Loading...

September 20, 2016

Awesome Asciidoctor: Change Level Offset For Included Documents

When we use the include directive to include another document we can must make sure the included document fits the levels of our main document. For example the included document shouldn't have level 0 headings if the main document already contains a level 0 heading. We can change the level offset in the main document before including another document. This will change the heading levels for the included document so all heading rules are okay.

To change the level offset we use the document attribute leveloffset. It is best to use a relative value, so if the included document also contains included document the output will still be okay and the heading rules still apply. Alternatively we can use the leveloffset attribute for the include directive. In the following sample document we include other files with a level 0 heading:

// File: book.adoc
= Include other files
// Include section numbers.
:sectnums:

// The file `chapter1.adoc` has a level 0 heading.
// To make sure it can be included we
// increase the level offset.
:leveloffset: +1

include::chapter1.adoc[]

// Reset level offset.
:leveloffset: -1
// Or use :leveloffset: 0

// We can also use the `leveloffset` attribute
// of the `include` directive. The level offset
// is then automatically reset.
include::chapter2.adoc[leveloffset=+2]

Here is the source for the included files:

// File: chapter1.adoc
= First chapter

Sample document to be included.
// File: chapter2.adoc
= First chapter

Sample document to be included.

When we transform book.adoc to HTML with Asciidoctor we get the following result:


Written with Asciidoctor 1.5.4.

Gradle Goodness: Use Command Line Options With Custom Tasks

Suppose we have a custom task with some properties that can be configured. Normally we would add the configuration in the build script. But we can also use command line options to configure a task. So when we run the task from the command line we can provide a configuration value for the task on the command line. To see which command line options are available for a task we can use the Gradle built-in task help followed by the option --task and the task name. To indicate a property as command line option we use a @Option annotation. We can specify the name of the command line option, a short description and also the order that is used to display the options with the help task.

Let's create a sample custom task and use the @Option annotation. In the following build file we create a custom task GenerateVersionFile. This task generates a file with a default name of version.txt in the build/ directory. The file contains the project version value. We make the property that defines the output filename as a command line option. This way the name can be defined when we run Gradle (and still of course using the default configuration in a build file).

// Import Option annotation
import org.gradle.api.internal.tasks.options.Option

version = 'demo'

// Create a task of the custom task type GenerateVersionFile.
task generateVersionFile(type: GenerateVersionFile)

/**
 * Custom task to generate a version value in a file.
 */
class GenerateVersionFile extends DefaultTask {
    
    String version

    // Specify outputFile property as
    // command line option.
    // Use as --outputFile filename.
    @Option(option = "outputFile", 
            description = "File to store the project version in",
            order = 1)
    Object outputFile
    
    GenerateVersionFile() {
        // Set default value for outputFile as version.txt.
        outputFile = 'version.txt'
        
        // Description for the task.
        description = 'Generate a file with the project version'
    }

    @TaskAction
    void generate() {
        // Create directory for the output file if 
        // it doesn't exist.
        final File versionFileDestination = getOutputFile()
        project.mkdir(versionFileDestination.parentFile)
        
        // Save version in file.
        versionFileDestination.text = getVersion()
    }

    @Input
    String getVersion() {
        return project.version
    }
    
    @OutputFile
    File getOutputFile() {
        return new File(project.buildDir, outputFile)
    }
    
}

If we run the help task for the generateVersionFile task we can see that our command line option is shown in the list of available options:

$ gradle help --task generationVersionFile
:help
Detailed task information for generateVersionFile

Path
     :generateVersionFile

Type
     GenerateVersionFile (GenerateVersionFile)

Options
     --outputFile     File where the project version is stored

Description
     Generate a file with the project version

Group
     -

BUILD SUCCESSFUL

Total time: 2.933 secs
$

Now we invoke the generateVersionFile task with a value for the command line option:

$ gradle generateVersionFile --outputFile version.saved
:generateVersionFile

