October 18, 2017

PlantUML Pleasantness: Layout Elements With Hidden Lines

In a previous post we learned how to use a together block to keep elements together. We can also layout elements in a different way: using hidden lines. We define our elements and by using the keyword [hidden] in our line definition the elements are layout as if there was a line, but we don't see it. This gives us great flexibility on how we layout our elements.

In the following sample we first have a PlantUML definition where we rely on the default layout:

@startuml

package "Core Components" {
    [Backend Client] as BackendClient
    [File Reader] as FileReader
    [Content Transform] as ContentTransform
    [Logging]
}

BackendClient ~~> ContentTransform : uses
FileReader ~~> ContentTransform: uses

@enduml

This definition renders the following diagram:

We want the Logging component at the bottom right corner of the Core Components. Using a visible line we would connect the BackendClient to the Logging component. This would place the Logging component beneath the BackendClient, just like we want. So we add a connecting line and we add the [hidden] attribute on our line definition. The Logging component is placed where we want and we don't see the line supporting this:

@startuml

package "Core Components" {
    [Backend Client] as BackendClient
    [File Reader] as FileReader
    [Content Transform] as ContentTransform
    [Logging]
}

BackendClient ~~> ContentTransform : uses
FileReader ~~> ContentTransform: uses

' Layout Logging under BackendClient
BackendClient -[hidden]- Logging

@enduml

When we regenerate the diagram we get the result we want:

Written with PlantUML 1.2017.16.

October 17, 2017

PlantUML Pleasantness: Use Gradients In Diagrams

We have a lot of ways to customize our PlantUML diagrams. We can change the colors and we can even set gradients as color. A gradient has two colors and a direction. The direction of the gradient is set by the separator between the two colors. We can use the following separators to set the gradient direction:

  • /: direction top left to bottom right
  • \: direction bottom left to top right
  • |: direction left to right
  • -: direction top to bottom

In the following example PlantUML diagram definition we apply different gradient directions and different colors:

@startuml

title Gradient

skinparam defaultTextAlignment center
skinparam RectangleFontSize 20

skinparam TitleFontStyle bold
skinparam TitleFontColor #e723e7

' Define two colors for a gradient
' and use - for left to right.
skinparam BackgroundColor  #e2e2e2-#afafaf

' Define two colors for a gradient
' and use / for top left to bottom right.
skinparam RectangleBackgroundColor #ffd200/#8cfcff

rectangle A [
    From top left
    to bottom right
    <&fullscreen-enter>
]

' Use \ for bottom left to top right
rectangle B #ffd200\8cfcff [
    From bottom left
    to top right
    <&resize-both>
]

' Use | for left to right
rectangle C #ffd200|8cfcff [
    From left
    to right
    <&resize-width>
]

' Use | for top to bottom
rectangle D #ffd200-8cfcff [
    From top
    to bottom
    <&resize-height>
]

@enduml

When we convert this PlantUML syntax to a PNG image we get the following result:

Written with PlantUML 1.2017.16.

Groovy Goodness: Make Sure Closeable Objects Are Closed Using withCloseable Method

If a class implements the Closeable interface Groovy adds the withCloseable method to the class. The withCloseable method has a closure as argument. The code in the closure is executed and then the implementation of the close method of the Closeable interface is invoked. The Closeable object is passed as argument to the closure, so we can refer to it inside the closure.

In the following example we have two objects that implement the Closeable interface. By using withCloseable we know for sure the close method is invoked after all the code in the closure is executed:

@Grab(group='org.apache.httpcomponents', module='httpclient', version='4.5.3')
import org.apache.http.impl.client.HttpClientBuilder
import org.apache.http.client.methods.HttpGet

// HttpClientBuilder.create().build() returns a CloseableHttpClient
// that implements the Closeable interface. Therefore we can use
// the withCloseable method to make sure the client is closed
// after the closure code is executed. 
HttpClientBuilder.create().build().withCloseable { client ->
    final request = new HttpGet('http://www.mrhaki.com')

    // The execute method returns a CloseableHttpResponse object
    // that implements the Closeable interface. We can use
    // withCloseable method to make sure the response is closed
    // after the closure code is executed.
    client.execute(request).withCloseable { response ->
        assert response.statusLine.statusCode == 200
    }
}

