Loading...

Thursday, December 11, 2014

Awesome Asciidoctor: Nested Delimited Blocks

In our Asciidoc markup we can include delimited blocks, like sidebars, examples, listings and admonitions. A delimited block is indicated by a balanced pair of delimiter characters. For example a sidebar starts and ends with four asterisk characters (****). If we want to nest another delimited block of the same type we must add an extra delimiter character at the start and end of the nested block. So when we want to nest another sidebar block inside an existing sidebar block we must use five asterisk characters (*****).

In the following example Asciidoc source we have several blocks with nested blocks:

== Nested sidebar

[sidebar]
.Sidebar
****
This is just an example of how
// Start nested block with extra *
*****
a nested delimited block
*****
can be defined.
****


== Nested example block

.Nested example
====
Also the example delimited block
// Start nested block
=====
allows nested blocks
======
and nested blocks
======
=====
to be defined.
====

== Nested admonition block

[NOTE]
====
We can nest
[TIP]
=====
adminition blocks
=====
as well.
====

== Mixing delimited blocks

[NOTE]
====
Of course we can also define 
****
another delimited block
*****
with nested block
*****
****
inside delimited blocks.
====

If we transform this to HTML we get the following result:






Written with Asciidoctor 1.5.2.

Tuesday, December 9, 2014

Gradle Goodness: Continue Build Even with Failed Tasks

If we run a Gradle build and one of the tasks fails, the whole build stops immediately. So we have fast feedback of our build status. If we don't want to this and want Gradle to execute all tasks, even though some might have failed, we use the command line option --continue. When we use the --continue command line option Gradle will execute every task where the dependent tasks are not failing. This is also useful in a multi-module project where we might want to build all projects even though some may have failing tests, so we get a complete overview of failed tests for all modules.

In the following Gradle build file we have two tasks. The task failTask throws a TaskExecutionException to purposely fail the task. The successTask will not fail:

task failTask << { task ->
    println "Running ${task.name}"

    throw new TaskExecutionException(
            task, 
            new Exception('Fail task on purpose')) 
}

task successTask << {
    println "Running ${it.name}"
}

Let's run both tasks from the command line and see the output:

$ gradle failTask successTask
:failTask
Running failTask
:failTask FAILED

FAILURE: Build failed with an exception.

* Where:
Build file '/Users/mrhaki/samples/gradle/continue/build.gradle' line: 4

* What went wrong:
Execution failed for task ':failTask'.
> Fail task on purpose

* Try:
Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output.

BUILD FAILED

Total time: 4.148 secs
$

We see the build has failed and only the task failTask is executed. Now we run the same two tasks, but we use the command line option --continue:

$ gradle --continue failTask successTask
:failTask
Running failTask
:failTask FAILED
:successTask
Running successTask

FAILURE: Build failed with an exception.

* Where:
Build file '/Users/mrhaki/samples/gradle/continue/build.gradle' line: 4

* What went wrong:
Execution failed for task ':failTask'.
> Fail task on purpose

* Try:
Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output.

BUILD FAILED

Total time: 6.918 secs
$

This time the successTask is executed even though the failTask has failed again. Gradle will keep track of all tasks that have failed and displays a summary with all the tasks that have failed.

Written with Gradle 2.2.1

Friday, December 5, 2014

Gradle Goodness: Skip Building Project Dependencies

If we use Gradle in a multi-module project we can define project dependencies between modules. Gradle uses the information from the project dependencies to determine which tasks need to be run. For example if module B depends on module A and we want to build module B, Gradle will also build module A for us, because module B depends on it. But if we know for sure that module A is up to date and has not changed, we can also instruct Gradle to skip building module A, when we build module B.

Let's start with the following module structure, where each module depends on the module above it. So module services depends on common and module web depends on services:

.
├── common
├── services
└── web

When we want to build the service module we go to the services directory and execute the build task and we get the following output:

$ gradle build
:common:compileJava 
:common:processResources 
:common:classes 
:common:jar 
:services:compileJava 
:services:processResources 
:services:classes 
:services:jar 
:services:assemble 
:services:compileTestJava 
:services:processTestResources 
:services:testClasses 
:services:test 
:services:check 
:services:build 

BUILD SUCCESSFUL

Total time: 8.013 secs

