Single-line comments start with // and can be found at any position in the line. The characters following //, until the end of the line, are considered part of the comment.

A multiline comment starts with /* and can be found at any position in the line. The characters following /* will be considered part of the comment, including new line characters, up to the first */ closing the comment. Multiline comments can thus be put at the end of a statement, or even inside a statement.

Similarly to multiline comments, Groovydoc comments are multiline, but start with /** and end with */. Lines following the first Groovydoc comment line can optionally start with a star *. Those comments are associated with:

Although the compiler will not complain about Groovydoc comments not being associated with the above language elements, you should prepend those constructs with the comment right before it.

Groovydoc follows the same conventions as Java’s own Javadoc. So you’ll be able to use the same tags as with Javadoc.

In addition, Groovy supports Runtime Groovydoc since 3.0.0, i.e. Groovydoc can be retained at runtime.

The Runtime Groovydoc starts with /**@ and ends with */, for example:

Beside the single-line comment, there is a special line comment, often called the shebang line understood by UNIX systems which allows scripts to be run directly from the command-line, provided you have installed the Groovy distribution and the groovy command is available on the PATH.

Identifiers start with a letter, a dollar or an underscore. They cannot start with a number.

A letter can be in the following ranges:

Then following characters can contain letters and numbers.

Here are a few examples of valid identifiers (here, variable names):

But the following ones are invalid identifiers:

All keywords are also valid identifiers when following a dot:

Quoted identifiers appear after the dot of a dotted expression. For instance, the name part of the person.name expression can be quoted with person."name" or person.'name'. This is particularly interesting when certain identifiers contain illegal characters that are forbidden by the Java Language Specification, but which are allowed by Groovy when quoted. For example, characters like a dash, a space, an exclamation mark, etc.

As we shall see in the following section on strings, Groovy provides different string literals. All kind of strings are actually allowed after the dot:

There’s a difference between plain character strings and Groovy’s GStrings (interpolated strings), as in that the latter case, the interpolated values are inserted in the final string for evaluating the whole identifier:

Single-quoted strings are a series of characters surrounded by single quotes:

All the Groovy strings can be concatenated with the + operator:

Triple-single-quoted strings are a series of characters surrounded by triplets of single quotes:

Triple-single-quoted strings may span multiple lines. The content of the string can cross line boundaries without the need to split the string in several pieces and without concatenation or newline escape characters:

If your code is indented, for example in the body of the method of a class, your string will contain the whitespace of the indentation. The Groovy Development Kit contains methods for stripping out the indentation with the String#stripIndent() method, and with the String#stripMargin() method that takes a delimiter character to identify the text to remove from the beginning of a string.

When creating a string as follows:

You will notice that the resulting string contains a newline character as first character. It is possible to strip that character by escaping the newline with a backslash:

Double-quoted strings are a series of characters surrounded by double quotes:

Triple-double-quoted strings behave like double-quoted strings, with the addition that they are multiline, like the triple-single-quoted strings.

Beyond the usual quoted strings, Groovy offers slashy strings, which use / as the opening and closing delimiter. Slashy strings are particularly useful for defining regular expressions and patterns, as there is no need to escape backslashes.

Example of a slashy string:

Only forward slashes need to be escaped with a backslash:

Slashy strings are multiline:

Slashy strings can be thought of as just another way to define a GString but with different escaping rules. They hence support interpolation:

Dollar slashy strings are multiline GStrings delimited with an opening $/ and a closing /$. The escaping character is the dollar sign, and it can escape another dollar, or a forward slash. Escaping for the dollar and forward slash characters is only needed where conflicts arise with the special use of those characters. The characters $foo would normally indicate a GString placeholder, so those four characters can be entered into a dollar slashy string by escaping the dollar, i.e. $$foo. Similarly, you will need to escape a dollar slashy closing delimiter if you want it to appear in your string.

Here are a few examples:

It was created to overcome some of the limitations of the slashy string escaping rules. Use it when its escaping rules suit your string contents (typically if it has some slashes you don’t want to escape).

Unlike Java, Groovy doesn’t have an explicit character literal. However, you can be explicit about making a Groovy string an actual character, by three different means:

The integral literal types are the same as in Java:

You can create integral numbers of those types with the following declarations:

If you use optional typing by using the def keyword, the type of the integral number will vary: it’ll adapt to the capacity of the type that can hold that number.

For positive numbers:

As well as for negative numbers:

The decimal literal types are the same as in Java:

You can create decimal numbers of those types with the following declarations:

Decimals can use exponents, with the e or E exponent letter, followed by an optional sign, and a integral number representing the exponent:

Conveniently for exact decimal number calculations, Groovy choses java.lang.BigDecimal as its decimal number type. In addition, both float and double are supported, but require an explicit type declaration, type coercion or suffix. Even if BigDecimal is the default for decimal numbers, such literals are accepted in methods or closures taking float or double as parameter types.

When writing long literal numbers, it’s harder on the eye to figure out how some numbers are grouped together, for example with groups of thousands, of words, etc. By allowing you to place underscore in number literals, it’s easier to spot those groups:

We can force a number (including binary, octals and hexadecimals) to have a specific type by giving a suffix (see table below), either uppercase or lowercase.

Examples:

Although operators are covered later on, it’s important to discuss the behavior of math operations and what their resulting types are.

Division and power binary operations aside (covered below),

The following table summarizes those rules:

Groovy has always supported literal list/array definitions using square brackets and has avoided Java-style curly braces so as not to conflict with closure definitions. In the case where the curly braces come immediately after an array type declaration however, there is no ambiguity with closure definitions, so Groovy 3 and above support that variant of the Java array initialization expression.

Examples:

The following binary arithmetic operators are available in Groovy:

Here are a few examples of usage of those operators:

The + and - operators are also available as unary operators:

In terms of unary arithmetics operators, the ++ (increment) and -- (decrement) operators are available, both in prefix and postfix notation:

For the unary not operator on Booleans, see Conditional operators.

The binary arithmetic operators we have seen above are also available in an assignment form:

Let’s see them in action:

The logical "not" has a higher priority than the logical "and".

The logical "and" has a higher priority than the logical "or".

The logical || operator supports short-circuiting: if the left operand is true, it knows that the result will be true in any case, so it won’t evaluate the right operand. The right operand will be evaluated only if the left operand is false.

Likewise for the logical && operator: if the left operand is false, it knows that the result will be false in any case, so it won’t evaluate the right operand. The right operand will be evaluated only if the left operand is true.

Groovy offers four bitwise operators:

Bitwise operators can be applied on arguments which are of type byte, short, int, long, or BigInteger. If one of the arguments is a BigInteger, the result will be of type BigInteger; otherwise, if one of the arguments is a long, the result will be of type long; otherwise, the result will be of type int:

It’s worth noting that the internal representation of primitive types follow the Java Language Specification. In particular, primitive types are signed, meaning that for a bitwise negation, it is always good to use a mask to retrieve only the necessary bits.

In Groovy, bitwise operators are overloadable, meaning that you can define the behavior of those operators for any kind of object.

Groovy offers three bit shift operators:

All three operators are applicable where the left argument is of type byte, short, int, or long. The first two operators can also be applied where the left argument is of type BigInteger. If the left argument is a BigInteger, the result will be of type BigInteger; otherwise, if the left argument is a long, the result will be of type long; otherwise, the result will be of type int:

In Groovy, bit shift operators are overloadable, meaning that you can define the behavior of those operators for any kind of object.

The "not" operator is represented with an exclamation mark (!) and inverts the result of the underlying boolean expression. In particular, it is possible to combine the not operator with the Groovy truth:

The ternary operator is a shortcut expression that is equivalent to an if/else branch assigning some value to a variable.

Instead of:

You can write:

The ternary operator is also compatible with the Groovy truth, so you can make it even simpler:

The "Elvis operator" is a shortening of the ternary operator. One instance of where this is handy is for returning a 'sensible default' value if an expression resolves to false-ish (as in Groovy truth). A simple example might look like this:

Usage of the Elvis operator reduces the verbosity of your code and reduces the risks of errors in case of refactorings, by removing the need to duplicate the expression which is tested in both the condition and the positive return value.

Groovy 3.0.0 introduces the Elvis operator, for example:

The Safe Navigation operator is used to avoid a NullPointerException. Typically when you have a reference to an object you might need to verify that it is not null before accessing methods or properties of the object. To avoid this, the safe navigation operator will simply return null instead of throwing an exception, like so:

Normally in Groovy, when you write code like this:

The user.name call triggers a call to the property of the same name, that is to say, here, to the getter for name. If you want to retrieve the field instead of calling the getter, you can use the direct field access operator:

The method pointer operator (.&) can be used to store a reference to a method in a variable, in order to call it later:

There are multiple advantages in using method pointers. First of all, the type of such a method pointer is a groovy.lang.Closure, so it can be used in any place a closure would be used. In particular, it is suitable to convert an existing method for the needs of the strategy pattern:

Method pointers are bound by the receiver and a method name. Arguments are resolved at runtime, meaning that if you have multiple methods with the same name, the syntax is not different, only resolution of the appropriate method to be called will be done at runtime:

To align with Java 8 method reference expectations, in Groovy 3 and above, you can use new as the method name to obtain a method pointer to the constructor:

Also in Groovy 3 and above, you can obtain a method pointer to an instance method of a class. This method pointer takes an additional parameter being the receiver instance to invoke the method on:

For backwards compatibility, any static methods that happen to have the correct parameters for the call will be given precedence over instance methods for this case.

The Parrot parser in Groovy 3+ supports the Java 8+ method reference operator. The method reference operator (::) can be used to reference a method or constructor in contexts expecting a functional interface. This overlaps somewhat with the functionality provided by Groovy’s method pointer operator. Indeed, for dynamic Groovy, the method reference operator is just an alias for the method pointer operator. For static Groovy, the operator results in bytecode similar to the bytecode that Java would produce for the same context.

Some examples highlighting various supported method reference cases are shown in the following script:

Some examples highlighting various supported constructor reference cases are shown in the following script:

The pattern operator (~) provides a simple way to create a java.util.regex.Pattern instance:

while in general, you find the pattern operator with an expression in a slashy-string, it can be used with any kind of String in Groovy:

Alternatively to building a pattern, you can use the find operator =~ to directly create a java.util.regex.Matcher instance:

Since a Matcher coerces to a boolean by calling its find method, the =~ operator is consistent with the simple use of Perl’s =~ operator, when it appears as a predicate (in if, ?:, etc.). When the intent is to iterate over matches of the specified pattern (in while, etc.) call find() directly on the matcher or use the iterator DGM.

The match operator (==~) is a slight variation of the find operator, that does not return a Matcher but a boolean and requires a strict match of the input string:

Typically, the match operator is used when the pattern involves a single exact match, otherwise the find operator might be more useful.

The Spread-dot Operator (*.), often abbreviated to just Spread Operator, is used to invoke an action on all items of an aggregate object. It is equivalent to calling the action on each item and collecting the result into a list:

The expression cars*.make is equivalent to cars.collect{ it.make }. Groovy’s GPath notation allows a short-cut when the referenced property isn’t a property of the containing list, in that case it is automatically spread. In the previously mentioned case, the expression cars.make can be used, though retaining the explicit spread-dot operator is often recommended.

The spread operator is null-safe, meaning that if an element of the collection is null, it will return null instead of throwing a NullPointerException:

The spread operator can be used on any class which implements the Iterable interface:

Use multiple invocations of the spread-dot operator (here cars*.models*.name) when working with aggregates of data structures which themselves contain aggregates:

Consider using the collectNested DGM method instead of the spread-dot operator for collections of collections:

Groovy supports the concept of ranges and provides a notation (..) to create ranges of objects:

Ranges implementation is lightweight, meaning that only the lower and upper bounds are stored. You can create a range from any Comparable object that has next() and previous() methods to determine the next / previous item in the range. For example, you can create a range of characters this way:

The spaceship operator (<=>) delegates to the compareTo method:

The subscript operator is a short hand notation for getAt or putAt, depending on whether you find it on the left hand side or the right hand side of an assignment:

The subscript operator, in combination with a custom implementation of getAt/putAt is a convenient way for destructuring objects:

Groovy 3.0.0 introduces safe indexing operator, i.e. ?[], which is similar to ?.. For example:

The membership operator (in) is equivalent to calling the isCase method. In the context of a List, it is equivalent to calling contains, like in the following example:

In Groovy, using == to test equality is different from using the same operator in Java. In Groovy, it is calling equals. If you want to compare reference equality, you should use is like in the following example:

The coercion operator (as) is a variant of casting. Coercion converts object from one type to another without them being compatible for assignment. Let’s take an example:

This can be fixed by using coercion instead:

When an object is coerced into another, unless the target type is the same as the source type, coercion will return a new object. The rules of coercion differ depending on the source and target types, and coercion may fail if no conversion rules are found. Custom conversion rules may be implemented thanks to the asType method:

The diamond operator (<>) is a syntactic sugar only operator added to support compatibility with the operator of the same name in Java 7. It is used to indicate that generic types should be inferred from the declaration:

In dynamic Groovy, this is totally unused. In statically type checked Groovy, it is also optional since the Groovy type checker performs type inference whether this operator is present or not.

The call operator () is used to call a method named call implicitly. For any object which defines a call method, you can omit the .call part and use the call operator instead:

Default imports are the imports that Groovy language provides by default. For example look at the following code:

The same code in Java needs an import statement to Date class like this: import java.util.Date. Groovy by default imports these classes for you.

The below imports are added by groovy for you:

This is done because the classes from these packages are most commonly used. By importing these boilerplate code is reduced.

A simple import is an import statement where you fully define the class name along with the package. For example the import statement import groovy.xml.MarkupBuilder in the code below is a simple import which directly refers to a class inside a package.