Written with Groovy 2.4.12.

October 16, 2017

Awesome Asciidoctor: Use Only Block As List Item

When we define a list in Asciidoctor we usually have a list item that is a paragraph. But if we want to have a block as list item we need to add an extra {blank} element to make sure the block is parsed correctly as list item. Because a list item starts with a . or a * at the beginning of a line and a block also is defined on the beginning of the line, we must add the extra {blank} element. Together with the list item continuation (+) we can have a list with blocks.

In the following example we define a numbered list with three listing blocks:

= Simple steps

We need to type the following commands to generated a HTML version
of our Asciidoctor source document:

. {blank}
+
----
$ asciidoctor sample.adoc
$
----
. {blank}
+
----
$ ls
sample.adoc      sample.html
$
----
. {blank}
+
----
$ open sample.html
$
----

When we generate a HTML version we get the following result:

Written with Asciidoctor 1.5.6.1.

October 13, 2017

PlantUML Pleasantness: Align Multi-line Label Text

PlantUML has some features that come from the underlying software to create diagrams. Graphviz is used by PlantUML and we can use Graphviz features in our PlantUML diagrams. For example we can align multi-line text of labels to be either center (default), left or right aligned using a Graphviz feature. When we want to text to be center aligned we simply use the new-line character \n. If we want to have our text left aligned we use \l instead of \n. And to right align the text we use \r.

In the following example we have three labels that are center, left and right aligned:

@startuml

actor "Application User" as User

[Mail server] as Mail <<Mail>> #ffcc66

package "Sample Application" {
    [Controller] <<Spring REST controllers>>
    [Service] <<Spring service>>
}

' Label text is centered
User --> Controller : Types in\ndata to\nsend a message.

' Label text is left aligned
Controller --> Service : User data to\lcreate a\lnew message.

' Label text is right aligned
Service --> Mail : Mail message\robject containing\rall user information.

@enduml

When we run PlantUML with this diagram syntax we get the following diagram:

Written with PlantUML 1.2017.16.

October 12, 2017

Awesome Asciidoctor: Prevent Transformation of URL to Hyperlink

Normally if we type an URL in Asciidoctor that starts with a scheme Asciidoctor knows about, the URL is turned into a hyperlink. The following schemes are recognized by Asciidoctor:

  • http
  • https
  • ftp
  • irc
  • mailto
  • email@email.com

If we want to keep our URL as text and not a link we must prepend our URL with a backslash (\). This way Asciidoctor will not transform the URL to a hyperlink in our output.

In the following example we have URL that is transformed to a link, followed by the same URL but with a backslash (\) before it, that is not transformed:

== URL not as a link

The URL http://www.asciidoctor.org  should
be turned into a hyperlink.

But now the URL \http://www.asciidoctor.org should
just be text and not a hyperlink.

If we transform our document to HTML with Asciidoctor we get the following result:

Written with Asciidoctor 1.5.6.1.

October 5, 2017

Awesome Asciidoctor: Using Tab Separated Data In A Table

In a previous post we learned how to use data in CSV and DSV format. Recently we can also include tab separated values (TSV) in a Asciidoctor table. We must set the table attribute format to the value tsv. The data can be inside the document, but also defined in an external file which we add with the include macro.

In the following example markup we have a table with inline tab separated values. A second table includes an external file with tab delimited values:

= Tables

Using the `format` attribute value `tsv` we can
use tab-delimited data for table data.

== TSV table

[format=tsv, options="header"]
|===
Writing tools Awesomeness
Asciidoctor Oh yeah!
MS Word  No!
|===

== Table with external data

// We have an external file with 
// tab-delimited values.

[%header,format=tsv]
|===
include::tools.tsv[]
|===

When we convert our Asciidoctor markup to HTML we get the following result:

Written with Asciidoctor 1.5.6.1.

October 4, 2017

Awesome Asciidoctor: Grouping Floating Images