We see in the output that first the common module is build, because the services module depends on it. But if we work on this project and we know for sure the common module is up to date and has not changed since the last build (for example we didn't checkout new sources from version control or changed sources in the common module ourselves), then we can skip building the common module. We use the command line option -a or --no-rebuild to tell Gradle to skip project dependencies.

When we run the build task from the services directory using the command line option -a we get the following output:

$ gradle -a build
:services:compileJava 
:services:processResources 
:services:classes 
:services:jar 
:services:assemble 
:services:compileTestJava 
:services:processTestResources 
:services:testClasses 
:services:test 
:services:check 
:services:build 

BUILD SUCCESSFUL

Total time: 5.626 secs

This time only the services module is build, which also speeds up the build proces. Still this should only be used if we know ourselves the project dependencies are up to date.

Written with Gradle 2.2.1.

Thursday, December 4, 2014

Awesome Asciidoctor: Span Cell over Rows and Columns

When we define a table in Asciidoctor we might want to span a cell over multiple columns or rows, instead of just a single column or row. We can do this using a cell specifier with the following format: column-span.row-span+. The values for column-span and row-span define the number of columns and rows the cell must span. We put the cell specifier before the pipe symbol (|) in our table definition.

In the following example Asciidoctor markup we have three tables. In the first table we span a cell over 2 columns, the second table spans a cell over 2 rows and in the final table we span a cell over both 2 columns and rows.

== Table cell span

.Cell spans columns
|===
| Name | Description

| Asciidoctor
| Awesome way to write documentation

// This cell spans 2 columns, indicated
// by the number before the + sign.
// The + sign 
// tells Asciidoctor to span this
// cell over multiple columns.
2+| The statements above say it all

|=== 


.Cell spans rows
|===
| Name | Description

// This cell spans 2 rows,
// because the number after 
// the dot (.) specifies the number
// of rows to span. The + sign 
// tells Asciidoctor to span this
// cell over multiple rows.
.2+| Asciidoctor
| Awesome way to write documentation

| Works on the JVM

|=== 


.Cell spans both rows and columns
|===
| Col1 | Col2 | Col 3

// We can combine the numbers for
// row and column span within one
// cell specifier. 
// The number before the dot (.)
// is the number of columns to span,
// the number after the dot (.)
// is the number of rows to span. 
2.2+| Cell spans 2 cols, 2 rows
| Row 1, Col 3

| Row 2, Col 3

|===

If we transform our source to HTML we get the following tables:

Written with Asciidoctor 1.5.1.

Tuesday, December 2, 2014

Awesome Asciidoctor: Repeating Cell Contents

With Asciidoctor we can repeat cell contents if we prefix the cell separator pipe symbol (|) with the number of times we want to repeat the cell followed by an asterisk (*).

In the following example Asciidoctor source file we define two tables and add 2* to cells that we want to repeat two times:

// 3-column table, where the first column
// cell value is not repeated, and the
// cell value for columns 2 and 3 is 
// repeated.
|===
| Column | Value | Value

| Name 
2*| Asciidoctor

| Description 
2*| Awesome way to write documentation

|=== 


// One column table. So the repeated
// cells are each on their own row.
|===
| Column

2*| Asciidoctor

2*| Awesome way to write documentation

|=== 

When we generate a HTML document from this source we see the following result:

Written with Asciidoctor 1.5.1.

Wednesday, November 26, 2014

Awesome Asciidoctor: Disable Last Updated Text in Footer

When we transform our Asciidoc source files to HTML Asciidoctor will print the date and time the document was last updated in the footer. If we want to disable the Last updated text we disable the document attribute last-update-label.

In the following example Asciidoc file we disable the Last update label in the footer:

:last-update-label!:

= Change footer

To disable the _Last updated_ text
in the footer we disable the document
attribute `last-update-label`.

----
// Disable last updated text.
:last-update-label!:
----

When we transform this to HTML we get the following output:

Written with Asciidoctor 1.5.1.

Tuesday, November 25, 2014

Grails Goodness: Create New Application without Wrapper

Since the latest Grails versions a Grails wrapper is automatically created when we execute the create-app command. If we don't want the wrapper to be created we can use the command argument --skip-wrapper. If later we changed our mind and want the Grails wrapper we can simply run the wrapper command from our Grails application directory.

Let's run the create-app command with the --skip-wrapper argument. If we check the contents of the created directory we see that the wrapper files are not created:

$ grails create-app --skip-wrapper sample 
$ cd sample
$ ls
application.properties lib   src   web-app
grails-app  scripts   test
$

Written with Grails 2.4.4.

Awesome Asciidoctor: Using Document Fragments

Normally all Asciidoc files are processed and transformed to output files by Asciidoctor. But if we start the file name with an underscore (_) the file is not transformed to an output file. This is very useful, because we can define some Asciidoc document fragments and include them in other Asciidoc files, but in the output directory the document fragment is not generated.

Let's create two Asciidoc files. One is _attrs.adoc which is a document fragment file that is used in sample.doc:

// File: _attrs.adoc
:blogger_url: http://mrhaki.blogspot.com
:blogger_tag: Aweseome Asciidoctor
:author: mrhaki
// File: sample.adoc
include::_attrs.adoc[]

== Sample

Asciidoctor handles files starting
with an underscore (`_`) differently. The file is
not processed, but can be used in other Asciidoc
documents.

More {blogger_url}[blog posts] about
{blogger_tag} available written by {author}.

From the command line we can invoke the asciidoctor command. We also check the directory and see there is only the file sample.html:

$ asciidoctor sample.adoc
$ ls
_attrs.adoc sample.adoc sample.html
$

The following screenshot shows how the sample.html looks like in a web browser:

Written with Asciidoctor 1.5.1.

Monday, November 24, 2014

Gradle Goodness: Using and Working with Gradle Version

To get the current Gradle version we can use the gradleVersion property of the Gradle object. This returns a string value we can use for displaying the values. If we want to compare Gradle versions we can use the GradleVersion object. With this class we can get the current version, but we can also compare Gradle versions. This can be useful in our build scripts if we have functionality based on a Gradle version.

In the following build file we first have a task that uses the gradleVersion of Gradle. Then inside the task we use the static method current of the GradleVersion class. We get an GradleVersion instance and we display different properties from this instance. In the task compareGradleVersion we create a GradleVersion instance with the static version method. We compare multiple GradleVersion objects and have different functionality based on the Gradle version.

task printGradleVersion << {
    // Get current Gradle version as object.
    final GradleVersion gradleVersion = GradleVersion.current()

    // Print different properties.
    println "Your Gradle version is ${gradleVersion.version}"
    println "Base version: ${gradleVersion.baseVersion}"
    println "Build time  : ${gradleVersion.buildTime}"
    println "Build number: ${gradleVersion.buildNumber}"
    println "Commit id   : ${gradleVersion.revision}"
    println "Next major  : ${gradleVersion.nextMajor}"
    println "Snapshot?   : ${gradleVersion.snapshot}"
}

task compareGradleVersion << {
    // Current Gradle version.
    final GradleVersion gradleVersion = GradleVersion.current()

    // Gradle version 2.1 as GradleVersion object.
    final GradleVersion gradle2_1 = GradleVersion.version('2.1')

    // Compare versions.
    if (gradleVersion > gradle2_1) {
        println "Your Gradle version is newer than 2.1"
    } else if (gradleVersion == gradle2_1) {
        println "Your Gradle version is 2.1"
    } else {
        println "Your Gradle version is older than 2.1"
    }
}

When we run the tasks we get the following output:

$ gradle -q printGradleVersion
Gradle version is 2.2

Your Gradle version is 2.2
Base version: Gradle 2.2
Build time  : 2014-11-10 13:31:44 UTC
Build number: none
Commit id   : aab8521f1fd9a3484cac18123a72bcfdeb7006ec
Next major  : Gradle 3.0
Snapshot?   : false
$ gradle -q compareGradleVersion
Your Gradle version is newer than 2.1
$

Thanks to John Engelman who showed me this class on a pull request for the Gradle Grails plugin.

Written with Gradle 2.2.

Gradle Goodness: Using CopySpec with Tasks

To define a Copy task we specify the files we want to copy and to which directory. This definition is a CopySpec instance. It contains the rules that defines what we want to copy. The archive tasks Jar, Zip and Tar also use a CopySpec instance.

When we create a task of type Copy we get a task object that implements the CopySpec interface. We can use all the methods from this interface to extend our recipe for copying tasks. In the following build file we first define the task website. We use CopySpec methods to configure the task. Then we define a task deploy of type Sync that also implements the CopySpec interface.

// Create a new task of type Copy.
// The website task is of type Copy
// and this means it implements the
// CopySpec interface. 
task website(type: Copy) {
    into "${buildDir}/website"
    from 'src/webroot'

    into 'resources', {
        from 'src/assets'
    }
}

// We can use all CopySpec methods
// to add new specifications to 
// the existing specifications.
website.into('resources') {
    from 'src/javascript'
}

// The copySpec method creates 
// a CopySpec instance
// from the closure.
// The copySpec method is part of the
// Project object.
CopySpec manualSpec = copySpec {
    from('src/manual') {
        include '**/*.html'
    }
}
// And the with method accepts
// the CopySpec we created.
website.with(manualSpec)

// Print each file path
// that is copied.
website.eachFile { 
    println it.path
}

// New task of type Sync.
// The Sync task is also implementing
// the CopySpec interface.
// (Just like archive tasks: Zip, Tar, Jar)
task deploy(type: Sync) {
    destinationDir = file("${buildDir}/production")
    from website
}

// Use rename method from CopySpec.
deploy.rename { file ->
    if (file == 'index.html') {
        'main.html'
    } else {
        file
    }
}

// And finally the exclude method.
deploy.exclude 'man.html'

When we run the deploy task and look at the files in the build directory we see how our copy specifications are executed:

$ gradle deploy
:website
index.html
resources/app.js
resources/site.css
man.html
:deploy

BUILD SUCCESSFUL

Total time: 3.643 secs
$ tree build/
build
├── production
│   ├── main.html
│   └── resources
│       ├── app.js
│       └── site.css
└── website
    ├── index.html
    ├── man.html
    └── resources
        ├── app.js
        └── site.css

4 directories, 7 files

Written with Gradle 2.2.