Groovy Command Chain DSL

Q: Can I use Groovy command chains with @CompileStatic?

Command chains have limited support under @CompileStatic. Basic command expressions (dropping parentheses on a single call) generally work, but complex multi-link chains may not be fully supported because @CompileStatic needs explicit type information at each step. For DSL-heavy code that relies on command chains, you typically use dynamic Groovy and keep @CompileStatic for performance-critical business logic.

Groovy Command Chain – Build Natural Language DSLs with 10 Examples

March 14, 2026

Groovy command chains to build natural language DSLs. 10+ examples covering method chaining without dots, named parameters. Groovy 5.x.

“Good code reads like well-written prose. Groovy command chains take that philosophy and make it literal.”
Dierk König, Groovy in Action

Last Updated: March 2026 | Tested on: Groovy 5.x, Java 17+ | Difficulty: Intermediate to Advanced | Reading Time: 22 minutes

Have you ever looked at a piece of code and wished it read more like English? With Groovy command chains, that is exactly what you can achieve. Command chains let you call methods without dots or parentheses, turning code into something that looks remarkably like natural language.

Instead of writing move(robot).to(position).at(speed), you can write move robot to position at speed. That is not pseudocode — that is actual, runnable Groovy. This feature is what makes Groovy one of the best languages for building domain-specific languages (DSLs).

In this tutorial, we will explore how Groovy command chain expressions work, build readable DSLs from scratch, work with named parameters and command expressions, and look at real-world applications in configuration builders and test frameworks. You will be writing code that your non-developer colleagues can almost read.

What Are Groovy Command Chains?

A Groovy command chain is a feature that allows you to chain method calls together by alternating between method names and their arguments, without using dots (.) or parentheses (()). The Groovy parser interprets a sequence of tokens as alternating method-argument pairs.

According to the official Groovy style guide, command chains were introduced in Groovy 1.8 and are the foundation for creating expressive, natural-language-like DSLs. The feature builds on Groovy’s existing support for optional parentheses in top-level method calls.

Key Points:

Command chains alternate between method names and arguments: method arg method arg
No dots or parentheses are needed between chained calls
Each method must return an object that has the next method in the chain
Arguments can be single values, maps (named parameters), or closures
They work best for DSL-style APIs where readability is the top priority
Parentheses-free calls were already supported for single method calls — command chains extend this to multiple chained calls

Traditional Syntax	Command Chain Syntax	Equivalent To
`move(robot).to(target)`	`move robot to target`	Same result
`paint(wall).with(color)`	`paint wall with color`	Same result
`take(5).elements()`	`take 5 elements`	Uses no-arg method
`send("Hello").to("Alice")`	`send "Hello" to "Alice"`	Same result

How Command Chains Work

The magic behind command chains is surprisingly simple. Groovy parses a sequence of alternating identifiers and expressions as chained method calls. Here is the rule:

a b c d e f is parsed as a(b).c(d).e(f).

The first token (a) is a method call with b as its argument. That call returns an object, and c is called on that object with d as the argument, and so on. If a method takes no arguments, you use an empty pair of parentheses in the odd positions or use a property-like syntax.

Basic Command Chain Parsing

// Step 1: Understand the parsing rule
// a b c d  =>  a(b).c(d)

// Let's prove it with a simple example
class ChainDemo {
    String value

    ChainDemo say(String msg) {
        println "Say: $msg"
        return this
    }

    ChainDemo to(String person) {
        println "To: $person"
        return this
    }

    ChainDemo and(String extra) {
        println "And: $extra"
        return this
    }
}

def demo = new ChainDemo()

// Traditional syntax with dots and parens
demo.say("hello").to("world").and("goodbye")

println "---"

// Command chain syntax - same result
demo.say "hello" to "world" and "goodbye"

Output

Say: hello
To: world
And: goodbye
---
Say: hello
To: world
And: goodbye

What happened here: Both forms produce identical results. The command chain demo.say "hello" to "world" and "goodbye" is parsed as demo.say("hello").to("world").and("goodbye"). The first method in the chain still needs the dot on the receiver object, but after that, the alternating pattern takes over. Each method returns this to enable the chain to continue.

10 Practical Command Chain Examples

Example 1: Basic Command Expression (No Parentheses)

What we’re doing: Starting with the simplest form — calling methods without parentheses, which is the foundation of command chains.

Example 1: Basic Command Expression

// In Groovy, top-level method calls don't need parentheses
// This is the starting point for command chains

// Traditional
println("Hello, World!")

// Command expression - no parentheses
println "Hello, World!"

// Works with any method
def greet(String name) {
    return "Hello, $name!"
}

// Traditional
def result1 = greet("Alice")
println result1

// Command expression
def result2 = greet "Bob"
println result2

// Multiple arguments still work
def add(int a, int b) {
    return a + b
}

println add(3, 4)   // traditional
println(add(3, 4))  // nested calls need parentheses - command chains can't nest

Output

Hello, World!
Hello, World!
Hello, Alice!
Hello, Bob!
7
7

What happened here: Groovy allows you to drop parentheses on top-level method calls. This works for any method with at least one argument. The call println "Hello" is exactly the same as println("Hello"). This is the building block upon which command chains are built — once you are comfortable dropping parentheses on single calls, chaining them becomes natural.