Groovy, like Java, provides a special way to import all classes from a package using *, the so called star import. MarkupBuilder is a class which is in package groovy.xml, alongside another class called StreamingMarkupBuilder. In case you need to use both classes, you can do:

That’s perfectly valid code. But with a * import, we can achieve the same effect with just one line. The star imports all the classes under package groovy.xml:

One problem with * imports is that they can clutter your local namespace. But with the kinds of aliasing provided by Groovy, this can be solved easily.

Groovy’s static import capability allows you to reference imported classes as if they were static methods in your own class:

This is similar to Java’s static import capability but is a more dynamic than Java in that it allows you to define methods with the same name as an imported method as long as you have different types:

If you have the same types, the imported class takes precedence.

Static imports with the as keyword provide an elegant solution to namespace problems. Suppose you want to get a Calendar instance, using its getInstance() method. It’s a static method, so we can use a static import. But instead of calling getInstance() every time, which can be misleading when separated from its class name, we can import it with an alias, to increase code readability:

Now, that’s clean!

A static star import is very similar to the regular star import. It will import all the static methods from the given class.

For example, lets say we need to calculate sines and cosines for our application. The class java.lang.Math has static methods named sin and cos which fit our need. With the help of a static star import, we can do:

As you can see, we were able to access the methods sin and cos directly, without the Math. prefix.

With type aliasing, we can refer to a fully qualified class name using a name of our choice. This can be done with the as keyword, as before.

For example we can import java.sql.Date as SQLDate and use it in the same file as java.util.Date without having to use the fully qualified name of either class:

Groovy supports both scripts and classes. Take the following code for example:

This is typical code that you would find coming from Java, where code has to be embedded into a class to be executable. Groovy makes it easier, the following code is equivalent:

A script can be considered as a class without needing to declare it, with some differences.

A script is always compiled into a class. The Groovy compiler will compile the class for you, with the body of the script copied into a run method. The previous example is therefore compiled as if it was the following:

If the script is in a file, then the base name of the file is used to determine the name of the generated script class. In this example, if the name of the file is Main.groovy, then the script class is going to be Main.

It is possible to define methods into a script, as illustrated here:

You can also mix methods and code. The generated script class will carry all methods into the script class, and assemble all script bodies into the run method:

This code is internally converted into:

Variables in a script do not require a type definition. This means that this script:

will behave the same as:

However, there is a semantic difference between the two:

Groovy supports the same primitive types as those defined by the Java Language Specification:

While Groovy declares and stores primitive fields and variables as primitives, because it uses Objects for everything, it autowraps references to primitives. Just like Java, the wrappers it uses are

Here’s an example using int

Now you may be concerned that this means every time you use a mathematical operator on a reference to a primitive that you’ll incur the cost of unboxing and reboxing the primitive. But this is not the case, as Groovy will compile your operators into their method equivalents and uses those instead. Additionally, Groovy will automatically unbox to a primitive when calling a Java method that takes a primitive parameter and automatically box primitive method return values from Java. However, be aware there are some differences from Java’s method resolution.

Groovy classes are very similar to Java classes, and are compatible with Java ones at JVM level. They may have methods, fields and properties (think JavaBeans properties but with less boilerplate). Classes and class members can have the same modifiers (public, protected, private, static, etc) as in Java with some minor differences at the source level which are explained shortly.

The key differences between Groovy classes and their Java counterparts are:

The following code presents an example class.

An interface defines a contract that a class needs to conform to. An interface only defines a list of methods that need to be implemented, but does not define the methods implementation.

Methods of an interface are always public. It is an error to use protected or private methods in interfaces:

A class implements an interface if it defines the interface in its implements list or if any of its superclasses does:

An interface can extend another interface:

It is worth noting that for a class to be an instance of an interface, it has to be explicit. For example, the following class defines the greet method as it is declared in the Greeter interface, but does not declare Greeter in its interfaces:

In other words, Groovy does not define structural typing. It is however possible to make an instance of an object implement an interface at runtime, using the as coercion operator:

You can see that there are two distinct objects: one is the source object, a DefaultGreeter instance, which does not implement the interface. The other is an instance of Greeter that delegates to the coerced object.

Constructors are special methods used to initialize an object with a specific state. As with normal methods, it is possible for a class to declare more than one constructor, so long as each constructor has a unique type signature. If an object doesn’t require any parameters during construction, it may use a no-arg constructor. If no constructors are supplied, an empty no-arg constructor will be provided by the Groovy compiler.

Groovy supports two invocation styles:

Groovy methods are quite similar to other languages. Some peculiarities will be shown in the next subsections.