Groovy 2.5.0 adds thetap method to all objects and changes the method signature of thewith method. In a previous post, we learned about the with method. In Groovy 2.5.0 we can add an extra boolean argument to thewithmethod. If the value is false, which is the default, thewith method must return the same value as the closure invocation returns. If the value is true, the object instance on which the with  method is invoked will be returned. The new tap method is an alias for with (true), so it will always return the object instance.

In the first example, we will use the tap method to create a new Sample object and set property values to invoke methods of the Sample class:

/**
 * Sample class with some properties
 * and a method.
 */
class Sample {

    String username, email

    List<String> labels = []

    void addLabel(value) {
        labels << value
    }
}

// Use tap method to create instance of
// Sample and set properties and invoke methods.
def sample =
        new Sample().tap {
            assert delegate.class.name == 'Sample'

            username = 'mrhaki'
            email = 'email@host.com'
            addLabel 'Groovy'
            addLabel 'Gradle'

            // We use tap, an alias for with(true),
            // so the delegate of the closure,
            // the Sample object, is returned.
        }

assert sample.labels == ['Groovy', 'Gradle']
assert sample.username == 'mrhaki'
assert sample.email == 'email@host.com'

In the following example, we will use the with method to demonstrate the differences for several invocations using different argument values:

/**
 * Sample class with some properties
 * and a method.
 */
class Sample {

    String username, email

    List<String> labels = []

    void addLabel(value) {
        labels << value
    }

}

// Use with method to create instance of
// Sample and set properties and invoke methods.
def sample1 =
        new Sample().with {
            assert delegate.class.name == 'Sample'

            username = 'mrhaki'
            email = 'email@host.com'
            addLabel 'Groovy'
            addLabel 'Gradle'  
        }

// With method returns the result
// from the closure. In the previous
// case the return result is null,
// because the last statement addLabel
// is used as return value. addLabel has
// return type void.
assert !sample1


// Use with method to create instance of
// Sample and set properties and invoke methods.
def sample2 =
        new Sample().with {
            assert delegate.class.name == 'Sample'

            username = 'mrhaki'
            email = 'email@host.com'
            addLabel 'Groovy'
            addLabel 'Gradle'

            // Explicitly return delegate of
            // closure, which is the Sample object.
            return delegate
        }

assert sample2.labels == ['Groovy', 'Gradle']
assert sample2.username == 'mrhaki'
assert sample2.email == 'email@host.com'


// Use with method to create instance of
// Sample and set properties and invoke methods.
def sample3 =
        new Sample().with(true) {
            assert delegate.class.name == 'Sample'

            username = 'mrhaki'
            email = 'email@host.com'
            addLabel 'Groovy'
            addLabel 'Gradle'

            // We use with(true), so the
            // delegate of the closure, the Sample
            // object, is returned.
        }

assert sample3.labels == ['Groovy', 'Gradle']
assert sample3.username == 'mrhaki'
assert sample3.email == 'email@host.com'

A good use case for using the with method is to transform an object to another type using values from the object. In the next example, we use values from a Sample object to create a new String:

/**
 * Sample class with some properties
 * and a method.
 */
class Sample {
    String username, email
    List<String> labels = []
    void addLabel(value) {
        labels << value
    }
}

def sample =
        new Sample().tap {
            username = 'mrhaki'
            email = 'email@host.com'
            addLabel 'Groovy'
            addLabel 'Gradle'
        }

// The with method can be very useful to
// transform object to another type using
// values from the object.
def user = sample.with { "$username likes ${labels.join(', ')}." }

assert user == 'mrhaki likes Groovy, Gradle.'

Written with Groovy 2.5.0.