Example 2: Two-Part Command Chain

What we’re doing: Building a simple two-method command chain where one method returns an object for the next call.

Example 2: Two-Part Command Chain

// Build a simple "send message to person" chain

class Messenger {
    def send(String message) {
        // Return a helper object that has the 'to' method
        return new MessageTarget(message: message)
    }
}

class MessageTarget {
    String message

    def to(String recipient) {
        println "Sending '$message' to $recipient"
        return "Message delivered to $recipient"
    }
}

def messenger = new Messenger()

// Traditional syntax
messenger.send("Hello").to("Alice")

// Command chain syntax
messenger.send "Goodbye" to "Bob"

// You can also store the result
def status = messenger.send "Update" to "Charlie"
println "Status: $status"

Output

Sending 'Hello' to Alice
Sending 'Goodbye' to Bob
Sending 'Update' to Charlie
Status: Message delivered to Charlie

What happened here: The send method returns a MessageTarget object that has the to method. When Groovy sees messenger.send "Goodbye" to "Bob", it parses it as messenger.send("Goodbye").to("Bob"). The chain flows naturally because each method returns the right type of object for the next call. This is the core design pattern for building command-chain-friendly APIs.

Example 3: Three-Part Chain with Fluent API

What we’re doing: Extending the chain to three methods, creating a more expressive sentence-like API.

Example 3: Three-Part Command Chain

// "paint <wall> with <color> using <brush>"

class Painter {
    def paint(String surface) {
        return new PaintSurface(surface: surface)
    }
}

class PaintSurface {
    String surface

    def with(String color) {
        return new PaintJob(surface: surface, color: color)
    }
}

class PaintJob {
    String surface
    String color

    def using(String tool) {
        println "Painting $surface with $color using a $tool"
        return this
    }
}

def painter = new Painter()

// Traditional
painter.paint("ceiling").with("white").using("roller")

// Command chain - reads like English!
painter.paint "wall" with "blue" using "brush"
painter.paint "fence" with "green" using "spray gun"
painter.paint "door" with "red" using "small brush"

Output

Painting ceiling with white using a roller
Painting wall with blue using a brush
Painting fence with green using a spray gun
Painting door with red using a small brush

What happened here: We built a three-link chain: paint returns a PaintSurface, which has with that returns a PaintJob, which has using. The chain painter.paint "wall" with "blue" using "brush" reads almost like a natural instruction. This pattern scales well — you can add more links by having each class return an appropriate object for the next step.

Example 4: Using Maps as Named Parameters

What we’re doing: Combining command chains with Groovy’s named parameter syntax for even more readable DSLs.

Example 4: Named Parameters in Chains

// Named parameters (maps) make command chains even more readable

class TaskBuilder {
    def create(Map params) {
        def task = new Task(name: params.task ?: 'unnamed')
        return task
    }
}

class Task {
    String name
    String assignee
    int priority

    def assign(Map params) {
        this.assignee = params.to
        return this
    }

    def with(Map params) {
        this.priority = params.priority ?: 0
        println "Task: '$name' assigned to $assignee (priority: $priority)"
        return this
    }
}

def builder = new TaskBuilder()

// Using maps as named parameters in the chain
builder.create task: "Fix bug" assign to: "Alice" with priority: 1
builder.create task: "Write tests" assign to: "Bob" with priority: 2
builder.create task: "Deploy app" assign to: "Charlie" with priority: 3

println "---"

// You can also mix strings and maps
class EmailBuilder {
    def email(String subject) {
        return new EmailDraft(subject: subject)
    }
}

class EmailDraft {
    String subject

    def to(String recipient) {
        println "Email: '$subject' -> $recipient"
        return this
    }
}

def mail = new EmailBuilder()
mail.email "Meeting Tomorrow" to "team@example.com"
mail.email "Bug Report" to "dev@example.com"

Output

Task: 'Fix bug' assigned to Alice (priority: 1)
Task: 'Write tests' assigned to Bob (priority: 2)
Task: 'Deploy app' assigned to Charlie (priority: 3)
---
Email: 'Meeting Tomorrow' -> team@example.com
Email: 'Bug Report' -> dev@example.com

What happened here: Groovy’s map literal syntax (key: value) works beautifully in command chains. When Groovy sees create task: "Fix bug", it passes [task: "Fix bug"] as a Map argument to the create method. This is what makes Groovy DSLs so powerful — you get keyword-argument-style syntax without any extra framework or library.

Example 5: No-Arg Methods in Chains (Property Syntax)

What we’re doing: Handling methods that take no arguments in the middle of a command chain using Groovy’s property access syntax.

Example 5: No-Arg Methods in Chains

// In command chains, odd-positioned tokens are methods and
// even-positioned tokens are arguments.
// For no-arg methods, use the property access pattern (getter).

class NumberChain {
    int value

    NumberChain take(int n) {
        this.value = n
        return this
    }

    // No-arg method accessed as a property
    NumberChain getDoubled() {
        this.value = this.value * 2
        return this
    }

    NumberChain getSquared() {
        this.value = this.value * this.value
        return this
    }

    NumberChain plus(int n) {
        this.value = this.value + n
        return this
    }