BUILD SUCCESSFUL

Total time: 0.826 secs
$ more build/version.saved
demo
$

Written with Gradle 3.1.

September 19, 2016

Gradle Goodness: Change Gradle Wrapper Script Name

With the Gradle Wrapper task we can specify the name of the generated script files. By default the names are gradlew and gradlew.bat. The Wrapper task has the property scriptFile. We can set a different value for this property to let Gradle generate the script files with a different name.

In the following example we use the value mvnw (they will be surprised the build is so fast... ;-)) as the value:

task gradleWrapper(type: Wrapper) {
    scriptFile = 'mvnw'
}

Let's run the gradleWrapper task:

$ gradle gradleWrapper
:gradleWrapper

BUILD SUCCESSFUL

Total time: 8.597 secs
$ ls mvnw*
mvnw     mvnw.bat
$

Written with Gradle 3.1.

Gradle Goodness: Specify Wrapper Version and Distribution Type From Command Line

Gradle has the built-in task wrapper to create a Gradle wrapper. The Gradle wrapper can be part of our project so other people can build our project with Gradle, without the need for them to install Gradle. Also if we specify the Gradle wrapper we can make sure the correct Gradle version is used. To specify the version we must use the option --gradle-version. This version can be different than the Gradle version we use to create the Gradle wrapper. Since Gradle 3.1 we can also specify the distribution type of the Gradle wrapper. We choose between a binary distribution or the all distribution, which contains documentation and source code. Especially IDEs like to have the all distribution type, so they can provide better help in their editors.

With the following wrapper command we create a wrapper for Gradle 3.1 and the all distribution type. For a binary distribution we either use the value bin or we don't specify the option, so Gradle falls back to the default value bin.

$ gradle wrapper --gradle-version 3.1 --distribution-type all
:wrapper

BUILD SUCCESSFUL

Total time: 1.012 secs

$

We can check the file gradle/wrapper/gradle-wrapper.properties and look for the key distributionUrl. We see the value points to the correct Gradle version and distribution type:

$ more gradle/wrapper/gradle-wrapper.properties
#Mon Sep 19 15:26:27 CEST 2016
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-3.1-all.zip
$

Written with Gradle 3.1

September 16, 2016

Awesome Asciidoctor: Use Counters in Markup

In Asciidoctor we can create a document attribute as a counter attribute. The attribute is automatically incremented each time we use it in our markup. We can choose to use numbers or characters. Only latin characters from 'a' to 'z' or 'A' to 'Z' are allowed. By default the counter will start at 1, but we can define another start value when we use the counter attribute for the first time.

To define a counter attribute we must prefix the attribute name with counter:. Each time we use this syntax with the counter: prefix the value is incremented and displayed. To only display the current value, without incrementing, we simply refer to the document attribute without the counter: prefix. For example if we want to add a counter attribute with the name steps we would use the following markup in Asciidoctor: {counter:steps}.

To increment the counter without display it we must replace counter: with counter2:. The value of the attribute is incremented but not displayed. So to increment our steps attribute we would use the syntax: {counter2:steps}. To get the current value without incrementing we simply use {steps}.

To start with a different value than 1 we can suffix the attribute name with :<:start-value>. Let's look at how we would create the steps counter attribute starting from 100: {counter:steps:100}. To have a counter with letters we define the start value as a letter from which we want to count: {counter:steps:A}.

In the following example markup we see different usages of the counter support in Asciidoctor:

== Counters

In Asciidoctor we can use counters. To use them
we ({counter:usage}) use a document attribute
prefixed with `counter:` and ({counter:usage}) use it again
to increment the counter.

Instead of numbers we can use characters. To use them
we ({counter:usageChar:A}) use a document attribute
prefixed with `counter:` and suffix `:A` and ({counter:usageChar}) use it again
to increment the counter.

=== Current value

Current value for a counter can be obtained by just referring to document attribute name. 
Value counter is *{usage}*.