With Asciidoctor markup we can position images in our document. We can even float images, so text can next to an image, inside only below or about the image. We can also define multiple images to float, so the images are displayed on the same line next to each other. Any text that follows these images is also displayed next to the images. If we want only to have floating images, but the text starting under the images we can place the images inside an open block and assign the block the role float-group.

In the next example we first define three images that all have roles to float left. In the second part we group these images using the role float-group, so the text will not be displayed next to the images, but under the images:

:imagesdir: images/

= Grouping floats

// Images in open block to indicate 
// they belong together.
--
image::groovy.png[float="left"]
image::gradle.png[float="left"]
// Define float role, instead of attribute.
[.left]
image::grails.png[]
--

The images are all on one line,
but the text is next to the images.

If we want the images to be on one line,
but the text underneath them, we must use
a _float-group_ role, like in the
following example.

[.float-group]
--
image::groovy.png[float="left"]
image::gradle.png[float="left"]
// Define float role, instead of attribute.
[.left]
image::grails.png[]
--

The images above are all grouped together
to appear on one line.

And the text is not next to the images, but
underneath the images, like we wanted.

When we create a HTML document from the Asciidoctor markup we get the following result:

Written with Asciidoctor 1.5.6.1.

October 3, 2017

Awesome Asciidoctor: Using Paragraphs in Lists With List Item Continuation

When we write a list in Asciidoctor we can simply create a list item by starting the line with a dot (.). To create a another list item we simply start a new line with a dot (.). But what if we want to add a list item with multiple paragraphs, or text and a source code block element. We can use the list item continuation (+) to indicate to Asciidoctor we want to keep these together for a single list item.

In the following example we have a list in Asciidoctor markup. The second list item has multiple paragraphs , the third item has an extra admonition block and the fourth item contains a source code block:

:icons: font

== List continuation

When we have a list item that has for example multiple paragraphs,
we can use Asciidoctor's list continuation feature. We place a
`+` symbol between the paragraphs to indicate the paragraphs
belong to a single list item.

=== Sample list

. A very simple first item
. This item consists of two paragraphs.
+
By adding the `+` symbol we indicate this
paragraph also belongs to the second list item.
. We can even add for example an admonition.
+
TIP: Did you know Asciidoctor is awesome?
. A small code example:
+
[source,groovy]
----
println 'Groovy rocks!'
----
. Let's end with a simple list item.

Let's generate this Asciidoctor markup to HTML and we see the following result:

We see how the extra paragraph, admonition and source code are part of a single list item.

Written with Asciidoctor 1.5.6.1.

October 2, 2017

Spocklight: Reuse Variables In Data Providers

Writing a parameterized specification in Spock is easy. We need to add the where: block and use data providers to specify different values. For each set of values from the data providers our specifications is run, so we can test for example very effectively multiple input arguments for a method and the expected outcome. A data provider can be anything that implements the Iterable interface. Spock also adds support for a data table. In the data table we define columns for each variable and in the rows values for each variable. Since Spock 1.1 we can reuse the value of the variables inside the data provider or data table. The value of the variable can only be reused in variables that are defined after the variable we want to reuse is defined.

In the following example we have two feature methods, one uses a data provider and one a data table. The variable sentence is defined after the variable search, so we can use the search variable value in the definition of the sentence variable.

package mrhaki

import spock.lang.Specification
import spock.lang.Unroll

class CountOccurrencesSpec extends Specification {

    @Unroll('#sentence should have #count occurrences of #search (using data table)')
    void 'count occurrences of text using data table'() {
        expect:
        sentence.count(search) == count

        where:
        search  | sentence                                                  || count
        'ABC'   | "A simple $search"                                        || 1
        'Spock' | "Don't confuse $search framework, with the other $search" || 2
    }

    @Unroll('#sentence should have #count occurrences of #search (using data provider)')
    void 'count occurrences of text using data provider'() {
        expect:
        sentence.count(search) == count

        where:
        search << ['ABC', 'Spock']
        sentence << ["A simple $search", "Don't confuse $search framework, with the other $search"]
        count << [1, 2]
    }
}

When we run the specification the feature methods will pass and in we see in the @Unroll descriptions that the sentence variable uses the value of search:

Written with Spock 1.1-groovy-2.4.