    String toString() { "Result: $value" }
}

def calc = new NumberChain()

// Using property syntax for no-arg methods
// Note: take(5).doubled works - the dot binds to the return value
calc.take(5).doubled.squared
println calc  // 5 * 2 = 10, 10 * 10 = 100

calc.take(3).doubled
println calc  // 3 * 2 = 6

calc.take(4).squared
println calc  // 4 * 4 = 16

// Another approach: use a marker object
class Timer {
    int seconds

    Timer wait(int n) {
        this.seconds = n
        return this
    }

    // "seconds" acts as a no-arg method that just returns this
    Timer getSeconds() {
        println "Waiting for ${this.seconds} seconds..."
        return this
    }

    Timer then(Closure action) {
        action()
        return this
    }
}

def timer = new Timer()
timer.wait(5).seconds
timer.wait(10).seconds

Output

Result: 100
Result: 6
Result: 16
Waiting for 5 seconds...
Waiting for 10 seconds...

What happened here: When you need a no-argument method in a command chain, you can use Groovy’s property access convention. A method named getDoubled() can be accessed as the property .doubled. This is how you insert “connector words” in your DSL that do not take arguments. The trick is that the no-arg link must use dot notation (since the command chain pattern requires arguments in even positions).

Example 6: Building a Query DSL

What we’re doing: Creating a SQL-like query DSL using command chains — a classic use case for this feature.

Example 6: Query DSL

// Build a simple SQL-like query DSL

class QueryBuilder {
    String table
    String condition
    String sortField
    int limitCount = -1

    def select(String columns) {
        return new SelectClause(columns: columns, builder: this)
    }
}

class SelectClause {
    String columns
    QueryBuilder builder

    def from(String table) {
        builder.table = table
        return new FromClause(columns: columns, builder: builder)
    }
}

class FromClause {
    String columns
    QueryBuilder builder

    def where(String condition) {
        builder.condition = condition
        return new WhereClause(columns: columns, builder: builder)
    }

    String toString() {
        "SELECT $columns FROM ${builder.table}"
    }
}

class WhereClause {
    String columns
    QueryBuilder builder

    def orderBy(String field) {
        builder.sortField = field
        return new OrderClause(columns: columns, builder: builder)
    }

    String toString() {
        "SELECT $columns FROM ${builder.table} WHERE ${builder.condition}"
    }
}

class OrderClause {
    String columns
    QueryBuilder builder

    def limit(int n) {
        builder.limitCount = n
        return new FinalQuery(columns: columns, builder: builder)
    }

    String toString() {
        "SELECT $columns FROM ${builder.table} WHERE ${builder.condition} ORDER BY ${builder.sortField}"
    }
}

class FinalQuery {
    String columns
    QueryBuilder builder

    String toString() {
        "SELECT $columns FROM ${builder.table} WHERE ${builder.condition} ORDER BY ${builder.sortField} LIMIT ${builder.limitCount}"
    }
}

def query = new QueryBuilder()

// Command chain builds a readable query
def q1 = query.select "*" from "users" where "age > 18" orderBy "name" limit 10
println q1

def q2 = new QueryBuilder().select "name, email" from "customers" where "active = true"
println q2

def q3 = new QueryBuilder().select "COUNT(*)" from "orders"
println q3

Output

SELECT * FROM users WHERE age > 18 ORDER BY name LIMIT 10
SELECT name, email FROM customers WHERE active = true
SELECT COUNT(*) FROM orders

What happened here: We built a chain of classes, each representing a SQL clause. The command chain select "*" from "users" where "age > 18" orderBy "name" limit 10 reads almost exactly like SQL. Each method returns the next clause object, ensuring the chain can only proceed in a valid order. This is one of the most powerful patterns for command chains — using the type system to enforce the grammar of your DSL.

Example 7: Closure Arguments in Chains

What we’re doing: Using closures as arguments in command chains to add logic and behavior to your DSL.

Example 7: Closures in Command Chains

// Closures can be arguments in command chains

class EventHandler {
    String eventName

    def on(String event) {
        this.eventName = event
        return this
    }

    def execute(Closure action) {
        println "Event '$eventName' triggered:"
        action()
        return this
    }

    // Alias for more readable chaining
    def then(Closure action) {
        return execute(action)
    }
}

def handler = new EventHandler()

// Closure as the last argument in a command chain
handler.on "click" execute {
    println "  Button clicked!"
    println "  Updating UI..."
}

println "---"

handler.on "submit" then {
    println "  Form submitted!"
    println "  Validating data..."
}

println "---"

// Multiple closures with a builder pattern
class RuleEngine {
    def when(Closure condition) {
        return new RuleAction(condition: condition)
    }
}

class RuleAction {
    Closure condition

    def then(Closure action) {
        if (condition()) {
            println "Rule matched! Executing action..."
            action()
        } else {
            println "Rule did not match."
        }
    }
}

def rules = new RuleEngine()
def temperature = 35

rules.when { temperature > 30 } then {
    println "  It's hot! Turn on AC."
}

temperature = 15
rules.when { temperature > 30 } then {
    println "  It's hot! Turn on AC."
}

Output

Event 'click' triggered:
  Button clicked!
  Updating UI...
---
Event 'submit' triggered:
  Form submitted!
  Validating data...