=== Increment

{counter2:usage} We can also increment the counter without displaying the value. 
On the next increment the value is *{counter:usage}*.

=== Start at

To start at another number than 1 we can specify the starting counter value as 
a suffix to the counter attribute as `:<start>`.

{counter:sample:10}. do something followed by {counter:sample}. something else.

When we transform this to HTML with Asciidoctor we get the following result:


Written with Asciidoctor 1.5.4.

Spocklight: Custom Default Responses for Stubs

Although I couldn't make it to Gr8Conf EU this year, I am glad a lot of the presentations are available as slide decks and videos. The slide deck for the talk Interesting nooks and crannies of Spock you (may) have never seen before by Marcin ZajÄ…czkowski is very interesting. This is really a must read if you use Spock (and why shouldn't you) in your projects. One of the interesting things is the ability to change the response for methods in a class that is stubbed using Spock's Stub method, but have no explicit stubbed method definition.

So normally when we create a stub we would add code that implements the methods from the stubbed class. In our specification the methods we have written are invoked instead of the original methods from the stubbed class. By default if we don't override a method definition, but it is used in the specification, Spock will try to create a response using a default response strategy. The default response strategy for a stub is implemented by the class EmptyOrDummyResponse. For example if a method has a return type Message then Spock will create a new instance of Message and return it to be used in the specification. Spock also has a ZeroOrNullResponse response strategy. With this strategy null is returned for our method that returns the Message type.

Both response strategies implement the IDefaultResponse interface. We can write our own response strategy by implementing this interface. When we use the Stub method we can pass an instance of our response strategy with the defaultResponse named argument of the method. For example: MessageProvider stub = Stub(defaultResponse: new CustomResponse()). We implement the respond
method of IDefaultResponse to write a custom response strategy. The method gets a IMockInvocation instance. We can use this instance to check for example the method name, return type, arguments and more. Based on this we can write code to return the response we want.

In the following example we have a Spock specification where we create a stub using the default response strategy, the ZeroOrNullResponse strategy and a custom written response strategy:

package com.mrhaki.spock

@Grab('org.spockframework:spock-core:1.0-groovy-2.4')
import spock.lang.Specification
import spock.lang.Subject
import org.spockframework.mock.ZeroOrNullResponse
import org.spockframework.mock.IDefaultResponse
import org.spockframework.mock.IMockInvocation

class SampleSpec extends Specification {

    def """stub default response returns
           instance of Message created with default constructor"""() {
        given: 'Use default response strategy EmptyOrDummyResponse'
        final MessageProvider messageProvider = Stub()
        final Sample sample = new Sample(messageProvider)

        expect:
        sample.sampleMessage == 'Sample says: default'
    }

    def "stub default reponse returns null with ZeroOrNullResponse"() {
        given: 'Use default response strategy of ZeroOrNullResponse'
        final MessageProvider messageProvider =
                Stub(defaultResponse: ZeroOrNullResponse.INSTANCE)
        final Sample sample = new Sample(messageProvider)

        when:
        sample.sampleMessage

        then: 'messageProvider.message returns null'
        thrown(NullPointerException)
    }

    def """stub default response returns
           Message object with initialized text property
           from StubMessageResponse"""() {
        given: 'Use custom default response strategy'
        final MessageProvider messageProvider =
                Stub(defaultResponse: new StubMessageResponse())
        final Sample sample = new Sample(messageProvider)

        expect:
        sample.sampleMessage == 'Sample says: *STUB MESSAGE TEXT*'
    }

}

/**
 * Class to test with a dependency on MessageProvider
 * that is stubbed in the specification.
 */
class Sample {
    private final MessageProvider messageProvider

    Sample(final MessageProvider messageProvider) {
        this.messageProvider = messageProvider
    }

    String getSampleMessage() {
        "Sample says: ${messageProvider.message.text}"
    }