---
Rule matched! Executing action...
  It's hot! Turn on AC.
Rule did not match.

What happened here: Closures integrate directly into command chains. When Groovy sees handler.on "click" execute { ... }, it parses it as handler.on("click").execute({ ... }). The closure is treated as an argument, just like a string or number. The rule engine example shows a particularly powerful pattern: when { condition } then { action } — this is how frameworks like Spock build their readable test specifications.

Example 8: Using ‘with’ for DSL Scoping

What we’re doing: Combining command chains with Groovy’s with method to scope method calls inside a configuration block.

Example 8: DSL Scoping with ‘with’

// Using 'with' to scope method calls in a DSL

class ServerConfig {
    String host = 'localhost'
    int port = 8080
    String protocol = 'http'
    boolean ssl = false
    List<String> routes = []

    def host(String h) { this.host = h; return this }
    def port(int p) { this.port = p; return this }
    def protocol(String pr) { this.protocol = pr; return this }
    def enableSsl() { this.ssl = true; return this }

    def route(String path) {
        routes << path
        return this
    }

    String toString() {
        def base = "${protocol}://${host}:${port}"
        def sslStr = ssl ? " [SSL]" : ""
        return "Server: ${base}${sslStr}\nRoutes: ${routes}"
    }
}

// Using 'with' for configuration block
def server = new ServerConfig().with {
    host 'api.example.com'
    port 443
    protocol 'https'
    enableSsl()
    route '/users'
    route '/products'
    route '/orders'
    it  // return the config object
}

println server

println "\n---"

// Another example: build a person object
class Person {
    String name
    int age
    String city
    List<String> hobbies = []

    def name(String n) { this.name = n; return this }
    def age(int a) { this.age = a; return this }
    def livesIn(String c) { this.city = c; return this }
    def likes(String hobby) { hobbies << hobby; return this }

    String toString() { "$name (age $age) from $city, likes: $hobbies" }
}

def person = new Person().with {
    name 'Alice'
    age 30
    livesIn 'New York'
    likes 'coding'
    likes 'hiking'
    likes 'reading'
    it
}

println person

Output

Server: https://api.example.com:443 [SSL]
Routes: [/users, /products, /orders]

---
Alice (age 30) from New York, likes: [coding, hiking, reading]

What happened here: The with method sets the delegate of the closure to the object itself, so every unqualified method call inside the closure is dispatched to the server config or person object. Inside the block, host 'api.example.com' is a command expression that calls this.host('api.example.com'). This pattern is used everywhere in Groovy frameworks — Gradle build scripts, Grails configurations, and Jenkins pipelines all use this approach.

Example 9: Arithmetic and Unit-Like DSLs

What we’re doing: Creating unit-like expressions where numbers and words combine to form meaningful commands.

Example 9: Unit-Like DSL

// Add methods to Integer to create unit-like expressions

// Using metaprogramming to add DSL methods
Integer.metaClass.getSeconds = { -> delegate * 1000L }
Integer.metaClass.getMinutes = { -> delegate * 60 * 1000L }
Integer.metaClass.getHours   = { -> delegate * 60 * 60 * 1000L }
Integer.metaClass.getDays    = { -> delegate * 24 * 60 * 60 * 1000L }

// Now we can write time expressions naturally
println "5 seconds = ${5.seconds} ms"
println "2 minutes = ${2.minutes} ms"
println "1 hour = ${1.hours} ms"
println "3 days = ${3.days} ms"

println "\n--- Distance DSL ---"

// Distance unit DSL
Integer.metaClass.getKm = { -> delegate * 1000.0 }
Integer.metaClass.getMeters = { -> delegate * 1.0 }
Integer.metaClass.getMiles = { -> delegate * 1609.34 }

def distanceInMeters = 5.km
println "5 km = ${distanceInMeters} meters"
println "3 miles = ${3.miles} meters"
println "500 meters = ${500.meters} meters"

println "\n--- Money DSL ---"

// Money DSL
class Money {
    double amount
    String currency

    Money(double amount, String currency) {
        this.amount = amount
        this.currency = currency
    }

    Money plus(Money other) {
        if (currency != other.currency) throw new IllegalArgumentException("Currency mismatch")
        return new Money(amount + other.amount, currency)
    }

    String toString() { "${currency} ${String.format('%.2f', amount)}" }
}

Integer.metaClass.getDollars = { -> new Money(delegate, 'USD') }
Integer.metaClass.getEuros   = { -> new Money(delegate, 'EUR') }
Double.metaClass.getDollars  = { -> new Money(delegate, 'USD') }

println 100.dollars
println 50.euros
println 100.dollars + 50.dollars

Output

5 seconds = 5000 ms
2 minutes = 120000 ms
1 hour = 3600000 ms
3 days = 259200000 ms

--- Distance DSL ---
5 km = 5000.0 meters
3 miles = 4828.02 meters
500 meters = 500.0 meters

--- Money DSL ---
USD 100.00
EUR 50.00
USD 150.00

What happened here: By adding property-style getters to Integer via metaClass, we created expressions like 5.seconds and 100.dollars that read like natural language. This is a powerful pattern for DSLs that deal with measurements, currencies, or any domain where numbers have units. Groovy’s dynamic nature makes this kind of extension trivial — no wrapper classes or operator overloading needed for the basic cases.

Example 10: Combining Command Chains with Closures and Maps

What we’re doing: Building a full-featured DSL that combines all the command chain techniques — maps, closures, chaining, and scoping.

Example 10: Full-Featured DSL

// Build a pipeline DSL that combines everything

class Pipeline {
    List<Map> steps = []

    def step(String name) {
        return new StepBuilder(pipeline: this, stepName: name)
    }

    def run() {
        println "=== Pipeline Execution ==="
        steps.eachWithIndex { step, idx ->
            println "Step ${idx + 1}: ${step.name}"
            if (step.action) {
                step.action()
            }
            println "  Timeout: ${step.timeout ?: 'default'}"
            println ""
        }
    }
}

class StepBuilder {
    Pipeline pipeline
    String stepName
    String timeoutVal
    Closure actionClosure

    def timeout(String t) {
        this.timeoutVal = t
        return this
    }

    def execute(Closure action) {
        pipeline.steps << [
            name: stepName,
            timeout: timeoutVal,
            action: action
        ]
        return pipeline
    }
}

def pipeline = new Pipeline()

// Build a CI/CD pipeline using command chains
pipeline.step "Checkout Code" timeout "30s" execute {
    println "  Cloning repository..."
}

pipeline.step "Run Tests" timeout "5m" execute {
    println "  Running unit tests..."
    println "  42 tests passed, 0 failed"
}

pipeline.step "Build Artifact" timeout "10m" execute {
    println "  Compiling source..."
    println "  Creating JAR file..."
}

pipeline.step "Deploy" timeout "2m" execute {
    println "  Deploying to staging..."
    println "  Health check passed"
}

// Run the pipeline
pipeline.run()

Output

=== Pipeline Execution ===
Step 1: Checkout Code
  Cloning repository...
  Timeout: 30s

Step 2: Run Tests
  Running unit tests...
  42 tests passed, 0 failed
  Timeout: 5m

Step 3: Build Artifact
  Compiling source...
  Creating JAR file...
  Timeout: 10m

Step 4: Deploy
  Deploying to staging...
  Health check passed
  Timeout: 2m

What happened here: This pipeline DSL combines everything we have learned. The chain pipeline.step "Checkout Code" timeout "30s" execute { ... } is parsed as pipeline.step("Checkout Code").timeout("30s").execute({ ... }). This is exactly the pattern used by tools like Jenkins Pipeline (Jenkinsfile), where build configurations read as a sequence of declarative steps. The power of command chains really shines in these infrastructure-as-code scenarios.

Bonus Example 11: Top-Level Functions as DSL Entry Points

What we’re doing: Using script-level functions as entry points for command chains, so the chain starts without any receiver object.

Bonus: Top-Level DSL Entry Points

// Define top-level functions that start command chains
// In a Groovy script, these are accessible without any object prefix

class Delivery {
    String item
    String destination

    def to(String dest) {
        this.destination = dest
        println "Delivering $item to $destination"
        return this
    }
}

class Assertion {
    Object actual

    def is(Object expected) {
        def result = actual == expected
        println "Assert: $actual == $expected -> $result"
        assert actual == expected
        return this
    }

    def isGreaterThan(Object expected) {
        def result = actual > expected
        println "Assert: $actual > $expected -> $result"
        assert actual > expected
        return this
    }
}

// Top-level functions
def deliver(String item) {
    return new Delivery(item: item)
}

def expect(Object value) {
    return new Assertion(actual: value)
}

// Now use them as command chain entry points
deliver "package" to "warehouse"
deliver "letter" to "post office"
deliver "groceries" to "home"

println "---"

expect 42 is 42
expect 10 isGreaterThan 5

println "\n--- All assertions passed! ---"

Output

Delivering package to warehouse
Delivering letter to post office
Delivering groceries to home
---
Assert: 42 == 42 -> true
Assert: 10 > 5 -> true

--- All assertions passed! ---

What happened here: Script-level functions like deliver and expect serve as natural entry points for command chains. Since they are already at the top level, you do not need a receiver object to start the chain. The call deliver "package" to "warehouse" is pure command chain, parsed as deliver("package").to("warehouse"). The expect function shows how testing frameworks like Spock can create assertion DSLs that read like natural language.

Building a Real-World Configuration DSL

Let us build a more realistic example — a configuration DSL similar to what you would see in a Gradle build file or a Grails configuration. This shows how command chains work alongside closure-based configuration blocks in production code.

Real-World Configuration DSL

class AppConfig {
    String appName
    String version
    Map database = [:]
    Map server = [:]
    List<String> features = []

    def app(String name) {
        this.appName = name
        return this
    }

    def version(String v) {
        this.version = v
        return this
    }

    def database(Closure config) {
        def dbConfig = new DatabaseConfig()
        config.delegate = dbConfig
        config.resolveStrategy = Closure.DELEGATE_FIRST
        config()
        this.database = dbConfig.toMap()
        return this
    }

    def server(Closure config) {
        def srvConfig = new ServerConf()
        config.delegate = srvConfig
        config.resolveStrategy = Closure.DELEGATE_FIRST
        config()
        this.server = srvConfig.toMap()
        return this
    }