    String sampleMessage(String prefix) {
        "Sample says: ${messageProvider.getMessageWithPrefix(prefix).text}"
    }
}

/**
 * Work with messages. This interface is stubbed
 * in the specification.
 */
interface MessageProvider {
    Message getMessage()
    Message getMessageWithPrefix(String prefix)
}

/**
 * Supporting class for MessageProvider.
 */
class Message {
    String text = 'default'
}

/**
 * Custom default response strategy.
 * When a method has a Message return type then we
 * create an instance of Message with a custom text
 * property value.
 * Otherwise rely on default behaviour.
 */
class StubMessageResponse implements IDefaultResponse {
    @Override
    Object respond(IMockInvocation invocation) {
        // If return type of method is Message we create
        // a new Message object with a filled text property.
        if (invocation.method.returnType == Message) {
            return new Message(text: '*STUB MESSAGE TEXT*')
        }

        // Otherwise use default response handler for Stubs.
        return ZeroOrNullResponse.INSTANCE.respond(invocation)
    }
}

Written with Spock 1.0-groovy-2.4.

September 15, 2016

Awesome Asciidoctor: Replacements For Text To Symbols

With Asciidoctor we can use text to describe a symbol in our markup. The text is automatically transformed to a Unicode replacement. For example if we use the text (C) it is converted to &#169; which is the copyright symbol: ©.

In the following sample we see all the symbol replacements:

Written with Asciidoctor 1.5.2.

September 14, 2016

Gradle Goodness: Lazy Project Property Evaluation

Sometime we need to define a project property in our Gradle build file for which the value must be evaluated later than the assignment. We can do this in different ways in Gradle. For example for a String type property we can rely on Groovy's support for lazy String evaluation. If the property is of a different type we can use Closure to define the value. The Closure code is not executed during the configuration phase directly, but we can write code to invoke the Closure at the right moment and get the value. Finally we can use the afterEvaluate method of the Project class to define a lazy property. Let's look at the different options we have with some code samples.

First we look at a lazy String property. We illustrate this with an example of a multi-project build with the following layout:

.
├── api
├── app
├── build.gradle
├── lib
└── settings.gradle

In our settings.gradle file we define the projects we want to be part of the root project:

include 'api'
include 'lib'
include 'app'

Let's create a build file with a lazy property buildVersion:

subproject {

    version = '1.0.0'

    // Use lazy String evaluation using
    // the ${->...} syntax. If we don't
    // make it lazy the value of project.version
    // is always 1.0.0, because that is the only
    // known value at this point and the changed value
    // in the app project is not noticed.
    ext.buildVersion = "${project.name}-${-> project.version}"

    task displayBuildVersion {
        description = 'Display value of buildVersion property'
        doFirst {
            println buildVersion
        }
    }

}

project('app') {
    // In the project app we define
    // a different value for the version
    // property. Remember this property
    // is used in the definition of the
    // buildVersion property.
    version = '1.0.3'
}

If we run the displayBuildVersion task we get the following output:

$ gradle -q displayBuildVersion

api-1.0.0
app-1.0.3
lib-1.0.0
$

If we have a property of another type than String we can use another mechanism to support lazy properties. We use a Closure to define the value and then invoke the Closure to calculate the value at a later time. In the next build script we add a support method lazyProperty to check if the property is defined with a Closure. If so we execute the Closure to calculate the value. Any other type is return as-is.

subprojects {

    ext {
        // Project property with Integer value.
        // Value is overriden in the 'app' project.
        port = 80

        // Value is lazy and depends on port
        // property. Port property can be overriden
        // later in the configuration phase of Gradle.
        // Using a Closure we can make the value
        // calculation at a later point in time.
        calculatedPort = { port + 10 }
    }

    task displayCalculatedPort {
        description = 'Display value of calculatedPort property'
        doFirst {
            print "Calculated port for ${project.name} "
            println lazyProperty(project, 'calculatedPort')
            // Alternative without support method:
            // println project.property('calculatedPort')()
            // Or even shorter:
            // println calculatedPort()
        }
    }

}

project('app') {
    // Override port property.
    ext.port = 8000
}

/**
 * Check if property value is a Closure. If so the value
 * is calculated by running the Closure and returned. 
 * Otherwise the value is returned without calculation.
 *
 * @param project Project containing the property to calculate.
 * @param propertyName Name of the property to calculate value for.
 */
def lazyProperty(final Project project, final String propertyName) {
    // Get property.
    def propertyValue = project.property(propertyName)

    // Check for type of property to see if we can
    // run it as a Closure.
    if (propertyValue instanceof Closure) {
        // Invoke Closure to calculate the value.
        propertyValue()
    } else {
        // Return value as-is.
        propertyValue
    }
}

Let's run the displayBuildVersion task and look at the output:

$ gradle -q displayCalculatedPort

Calculated port for api 90
Calculated port for app 8010
Calculated port for lib 90
$

Finally we use the afterEvaluate method:

subprojects {

    // Project property with Integer value.
    // Value is overriden in the 'app' project.
    ext.port = 80

    afterEvaluate {
        // Create calculatedPort property with
        // value at the latest moment.
        ext.calculatedPort = port + 10
    }

    task displayCalculatedPort {
        description = 'Display value of calculatedPort property'
        doFirst {
            print "Calculated port for ${project.name} "
            println calculatedPort
        }
    }

}

project('app') {
    // Override port property.
    ext.port = 8000
}

When we run the displayBuildVersion task and look at the output we see expected results:

$ gradle -q displayCalculatedPort

Calculated port for api 90
Calculated port for app 8010
Calculated port for lib 90
$

In our simple examples we used the lazy project property only in one task. We could have simply evaluated the value in the task definition as it is the only place where it is used. But if a property is used by other tasks and code in our build script we can rely on the mentioned solutions in this blog post.

Written with Gradle 3.0.

Gradle Goodness: Check The Gradle Daemon Status

Since Gradle 3 the Gradle daemon is automatically used to run Gradle. This means Gradle will startup up faster after a first run. Gradle tries to re-use a daemon if it is available. We can check the status of the Gradle daemon processes with the new command-line option --status. We get the status results for the Gradle daemons with the same Gradle version that is used to view the status. So when we use Gradle 3.0 with the --status option we only see the 3.0 Gradle daemons.

The following example shows the sample output of running gradle with the --status option:

$ gradle --status
No Gradle daemons are running.
   PID STATUS   INFO
 28914 IDLE     3.0
 26854 STOPPED  (after being idle for 22 minutes and to reclaim system memory)

Only Daemons for the current Gradle version are displayed. See https://docs.gradle.org/3.0/userguide/gradle_daemon.html#sec:status

Written with Gradle 3.0.

August 31, 2016

Check Which Candidates Can Be Updated With SDKMAN!

The Software Development Kit Manager (SDKMAN!) is an awesome and very useful tool. We can use it to install and manage candidates like Groovy, Grails, Griffon and Gradle. If we want to know if a new version of an installed candidate is available we use the outdated command. SKDMAN! returns a list of candidates with newer versions and also displays the version we have and is available. If we specify the candidate we can see if for that specific candidate a newer version is available.

For example we can get the following results:

$ sdk outdated
Outdated:
ant (1.9.6 < 1.9.7)
kotlin (1.0.0, 1.0.1, 1.0.2 < 1.0.3)
$ # Or we use the shortcut o
$ sdk o
Outdated:
ant (1.9.6 < 1.9.7)
kotlin (1.0.0, 1.0.1, 1.0.2 < 1.0.3)
$ # Check a specific candidate
$ sdk outdated ant
Outdated:
ant (1.9.6 < 1.9.7)
$

Written with SDKMAN! 5.0.0+51