    def enable(String feature) {
        features << feature
        return this
    }

    void printConfig() {
        println "App: $appName v$version"
        println "Database: $database"
        println "Server: $server"
        println "Features: $features"
    }
}

class DatabaseConfig {
    String driver, url, username, password
    int poolSize = 5

    def driver(String d) { this.driver = d }
    def url(String u) { this.url = u }
    def username(String u) { this.username = u }
    def password(String p) { this.password = p }
    def poolSize(int s) { this.poolSize = s }

    Map toMap() { [driver: driver, url: url, username: username, poolSize: poolSize] }
}

class ServerConf {
    String host = 'localhost'
    int port = 8080

    def host(String h) { this.host = h }
    def port(int p) { this.port = p }

    Map toMap() { [host: host, port: port] }
}

// Build config using command chains + closure blocks
def config = new AppConfig()

config.app "MyWebApp" version "2.1.0"

config.database {
    driver 'org.postgresql.Driver'
    url 'jdbc:postgresql://localhost:5432/mydb'
    username 'admin'
    password 'secret'
    poolSize 10
}

config.server {
    host '0.0.0.0'
    port 9090
}

config.enable "caching"
config.enable "logging"
config.enable "metrics"

config.printConfig()

Output

App: MyWebApp v2.1.0
Database: [driver:org.postgresql.Driver, url:jdbc:postgresql://localhost:5432/mydb, username:admin, poolSize:10]
Server: [host:0.0.0.0, port:9090]
Features: [caching, logging, metrics]

This pattern is everywhere in the Groovy ecosystem. Gradle’s build.gradle files, Grails’ application.groovy, Jenkins’ Jenkinsfile, and Spock test specifications all use this same combination of command chains and closure-based configuration blocks. When you understand command chains, you understand how these tools work under the hood.

Command Chains in Test Frameworks

Testing is where command chains truly shine. Frameworks like Spock use Groovy’s command chain support to create specifications that read almost like plain English. Let us build a tiny test-assertion DSL to see how it works.

Test Framework DSL

// Build a mini assertion framework using command chains

class Should {
    Object actual

    Should(Object actual) {
        this.actual = actual
    }

    def equal(Object expected) {
        assert actual == expected : "Expected $expected but got $actual"
        println "PASS: $actual == $expected"
        return this
    }

    def contain(Object item) {
        assert (actual as Collection).contains(item) : "$actual does not contain $item"
        println "PASS: $actual contains $item"
        return this
    }

    def haveSize(int size) {
        def actualSize = (actual as Collection).size()
        assert actualSize == size : "Expected size $size but got $actualSize"
        println "PASS: size is $size"
        return this
    }

    def beGreaterThan(Object other) {
        assert actual > other : "$actual is not greater than $other"
        println "PASS: $actual > $other"
        return this
    }

    def beLessThan(Object other) {
        assert actual < other : "$actual is not less than $other"
        println "PASS: $actual < $other"
        return this
    }

    def beInstanceOf(Class type) {
        assert type.isInstance(actual) : "$actual is not instance of $type"
        println "PASS: $actual is instance of ${type.simpleName}"
        return this
    }
}

// Top-level entry point
def the(Object value) { new Should(value) }

// Now write assertions that read like English
println "=== String Tests ==="
the "hello" equal "hello"
the "Groovy" beInstanceOf String

println "\n=== Number Tests ==="
the 42 equal 42
the 100 beGreaterThan 50
the 3 beLessThan 10

println "\n=== Collection Tests ==="
the([1, 2, 3]) contain 2
the([1, 2, 3]) haveSize 3

println "\n=== All tests passed! ==="

Output

=== String Tests ===
PASS: hello == hello
PASS: Groovy is instance of String

=== Number Tests ===
PASS: 42 == 42
PASS: 100 > 50
PASS: 3 < 10

=== Collection Tests ===
PASS: [1, 2, 3] contains 2
PASS: size is 3

=== All tests passed! ===

Notice how the 42 equal 42 reads like a natural assertion. This is the exact pattern that Spock uses for its then: blocks and assertion methods. The beauty of command chains in testing is that test failures become easier to understand because the test code itself describes what should happen in plain language.

Named Parameters in Command Chains

Named parameters (maps) are one of the most useful tools in the command chain toolkit. They let you label your arguments, making the DSL even more expressive. Here is a deeper look at how they work.

Named Parameters Details

// Groovy automatically collects key:value pairs into a Map argument

class Schedule {
    def meeting(Map params) {
        println "Meeting: ${params.title}"
        return new MeetingBuilder(title: params.title)
    }
}

class MeetingBuilder {
    String title
    String time
    String room
    List<String> attendees = []

    def at(Map params) {
        this.time = params.time
        this.room = params.room
        return this
    }

    def with(Map params) {
        this.attendees = params.attendees as List
        println "  Time: $time, Room: $room"
        println "  Attendees: $attendees"
        return this
    }
}

def schedule = new Schedule()

// Named parameters make it crystal clear what each value means
schedule.meeting title: "Sprint Review" at time: "10:00 AM", room: "A-301" with attendees: ["Alice", "Bob", "Charlie"]

println "---"

schedule.meeting title: "Design Review" at time: "2:00 PM", room: "B-102" with attendees: ["Diana", "Eve"]

println "\n--- Multiple named params in one call ---"

// You can pass multiple named parameters in one method call
class HttpRequest {
    def get(Map params) {
        println "GET ${params.url}"
        println "  Headers: ${params.headers ?: 'none'}"
        println "  Timeout: ${params.timeout ?: 'default'}"
    }

    def post(Map params) {
        println "POST ${params.url}"
        println "  Body: ${params.body}"
        println "  ContentType: ${params.contentType ?: 'application/json'}"
    }
}

def http = new HttpRequest()
http.get url: "/api/users", headers: ["Auth": "Bearer token"], timeout: 5000
http.post url: "/api/users", body: '{"name":"Alice"}', contentType: "application/json"

Output

Meeting: Sprint Review
  Time: 10:00 AM, Room: A-301
  Attendees: [Alice, Bob, Charlie]
---
Meeting: Design Review
  Time: 2:00 PM, Room: B-102
  Attendees: [Diana, Eve]

--- Multiple named params in one call ---
GET /api/users
  Headers: [Auth:Bearer token]
  Timeout: 5000
POST /api/users
  Body: {"name":"Alice"}
  ContentType: application/json

Named parameters are the secret weapon of Groovy DSLs. They let you write self-documenting code where each argument carries its own label. The Groovy compiler automatically groups key: value pairs into a single Map argument, so your method only needs one Map parameter to accept any number of named values.

Limitations and Gotchas

Command chains are powerful, but they come with some rules and restrictions you need to know about. Understanding these will save you from confusing parser errors.

Command Chain Limitations

// Limitation 1: Cannot use in assignments with complex expressions
// This works:
// def result = send "hello" to "alice"

// Limitation 2: No-arg methods break the chain pattern
class Example {
    def doSomething(String s) {
        println "Doing: $s"
        return this
    }

    // No-arg method -- must use parentheses or property syntax
    def finish() {
        println "Finished!"
        return this
    }

    // Property getter alternative
    def getFinished() {
        println "Finished (property)!"
        return this
    }
}

def ex = new Example()

// Works: regular chain
ex.doSomething "task1" doSomething "task2"

// Cannot chain a no-arg method without dots:
// ex.doSomething "task" finish  // This would parse 'finish' as an arg to doSomething!
// Instead, use:
ex.doSomething("task3").finished  // explicit parens to avoid parsing issue

println "\n--- Limitation 3: Nested chains can be ambiguous ---"

// Be careful with nested calls
class Outer {
    def foo(x) { println "foo($x)"; return this }
    def bar(x) { println "bar($x)"; return this }
}

def o = new Outer()
// This is clear:
o.foo 1 bar 2

// But this can be confusing with complex expressions:
// o.foo 1 + 2 bar 3   // Is it foo(1+2).bar(3) or foo(1).+(2).bar(3)?
// When in doubt, use parentheses:
o.foo(1 + 2).bar(3)

println "\n--- Limitation 4: Must start from a known scope ---"

// Command chains need a known starting point
// Inside a class method, you need to qualify the first call
class MyClass {
    def process(String s) { println "Processing: $s"; return this }
    def save(String s) { println "Saving: $s" }

    def doWork() {
        // this.process "data" save "result"  -- need 'this' or explicit receiver
        process "data"  // single command expression works
    }
}

new MyClass().doWork()

Output

Doing: task1
Doing: task2
Doing: task3
Finished (property)!

--- Limitation 3: Nested chains can be ambiguous ---
foo(1)
bar(2)
foo(3)
bar(3)

--- Limitation 4: Must start from a known scope ---
Processing: data

Key limitations to remember:

No-argument methods cannot appear in the alternating pattern — use property syntax (.getXxx) or explicit parentheses
Arithmetic operators and complex expressions inside a chain can create ambiguity — use parentheses when in doubt
Command chains work best in scripts and DSL contexts — inside class methods, you may need to qualify the receiver
Chaining cannot span multiple lines without care — Groovy’s parser may interpret a new line as a new statement
IDE support for command chains varies — some IDEs may not provide full autocompletion inside chains

Performance Considerations

Command chains are purely a syntactic feature — they have zero runtime cost beyond normal method calls. The Groovy parser translates a b c d into a(b).c(d) at compile time, so the resulting bytecode is identical.

No runtime overhead: Command chains are resolved at parse time. The bytecode is the same as traditional dot-and-parentheses syntax.
Method dispatch cost: Each link in the chain is a method call. If you are using dynamic Groovy, each call goes through the MOP (Meta-Object Protocol). For performance-critical code, consider @CompileStatic — though note that command chains may have limited support under @CompileStatic.
Object creation: Each intermediate step in a chain typically creates a new object (to hold the state for the next method). In tight loops, consider reusing objects or using a single builder instead of creating many intermediaries.
Metaprogramming cost: If your DSL uses metaClass to add methods (like the unit DSL example), those calls go through the MOP and are slightly slower than compiled method calls. For performance-sensitive DSLs, use extension modules or @DelegatesTo annotations instead.

For most DSL use cases — configuration, testing, build scripts — performance is a non-issue. Command chains are designed for readability in scenarios where code is read far more often than it is executed.

Conclusion

We covered a lot of ground in this Groovy command chain tutorial — from basic parentheses-free method calls to multi-link chains, named parameters, closure arguments, and real-world DSL patterns. Command chains are one of the features that set Groovy apart from other JVM languages, letting you create APIs that read like natural language.

The key insight is that command chains are just syntactic sugar for regular method calls. The pattern a b c d is parsed as a(b).c(d). Once you understand this rule, you can design APIs where each method returns the right type to enable the next call in the chain. Combined with maps for named parameters and closures for behavior, you get a DSL toolkit that is hard to match in any other language.

For related topics, check out our post on Groovy operator overloading to learn how to customize operators for your classes, and the Groovy type checking guide to understand how static compilation interacts with dynamic DSL features.

Summary

Command chains let you write a b c d instead of a(b).c(d) — alternating methods and arguments
Each method in the chain must return an object that has the next method
Named parameters (maps) and closures work directly in command chains
No-arg methods need property syntax (.property) or explicit parentheses in chains
Command chains have zero runtime overhead — they are parsed at compile time into regular method calls

If you also work with build tools, CI/CD pipelines, or cloud CLIs, check out Command Playground to practice 105+ CLI tools directly in your browser — no install needed.

Up next: Groovy Type Checking – @TypeChecked and @CompileStatic

Frequently Asked Questions

What is a Groovy command chain?

A Groovy command chain is a syntactic feature that lets you call methods without dots or parentheses by alternating method names and arguments. For example, send "hello" to "Alice" is parsed as send("hello").to("Alice"). Each method must return an object that has the next method in the chain. Command chains were introduced in Groovy 1.8 and are the foundation for building natural-language DSLs.

How do I handle no-argument methods in a Groovy command chain?

No-argument methods break the alternating method-argument pattern that command chains require. You have two options: use property syntax by defining a getter method (e.g., getFinished() accessed as .finished) with a dot, or use explicit parentheses (e.g., .finish()). The dot is required because the parser expects an argument after each method name in the chain.

Do Groovy command chains affect performance?

No. Command chains are purely syntactic sugar resolved at parse time. The Groovy parser translates a b c d into a(b).c(d) before compilation, so the resulting bytecode is identical to writing the method calls with dots and parentheses. The only performance consideration is that each link in the chain is a method call, which has the normal cost of dynamic dispatch in Groovy.

Can I use Groovy command chains with @CompileStatic?

Command chains have limited support under @CompileStatic. Basic command expressions (dropping parentheses on a single call) generally work, but complex multi-link chains may not be fully supported because @CompileStatic needs explicit type information at each step. For DSL-heavy code that relies on command chains, you typically use dynamic Groovy and keep @CompileStatic for performance-critical business logic.

How are Groovy command chains used in real-world frameworks?

Command chains and command expressions are used extensively in the Groovy ecosystem. Gradle build scripts use command-style syntax like compile 'group:artifact:version'. Jenkins Pipeline (Jenkinsfile) uses command expressions for steps like sh 'make build'. Spock testing framework uses the pattern for readable test specifications. Grails uses closure-scoped command expressions for configuration. All of these use the same underlying Groovy feature.

Previous in Series: Groovy Generics and Type Parameters

Next in Series: Groovy Type Checking – @TypeChecked and @CompileStatic

Groovy, Groovy Metaprogramming

Groovy Command Chain – Build Natural Language DSLs with 10 Examples

Table of Contents

What Are Groovy Command Chains?

How Command Chains Work

10 Practical Command Chain Examples

Example 1: Basic Command Expression (No Parentheses)

Example 2: Two-Part Command Chain

Example 3: Three-Part Chain with Fluent API

Example 4: Using Maps as Named Parameters

Example 5: No-Arg Methods in Chains (Property Syntax)

Example 6: Building a Query DSL

Example 7: Closure Arguments in Chains

Example 8: Using ‘with’ for DSL Scoping

Example 9: Arithmetic and Unit-Like DSLs

Example 10: Combining Command Chains with Closures and Maps

Bonus Example 11: Top-Level Functions as DSL Entry Points

Building a Real-World Configuration DSL

Command Chains in Test Frameworks

Named Parameters in Command Chains

Limitations and Gotchas

Performance Considerations

Conclusion

Summary

Frequently Asked Questions

What is a Groovy command chain?

How do I handle no-argument methods in a Groovy command chain?

Do Groovy command chains affect performance?

Can I use Groovy command chains with @CompileStatic?

How are Groovy command chains used in real-world frameworks?

Related Posts

Related Topics You Might Like:

PreviousGroovy Generics and Type Parameters – 13 Tested Examples

NextGroovy Type Checking – @TypeChecked and @CompileStatic with 10 Examples

RahulAuthor posts

Related Posts ...

Groovy Advanced AST Transforms – Part 2 with 10+ Examples

Groovy Modern Features – Cookbook Guide with 10+ Examples

Groovy Number Math – Cookbook Guide with 10+ Examples

GPars Tutorial – Groovy Parallel Programming with 10+ Examples

Groovy HTTP REST – Cookbook Guide with 10+ Examples

Groovy Script vs Class – 10+ Tested Examples

No comment

Leave a Reply Cancel reply