The Golo Programming Language

Editor and IDE support for Golo is available for:

Golo source code need to be placed in modules. Module names are separated with dots, as in:

It is suggested yet not enforced that the first elements in a module name are in lowercase, and that the last one have an uppercase first letter.

A Golo module can be executable if it has a function named main and that takes an argument for the JVM program arguments:

println is a predefined function that outputs a value to the standard console. As you can easily guess, here we output Hello, world! and that is an awesome achievement.

Of course, we need to run this incredibly complex application.

Golo comes with a golo script found in the distribution bin/ folder. It provides several commands, notably:

The complete commands usage instructions can be listed by running golo --help. A command usage instructions can be listed by running golo --usage ${command}.

Provided that golo is available from your current $PATH, you may run the program above as follows:

golo golo takes several Golo source files (*.golo and directories) as input. It expects the last one of them to have a main function to call (or use --module to define the golo module with the main function). The Golo code is compiled on the fly and executed straight into a JVM.

You may also pass arguments to the main function by appending --args on the command line invocation. Suppose that we have a module EchoArgs as follows:

We may invoke it as follows:

Note that args is expected to be an array.

Finally, the --classpath flag allows to specify a list of classpath elements, which can be either directories or .jar files. The system property golo.class.path or the environment variable GOLOPATH can also be used to specify these elements. See the golo --help command for details on the various Golo commands.

Golo comes with a compiler (compile command) that generates JVM bytecode in .class files. We will give more details in the chapter on interoperability with Java.

Compiling Golo files is straightforward:

This compiles the code found in samples/helloworld.golo and outputs the generated classes to a classes folder (it will be created if needed):

It is also possible to output to a Jar archive:

This would take all .golo files from the sample folder, and assemble the resulting JVM class files in hello.jar.

Golo provides a run command for running compiled Golo code:

Simple, isn’t it?

Golo provides a shebang command for running a Golo file as a simple script.

the script above can be executed with:

Naturally the main goal is to use this command to make the script self-executable:

Now, we can run the script directly:

Both golo and run commands can be given JVM-specific flags using the JAVA_OPTS environment variable.

As an example, the following runs fibonacci.golo and prints JIT compilation along the way:

A bash script can be found in share/shell-completion/ called golo-bash-completion that will provide autocomplete support for the golo and vanilla-golo CLI scripts. You may either source the script, or drop the script into your bash_completion.d/ folder and restart your terminal.

A zsh script can be found in share/shell-completion/ called golo-zsh-completion that works using the golo-bash-completion to provide autocomplete support using the bash autocomplete support provided by zsh. Place both files into the same directory and source golo-zsh-completion from your terminal or .zshrc to give it a try!

Golo comments start with a #, just like in Bash, Python or Ruby:

Golo does not check for types at compile time, and they are not declared. Everything happens at runtime in Golo.

Variables are declared using the var keyword, while constant references are declared with let. It is strongly advised that you favour let over var unless you are certain that you need mutability.

Variables and constants need to be initialized when declared. Failing to do so results in a compilation error.

Here are a few examples:

Valid names contain upper and lower case letters within the [a..z] range, underscores (_), dollar symbols ($) and numbers. In any case, an identifier must not start with a number.

It is possible to define a constant reference locally to the evaluation of an expression using the with keyword.

For instance:

is functionally equivalent to

However, the a variable exists only in the scope of the expression evaluation. Indeed, code like:

will not compile since a is unknown in the outer scope.

Besides the locality, this construct is really interesting when constructing other expressions (e.g. match constructs), and can help to keep a functional style form of writing functions.

Golo supports a set of data literals. They directly map to their counterparts from the Java Standard API. We give them along with examples in the data literals table below.

Speaking of strings, Golo also supports multi-line strings using the """ delimiters, as in:

This snippet would print the following to the standard console output:

Golo has special support for common collections. The syntax uses brackets prefixed by a collection name, as in:

The syntax and type matchings are the following:

In addition to literals, collections can be created using collection comprehension. This is a simple way to create a new collection based on another one (actually on any iterable object), by filtering and transforming its content. For instance:

This is a more readable and more powerful version of filter+map. Indeed, the previous example could be rewritten as:

The general syntax is a collection literal containing an expression followed by one or more loop-like expression. If more than one loop is given, it is equivalent to nested loops. Thus

is equivalent to:

for loop can be used, as in

Contrary to the filter+map approach, where the kind on collection is kept, comprehension can transform the source collection type, which can be any iterable. For instance:

However, the result collection can only be of the type of one of the predefined collection literal types.

Destructuring can also be used in collection comprehension, as in

Maps can also be created, provided the given expression is either a pair tuple or a instance of Map.Entry (you can use the predefined mapEntry(key, value) function to create such objects). For instance:

A collection comprehension is a expression, and can thus be used as such. E.g.

The analogy can be made between comprehension and SQL queries. As an illustration, compare:

with

Golo supports simple destructuring, that is automatic extraction of values from an object and assignment to multiple variables in one instruction.

For instance, using destructuring on a tuple:

If there are more or fewer variables than values to assign, an exception is raised. A special syntax is available to assign the rest of the values, similar to varargs notation. For instance:

The reminder has the same type than the destructured object. Note that only container-like object can be destructured using this syntax. For instance, golo structures can’t use the rest syntax and raise an exception.

Any object having a __$$_destruct(number, rest, toSkip) method returning an array can be used in destructuring assignments. Golo specific data structures and some Java native ones (arrays, maps, collections) can be destructured. Augmentations can be used to make an existing class destructurable.

For instance, golo structures are destructurable:

as well as java lists:

Already defined variables can also be assigned with destructuring. For instance, one can easily swap two variables:

Destucturing can also be used in foreach loops:

It is moreover possible to ignore some of the destructured values by using the special _ variable name.

This name can be used with the remainder syntax, to avoid the creation of a new structure to hold the other values. For instance:

Here, a is 2 and b is 4. No new range is created for the remaining values.

Golo supports the following set of operators.

The operator precedence rules are as follows:

This means that:

reads as:

Although we will discuss this in more details later on, you should already know that : is used to invoke instance methods.

You could for instance call the toString() method that any Java object has, and print it out as follows:

As you probably know, arrays on the JVM are special objects. Golo deals with such arrays as being instances of Object[] and does not provide a wrapper class like many languages do. A Java / JVM array is just what it is supposed to be.

Golo adds some sugar to relieve the pain of working with arrays. Golo allows some special methods to be invoked on arrays:

Given a reference a on some array:

Finally, arrays can be created with the Array function, as in:

You can of course take advantage of the array collection literal, too:

The structure of a free-form project is as follows:

The structure of a Maven-driven project is as follows:

The project can be built and packaged with Maven using the following command:

You can now run the module Foo with:

The structure of a Gradle-driven project is as follows:

The project can be built and packaged with Gradle using the following command:

You can now run the module Foo with:

With the --vcs option, the command will create a ignore file and try to initialize the repository. Mercurial (hg) and Git (git) are currently supported. For instance,

or

If the option is not given, or if the value is none, no repository is initialized.

The --profile option defines the kind of project you want to create, and will influence the files and hierarchy generated. Two profiles are currently supported:

Golo modules can define functions as follows:

In turn, you may invoke a function with a familiar notation:

A function needs to return a value using the return keyword. Some languages state that the last statement is the return value, but Golo does not follow that trend. We believe that return is more explicit, and that a few keystrokes in favour of readability is still a good deal.

Still, you may omit return statements if your function does not return a value:

If you do so, the function will actually return null, hence result in the next statement is null:

Of course functions may take some parameters, as in:

Invoking functions that take parameters is straightforward, too:

Functions may take a varying number of parameters. To define one, just add …​ to the last parameter name:

Here, c catches the variable arguments in an array, just like it would be the case with Java. You can thus treat c as being a Java object of type Object[].

Calling variable-arity functions does not require wrapping the last arguments in an array. While invoking the foo function above, the following examples are legit:

Because the parameter that catches the last arguments is an array, you may call array methods. Given:

then:

When you invoke Golo functions, you can use the name of the parameters explicitly in the call like so:

Suppose that we have a module foo.Bar:

We can invoke f from another module by prefixing it with its module name:

Of course, we may also take advantage of an import statement:

You may prepend the last piece of the module name. The following invocations are equivalent:

To help maintaining packages of several modules, and to avoid repeating the fully qualified name of the package when importing “local” modules, import can also be made relative to the package of the importing module. For instance, the following code:

is equivalent to

Note that only modules in the same package or in a sub-package can be imported using relative name. In the previous example, to import the module foo.Plop, its full name must be specified.

Moreover, it is possible to import several modules from the same package with a single import statement, as in;

Golo modules have a set of implicit imports:

These modules are imported after the module explicitly imported in the module, so that elements defined in these modules (e.g. predefined functions or augmentations) can be redefined.

By default, functions are visible outside of their module. You may restrict the visibility of a function by using the local keyword:

Here, b is visible while a can only be invoked from within the Foo module. Given another module called Bogus, the following would fail at runtime:

Golo feature recursive tail call optimization. If a function last action is to return the result of a recursive call, it is optimized to not stack a new call and is compiled in code equivalent to a loop. For instance, a function like:

is compiled into something roughly equivalent to :

This allows to create recursive functions that will not throw a StackOverflowError even in the presence of a large number or recursive call. The optimization can be disabled by setting the golo.optimize.tce system property to false (e.g. export GOLO_OPTS='-Dgolo.optimize.tce=false).

A call is tail recursive when the function returns the result of calling itself directly. Indeed, since no evaluation nor flow analysis is done, many effectively tail recursive calls can’t be identified as such, and thus are not optimized. It is recommended to rewrite the code to make the tail call more direct. For instance, the following two functions are not optimized:

while the following one is:

Note that returning a match expression that may evaluate to a tail call will be optimized, such that the function

will be strictly equivalent to the previous one. A consequence of this behavior is that mutual recursions are not optimized.

You can declare let and var references at the module level, as in:

These references get initialized when the module is being loaded by the Java virtual machine. In fact, module-level state is implemented using private static fields that get initialized in a <clinit> method.

Module-level references are only visible from their module, although a function may provide accessors to them.

It is important to note that such references get initialized in the order of declaration in the source file. Having initialization dependencies between such references would be silly anyway, but one should keep it in mind just in case.

If the Golo compiler find a unary function named main, it will be compiled to a void(String[]) static method. This main method can servers as a JVM entry point.

Suppose that we have the following Golo module:

Once compiled, we may invoke it as follows:

Golo can invoke public Java static methods by treating them as functions:

In this example, asList is resolved from the java.util.Arrays import and called as a function. Note that we could equivalently have written a qualified invocation as Arrays.asList(1, 2, 3).

When you have an object, you may invoke its methods using the : operator.

The following would call the toString method of any kind, then print it:

Of course, you may chain calls as long as a method is not of a void return type. Golo converts Java void methods by making them return null. This is neither a bug or a feature: the invokedynamic support on the JVM simply does so.

If you compile your Java 8 source code with the -parameters option, then you will be able to invoke the functions from Golo with named arguments.

Further documentation about Names Method Parameters with Java 8.

When calling a deprecated method or function, a warning is displayed. It can be disabled by setting the golo.warnings.deprecated system property to false.

Golo supports null-safe methods invocations using the "Elvis" symbol: ?:.

Suppose that we invoke the method bar() on some reference foo: foo: bar(). If foo is null, then invoking bar() throws a java.lang.NullPointerException, just like you would expect in Java.

By contrast:

This is quite useful when querying data models where null values could be returned. This can be elegantly combined with the orIfNull operator to return a default value, as illustrated by the following example:

This is more elegant than, say:

Golo doesn’t have an instantiation operator like new in Java. Instead, creating an object and calling its constructor is done as if it was just another function.

As an example, we may allocate a java.util.LinkedList as follows:

Another example would be using a java.lang.StringBuilder.

As one would expect, the str_build function above gives the "hello" string.

Golo treats public static fields as function, so one could get the maximum value for an Integer as follows:

Instance fields can be accessed as functions, both for reading and writing. Suppose that we have a Java class that looks as follows:

We can access the bar field as follows:

An interesting behavior when writing fields is that the "methods" return the object, which means that you can chain invocations.

Suppose that we have a Java class as follows:

We can set all fields by chaining invocations as in:

It should be noted that Golo won’t bypass the regular Java visibility access rules on fields.

Golo support property-style method calls.

Given a property name(), Golo will translate the method call to a {get|is or set}Name method call. Obviously, if a field is not accessible (ie. private) and doesn’t have a getter or setter, the resolution will fail. Finally, write-only properties can be chained (ie: return the current this instance), unless a return value is defined in the according setter method.

We will illustrate both how to deal with public static inner classes and enumerations at once.

The rules to deal with them in Golo are as follows.

Let us consider the following example:

Running it yields the following console output:

Because Golo provides a few named operators such as is, and or not, they are recognized as operator tokens.

However, you may find yourself in a situation where you need to invoke a Java method whose name is a Golo operator, such as:

This results in a parsing error, as is and not will be matched as operators instead of method identifiers.

The solution is to use escaping, by prefixing identifiers with a backtick, as in:

Golo provides a class loader for directly loading and compiling Golo modules. You may use it as follows:

This would work with a Golo module defined as in:

Indeed, a Golo module is viewable as a Java class where each function is a static method.

java.lang.Class instances of primitive data types can be obtained as in Java way: byte.class, short.class, int.class, long.class, float.class, double.class, boolean.class and char.class.

Golo supports the traditional if / else constructions, as in:

The condition of an if statement does not need parenthesis. You may add some to clarify a more elaborated expression, though.

Golo offers a versatile case construction for conditional branching. It may be used in place of multiple nested if / else statements, as in:

A case statement requires at least 1 when clause and a mandatory otherwise clause. Each clause is being associated with a block. It is semantically equivalent to the corresponding if / else chain:

The match expression is a convenient shortcut for cases where a case statement would be used to match a value, and give back a result. While it may resemble pattern matching operators in some other languages it is not fully equivalent, as Golo does not support full destructuring matching (but with can help here).

match is a great addition to the Golo programmer:

The values to be returned are specified after a then keyword that follows a boolean expression to be evaluated.

Like case statements, a match construct needs at least one when clause and one otherwise clause.

While loops in Golo are straightforward:

The parenthesis in the while condition may be omitted like it is the case for if statements.

This is the most versatile loop construction, as it features:

The following function shows a for loop:

As you can see, it is very much like a for loop in Java, except that:

Again, this choice is dictated by the pursue of simplicity.

Golo provides a "for each" style of iteration over iterable elements. Any object that is an instance of java.lang.Iterable can be used in foreach loops, as in:

In this example, item is a variable within the foreach loop scope, and iterable is an object that is expected to be iterable.

You may use parenthesis around a foreach expression, so foreach (foo in bar) is equivalent to foreach foo in bar.

There is a variant of the foreach loop with a when guard.

The following code:

can be simplified as:

The when guard can be any expression that evaluates to a boolean.

Although not strictly necessary, the break and continue statements can be useful to simplify some loops in imperative languages.

Like in Java and many other languages:

Consider the following contrived example:

Golo does not support break statements to labels like Java does. In fact, this is a goto statement in disguise.

Some programming languages return values from selected control flow constructions, with the returned value being the evaluation of the last statement in a block. This can be handy in some situations such as the following code snippet in Scala:

The Golo original author recognizes and appreciates the expressiveness of such construct. However, he often finds it harder to spot the returned values with such constructs, and he thought that trading a few keystrokes for explicitness was better than shorter construct based in implicitness.

Therefore, most Golo control flow constructions do not return values, and programmers are instead required to extract a variable or provide an explicit return statement.

Golo provides 2 predefined functions for raising exceptions:

Throwing an exception is thus as easy as:

Of course not every exception shall be an instance of java.lang.RuntimeException. When a more specialized type is required, you may simply instantiate a Java exception and throw it using the throw keyword as in the following example:

Exception handling uses the familiar try / catch, try / catch / finally and try / finally constructions. Their semantics are the same as found in other languages such as Java, especially regarding the handling of finally blocks.

The following snippets show each exception handling form.

Defining a closure is straightforward as it derives from the way a function can be defined:

At runtime, a closure is an instance of gololang.FunctionReference, which is essentially a boxing of java.lang.invoke.MethodHandle. This means that you can do all the operations that method handles support, such as invoking them or inserting arguments as illustrated in the following example:

As one would expect, this prints 3 and 12.

In order to make closure’s invocations more fluent you can insert argument using the closure’s parameter names.

Golo supports a compact form of closures for the cases where their body consists of a single expression. The example above can be simplified as:

You may also use this compact form when defining regular functions, as in:

While you may call function references using invoke, there is a (much) better way.

When you have a reference to a closure, you may simply call it as a regular function. The previous adder example can be equivalently rewritten as:

Closures have access to the lexical scope of their defining environment. Consider this example:

The plus_3 function returns a closure that has access to the foo reference, just as you would expect. The foo reference is said to have been captured and made available in the closure.

It is important to note that captured references are constants within the closure. Consider the following example:

The compilation fails because although a is declared using var in its original scope, it is actually passed as an argument to the f closure. Because function parameters are implicitly constant references, this results in a compilation error.

That being said, a closure has a reference on the same object as its defining environment, so a mutable object is a sensible way to pass data back from a closure as a side-effect, as in:

which prints [I heard you say, Hey!, Hey!].

The Java SE APIs have plenty of interfaces with a single method: java.util.concurrent.Callable, java.lang.Runnable, javax.swing.ActionListener, etc.

The predefined function asInterfaceInstance can be used to convert a method handle or Golo closure to an instance of a specific interface.

Here is how one could pass an action listener to a javax.swing.JButton:

Because the asInterfaceInstance call consumes some readability budget, you may refactor it with a local function as in:

Here is another example that uses the java.util.concurrent APIs to obtain an executor, pass it a task, fetch the result with a Future object then shut it down:

Java 8 introduced support for the so-called lambdas. The mechanism works through functional interfaces, that is, interfaces with a single abstract method that are annotated with @FunctionalInterface.

Golo provides a asFunctionalInterface pre-defined function to convert closures and that works like the asInterfaceInstance function:

When a function or method parameter of a Java API expects a single method interface type or a functional interface, you can pass a closure directly, as in:

Note that this causes the creation of a method handle proxy object for each function or method invocation. For performance-sensitive contexts, we suggest that you use either asInterfaceInstance, the to conversion method described hereafter, or asFunctionalInterface.

Instead of using asInterfaceInstance, you may use a class augmentation which is described later in this documentation. In short, it allows you to call a to method on instances of MethodHandle, which in turn calls asInterfaceInstance. Back to the previous examples, the next 2 lines are equivalent:

You may also take advantage of the predefined fun function to obtain a reference to a closure, as in:

Last but not least, we have an even shorter notation if function are not overridden:

If the function is overridden, that is several functions exist with the same name but different arities, you must specify the arity with the notation ^moduleName::functionName\arity. For instance:

In this case, one can even specify if a varargs function is needed or not (since arity alone can be ambiguous) using final …​:

Note that you can in the same way get a reference to a Java static method. For instance:

You can also get a reference to a non-static method. In this case, the function will accept an instance of the class as first argument, as in:

You can bind a function first argument using the bindTo(value) method. If you need to bind an argument at another position than 0, you may take advantage of bindAt(position, value):

You may compose functions using the andThen method:

or:

Given that functions are first-class objects in Golo, you may define functions (or closures) that return functions, as in:

You could use intermediate references to use the f function above:

Golo supports a nicer syntax if you don’t need intermediate references:

print and println do just what you would expect.

readln() or readln(strMessage) reads a single line of text from the console. It always returns a string.

readPassword() or readPassword(strPassword) reads a password from the console with echoing disabled. It always returns a string. There are also secureReadPassword() and secureReadPassword(strPassword) variants that return a char[] array.

Sometimes it is very desirable to read the content of a text file. The fileToText function does just that:

The first parameter is either a java.lang.String, a java.io.File or a java.nio.file.Path. The second parameter represents the encoding charset, either as a java.lang.String or a java.nio.charset.Charset.

We can write some text to a file, too:

The textToFile function overwrites existing files, and creates new ones if needed.

These functions are provided for convenience, so if you need more fine-grained control over reading and writing text then we suggest that you look into the java.nio.file package.

In addition, if you need to verify that a file exists, you can use the fileExists function.

As in the other File I/O methods, the parameter is either a java.lang.String, a java.io.File or a java.nio.file.Path. The fileExists function will return true if the file exists, false if it doesn’t.

If you need the current path of execution, you can use the currentDir function.

The following functions convert any number of string value to another number type: intValue(n), longValue(n), charValue(n), doubleValue(n) and floatValue(n).

The usual Java type narrowing or widening conventions apply.

raise can be used to throw a java.lang.RuntimeException. It comes in two forms: one with a message as a string, and one with a message and a cause.

Preconditions are useful, especially in a dynamically-typed language.

require can check for a boolean expression along with an error message. In case of error, it throws an AssertionError.

You may also use requireNotNull that…​ well…​ checks that its argument is not null:

Golo arrays can be created using the array[…​] literal syntax. Such arrays are of JVM type Object[].

There are cases where one needs typed arrays rather than Object[] arrays, especially when dealing with existing Java libraries.

The newTypedArray predefined function can help:

The range function yields an iterable range over either Integer, Long or Character bounds:

The lower bound is inclusive, the upper bound is exclusive.

A range with a lower bound greater than its upper bound will be empty, except if the increment is explicitly negative:

The reversedRange function is an alias for range with an increment of -1, such that reversedRange(5, 1) is the same as range(5, 1): decrementBy(1).

When range is called with only one value, it is used as the upper bound, the lower one being a default value (0 for numbers, 'A' for chars). For example, range(5) == range(0, 5) and range('Z') == range('A', 'Z'). In the same way, reversedRange(5) == reversedRange(5, 0).

Two ranges are equals if they have the same bounds and increment.

A range can also be defined with the literal notation [begin..end], which is equivalent to range(begin, end).

Given a function reference, one can convert it to an instance of an interface with a single method declaration, as in:

It is possible to test if an object is a closure or not with the isClosure function. This is useful to support values and delayed evaluation, as in:

You can get a reference to a closure using the predefined fun function:

Because functions may be overloaded, there is a form that accepts an extra parameter for specifying the number of parameters:

While asInterfaceInstance works for single-method interfaces, Java 8 introduced default methods and functional interfaces to support the so-called lambda expressions.

The asFunctionalInterface function is similar to asInterfaceInstance and supports these types of adaptations:

Golo does not provide a literal syntax for array types, such as Object[].class in Java.

Instead, we provide 3 helper functions.

mapEntry gives instances of java.util.AbstractMap.SimpleEntry, and is used as follows:

box gives instances of java.util.concurrent.atomic.AtomicReference, and can be used to create a mutable reference where not possible otherwise, e.g. in closures, as in:

Let us motivate the value of augmentations by starting with the following example. Suppose that we would like a function to wrap a string with a left and right string. We could do that in Golo as follows:

Defining functions for such tasks makes perfect sense, but what if we could just add the wrap method to all instances of java.lang.String instead?

Defining an augmentation is a matter of adding a augment block in a module:

More specifically:

It is a good convention to name the receiver this, but you are free to call it differently.

Also, augmentation functions can take variable-arity arguments, as in:

It should be noted that augmentations work with class hierarchies too. The following example adds an augmentation to java.util.Collection, which also adds it to concrete subclasses such as java.util.LinkedList:

By default, an augmentation is only visible from its defining module.

Augmentations are clear and explicit as they only affect the instances from which you have decided to make them visible.

It is advised to place reusable augmentations in separate module definitions. Then, a module that needs such augmentations can make them available through imports.

Suppose that you want to define augmentations for dealing with URLs from strings. You could define a string-url-augmentations.golo module source as follows:

Then, a module willing to take advantage of those augmentations can simply import their defining module:

To allow building libraries of functions leveraging augmentations, the callstack is also looked up in order to find if a complying augmentation was applied to the function arguments. It is thus possible to create a function like:

that can be applied on any object having a plop method, provided this is a native method or it is defined in an augmentation imported in the calling module.

It is possible for augmentations to have a name. A named augmentation is a set of functions that can be applied to some classes or structures.

This can be seen as a kind of lightweight trait, or mixin, as found in Rust, Groovy or Scala.

Named augmentations are defined with the augmentation keyword.

As an example:

A named augmentation is applied using the augment …​ with construct, as in

When applying several named augmentations, they are used in the application order. For instance, if AugmentA and AugmentB define both the method meth, and we augment augment java.lang.String with AugmentA, AugmentB, then calling "": meth() will call AugmentA::meth.

Augmentation rules about scopes and reusability apply. So, if we create a module

and import it, we can use the applied augmentation

The augmentations defined in an other module can also be applied, provided they are fully qualified or the module is imported:

or

The validity of the application is not checked at compile time. Thus augmenting without importing the coresponding module, as in:

will not raise an error, but trying to call search on a String will throw a java.lang.NoSuchMethodError: class java.lang.String::search at runtime.

The augmentations resolution order is as follows:

The first matching method found is used. It is thus possible to “override” an augmentation with a more higher priority one (in the sens of the previous order). Implicit modules are imported after explicit ones to allow to redefine standard augmentations.

Users can augment a class with a fallback behavior to give a very last chance to a failed method dispacth.

Golo comes with a set of pre-defined augmentations over collections, strings, closures and more.

These augmentation do not require a special import, and they are defined in the gololang.StandardAugmentations module.

Here is an example:

The full set of standard augmentations is documented in the generated golodoc (hint: look for doc/golodoc in the Golo distribution).

Structures are defined at the module-level:

When declaring a structure, it also defines two factory functions: one with no argument, and one with all arguments in their order of declaration in the struct statement. When not initialized, member values are null.

Each member yields a getter and a setter method: given a member a, the getter is method a() while the setter is method a(newValue). It should be noted that setter methods return the structure instance which makes it possible to chain calls as illustrated in the previous example while building p2.

Each struct is compiled to a self-contained JVM class.

Given:

a class sample.types.Point is being generated.

It is important to note that:

The toString() method is being overridden to provide a meaningful description of a structure content.

Given the following program:

running it prints the following console output:

Structure instances are mutable by default. Golo generates a factory function with the Immutable prefix to directly build immutable instances:

Golo generates two factories for structures. One for the initial values of each member and a second one with no parameters:

running it prints the following console output:

The Factories generated by Golo can be overloaded by custom ones:

running it prints the following console output:

Instances of a structure provide copying methods:

Trying to invoke any setter methods on an instance obtained through frozenCopy() raises a java.lang.IllegalStateException.

Golo structures honor the contract of Java objects regarding equality and hash codes.

By default, equals() and hashCode() are the ones of java.lang.Object. Indeed, structure members can be changed, so they cannot be used to compute stable values.

Nevertheless, structure instances returned by frozenCopy() have stable members, and members are being used.

Consider the following program:

the console output is the following:

Golo structures are comparable with structures of the same type, provided that their members are comparable pairwise. Two structure are compared by comparing their members lexicographically, that is pairwise in the order they are defined.

For instance, the following listing:

will output:

even if Triplet and Other have the same members.

A number of helper methods are being generated:

By default, all members in a struct can be accessed. It is possible to make some elements private by prefixing them with _, as in:

In this case, _b is a private struct member. This means that foo: _b() and foo: _b(666) are valid calls only if made from:

Any call to, say, foo: _b() from another module will yield a NoSuchMethodError exception.

Private struct members also have the following impact:

Structs provide a simple data model, especially with private members for encapsulation.

Augmenting structs is encouraged, as in:

When an augmentation on a struct is defined within the same module, then you can omit the full type name of the struct:

Again, it is important to note that augmentations can only access private struct members when they originate from the same module.

Unions are defined at the module-level:

Some well known usages of sum types are the following.

A union type is compiled to an abstract JVM class. Each alternative value type is itself compiled to a final immutable JVM class extending the abstract class. The value classes are member classes of the abstract one.

Given:

three classes are generated:

For your convenience, the abstract class provides factories static methods for each of the possible values, and you can’t instantiate values directly, since values without fields are actually singletons.

Note that proper definitions of toString(), hashCode() and equals() are provided. These definitions are similar to the ones defined for frozen struct.

Unions feature special methods to test for the exact type of a value, as well as members values if applicable. This allows to write readable tests, more specially using the match clause, to look like destructuring match in languages like OCaml, Haskell or Scala.

For instance, given a union defining a binary tree:

one can match a elt value using:

More precisely, each possible union value provides parameterless methods testing its exact type, named is<TypeName>. In the tree example, three methods are defined: isEmpty(), isLeaf() and isNode(). In addition to these methods, a method with parameters is defined for every alternative with members, here isLeaf(value) and isNode(left, right). The arguments are compared for equality to the members of the union value. For instance:

allowing readable test and match clauses.

A special singleton value is available to make these clauses even more readable: the Unknown value. This special singleton is considered equal to any other object (except null), and thus can be used in the parametrized test methods to ignore some members. For instance, to match a Node with only one child, one can use:

Since the union itself is a abstract class, and each possible value is a concrete class extending it, it is possible to augment the whole union, as in:

or just a value, as in:

Creating a dynamic object is as simple as calling the DynamicObject function:

A dynamic object can also be tagged using an arbitrary value as its kind. To create a tagged dynamic object, simply use a value in the constructor:

Dynamic objects have the following reserved methods, that is, methods that you cannot override:

Moreover, a suitable toString method is provided, but you can override it by defining a toString method.

Defining values also defines getter and setter methods, as illustrated by the next example:

Calling a setter method for a non-existent property defines it, hence the previous example can be rewritten as:

Dynamic object methods are simply defined as closures. They must take the dynamic object object as their first argument, and we suggest that you call it this. You can then define as many parameters as you want.

Here is an example where we define a toString-style of method:

The properties() method returns a set of entries, as instances of java.util.Map.Entry. You can thus write code such as:

Because dynamic object entries mix both values and function references, do not forget that the predefined isClosure(obj) function can be useful to distinguish them.

The fallback(handler) method let’s the user define a method that is invoked whenever the initial method dispatch fails. Here is an example of how to define a fallback.

A delegate function is available to ease defining a fallback function that delegates on another dynamic object. For instance:

The kind of a dynamic object can be any value. The more typical values are strings and unions (enumerations). This value is used by the toString() method to display a more specific representation of the object, and defaults to the string "DynamicObject". By using the two predefined methods hasKind(value) and sameKind(other), it is possible to test for the kind of a dynamic object. Note that the kind of a created object can’t be changed.

Let us get started with a simple example of a web application based on the nice Spark micro-framework ^[1].

Spark requires route handlers to extend an abstract base class called spark.Route. The following code snippet does just that:

This is as easy as providing a java.lang.Iterable as part of the configuration:

Implementations are great, but what happens if you need to call the parent class implementation of a method? In Java, you would use a super reference, but Golo does not provide that.

Instead, you can override methods, and have the parent class implementation given to you as a method handle parameter:

You can pass * as a name for implementations or overrides. In such cases, the provided closure become the dispatch targets for all methods that do not have an implementation or override. Note that providing both a star implementation and a star override is an error.

Let us see a concrete example:

The case of star implementation is similar, except that the closure takes only 2 parameters: |name, args|.

The AdapterFabric constructor can also take a class loader as a parameter. When none is provided, the current thread context class loader is being used as a parent for an AdapterFabric-internal classloader. There is also a static method withParentClassLoader(classloader) to obtain a fabric whose class loader is based on a provided parent.

As it is often the case for dynamic languages on the JVM, overloaded methods with the same name but different methods are painful. In such cases, we suggest that you take advantage of star-implementations or star-overrides as illustrated above on a ArrayList subclass where the 2 add(obj) and add(index, obj) methods are being intercepted.

Finally we do not encourage you to use adapters as part of Golo code outside of providing bridges to third-party APIs.

This is another way to use the adapters. You can see that as a kind of DSL for the Golo adapters. Let’s see how to re-write the examples in the previous paragraph

Decorators are similar in syntax and purpose to Java annotations. However, the concepts behind them are very different. Indeed, whereas Java annotations are compiler or VM directives, decorators are actually plain functions, more precisely higher order functions.

A decorator is thus a function that take the function to decorate as parameter, and return a new function, generally a wrapper that do some stuffs before or after calling the original function.

The name can remind the well known GoF Pattern, with good reason. This pattern describe a design that allow an object to be augmented by wrapping it in an other object with the same interface, delegating operations to the wrapped object. This is exactly what a decorator does here, the interface being “function” (more precisely a gololang.FunctionReference).

As in Python, and similarly to Java annotations, a decorator is used with a @ prefix before the function definition. As an example, the decorator deco1 only prints its name before returning the result unchanged

It can be used as:

Here, calling println(foo(1)) will print deco1 + foo: 1.

To be the most generic, the function created by a decorator should be a variable arity function, and thus call the decorated function with invoke, such that it can be applied to any function, regardless of its arity, as in the previous example.

Indeed, suppose you what to a decorator dec (that does nothing) used like:

Such a decorator can be implemented as:

But in that case, it will be applicable to two parameters functions only. On the other hand, you cannot do:

Indeed, this will throw an exception because func is not a variable arity function (just a reference on add function) and thus cannot take an array as parameter. In this case, the decorator have to invoke the original function like this:

which is equivalent to the first form, but is not generic. The more generic decorator is thus:

which can deal with any function.

As illustrated, the decorator is just a wrapper (closure) around the decorated function. The @ syntax is just syntactic sugar. Indeed, it can also be used as such:

prints all deco1 + bar: 1.

Decorators can also be stacked. For instance:

println(baz(1)) will print deco2 + deco1 + baz: 1

This result can also be achieved by composing decorators, as in:

Again, println(spam(1)) will print deco2 + deco1 + spam: 1

Moreover, since decorator are just higher order functions, they can be closure on a first argument, i.e. parametrized decorators, as illustrated in the following listing:

will print

Here, log create a closure on the message, and return the decorator function. Thus, log("hello") is a function that take a function as parameter, and return a new function printing the message (hello) before delegating to the inner function.

Again, since all of this are just functions, you can create shortcuts:

A call to println(baz()) will print

The only requirement is that the effective decorator (the expression following the @) is eventually a HOF returning a closure on the decorated function. As an example, it can be as elaborated as:

where a call foo("bar") will print

and with

calling bar() will print

or even, without decorator syntax:

A last thing (but not the least), the function returned by the decorator can have a different arity than the original one:

The @curry decorator transform the add function that takes two arguments, into a function that takes only one argument and returns a function that takes the second argument and finally return the result of the addition.

Let’s call this from Golo:

will print:

Let’s now illustrate with some use cases and examples, with a presentation of some decorators of the standard module gololang.Decorators.

Use cases are at least the same as aspect oriented programming (AOP) and the Decorator design pattern, but your imagination is your limit. Some are presented here for illustration.

A function call marked with bang (!) will be called only once, the result is stored as a constant and will be directly returned for every subsequent call.

A function call can be marked with a bang like in the following example:

In this example take_a_while is computed only once at the first call, and then this function returns directly the previously computed result as a constant for every subsequent call.

Bang function call is a kind of memoization but regardless of the given parameters:

In this example hello is executed at the first call with the parameter "Peter", then always returns "Hello Peter!", even when called with other values.

The result of a banged function call is constant within the same call place, but different for each call instructions.

In the previous listing, the hello!(name) in the loop is considered the same call, and thus evaluated only on the first iteration. On the other hand, the previous calls with "Foo" and "Bar" are distinct, and therefore prints different results.

Anonymous function call and object constructor call can be banged too:

In this example closure(i)!(i) always return 0 because:

The singleton function return a new java Object but the java.lang.Object is created with a banged constructor call, then the returned reference is constant.

As explained in the decorators part the following identity function:

is expanded to:

A banged decorator declared with the @! syntax:

is expanded to:

As seen previously, the decorator function is called only the first time. For every subsequent call, the function reference returned by the decorator is not re-computed but directly used as a constant.

Parametrized decorators can be banged too:

is expanded to:

As an example, consider two functions decorated with the same parametrized decorator:

These functions are expanded to

deco("a")!(|a| → a) return a function that we can name for the example func_a, and deco("b")!(|b| → b) return another function that we can name func_b.

Then, for every subsequent call of foo and bar, the executed code is somehow equivalent to:

func_a and func_b are now constant but different because they are not from the same "banged call instruction".

Performances can considerably increase with banged decorators, since the decorator function is no more called for each decorated function call. On the other hand, the decorator function has to be pure (without side-effects) and his parameters stable.

The code of a complete module can be evaluated by the asModule method:

It is important to note that an EvaluationEnvironment instance has a GoloClassloader, and that attempting to evaluate module code with the same module declaration will cause an error. Indeed, a class loader cannot load classes with the same name twice.

The anonymousModule method is similar to asModule, except that the code to evaluate is free of module declaration:

The modules that get evaluated through anonymousModule have unique names, hence this method is suitable in cases where the same code is to be re-evaluated several times.

The asFunction and def methods evaluate function code. Here is how asFunction can be used:

It evaluates straight code as the body of a function. Note that imports can be used to specify import statements to be available while evaluation the code:

The def method is similar, except that it has the parameters definition in the code to evaluate:

The first form of run method works as follows:

The second form allows passing parameter values in a map:

It is important not to abuse run, as each invocation triggers the generation of a one-shot class. If the same code is to be run several times, we suggest that you take advantage of either def or asFunction.

A worker is simply a Golo function that can be executed concurrently. You can pass messages to a worker, and they are eventually received and handled by their target worker. In other words, workers react to messages in an asynchronous fashion.

Communications between a worker and some client code happens through ports. A port is simply an object that is responsible for dispatching a message to its worker.

Ports are obtained by spawning a worker function from a worker environment. Internally, a worker environment manages a java.util.concurrent executor, which means that you do not have to deal with thread management.

Worker environments are defined in the gololang.concurrent.workers.WorkerEnvironment class / module.

You can directly pass an instance of java.util.concurrent.ExecutorService to its constructor, or you may go through its builder object and call either of the following static methods:

In most scenarios withCachedThreadPool() is a safe choice, but as usual, your mileage varies. If you have many concurrent tasks to perform and they are not IO-bound, then withFixedThreadPool() is probably a better option. You should always measure, and remember that you can always pass a fine-tuned executor to the WorkerEnvironment() constructor.

Worker environments also provide delegate methods to their internal executor. It is important to call shutdown() to close the workers environment and release the threads pool. You can also call the awaitTermination, isShutdown and isTerminated methods whose semantics are exactly those of java.util.concurrent.ExecutorService.

Worker functions take a single parameter which is the message to be received. To obtain a port, you need to call the spawn(target) function of a worker environment, as in:

A port provides a send(message) method:

Messages are being put in a queue, and eventually dispatched to the function that we spawned.

To better understand how workers can be used, here is a (fairly useless) example:

In this example, we spawn 3 workers:

As an aside, the example illustrates that worker functions may take further dependencies as arguments. The pusher function takes a queue target and generator needs a port.

You can satisfy dependencies by pre-binding function arguments, all you need is to make sure that each function passed to spawn only expects a single message as its argument, as in:

Consider the following example.

This multi-line string has a Golo template. It can be compiled into a function as follows:

As you may have guess from the previous example:

When no <%@params …​ %> exists, the function is assumed to have a single params parameter.

First, let’s remind some basis of the compilation process. Here is a simplified view of the way Golo compiles a program:

The IR tree is a logical representation of the program structure, independently of the text (and even the concrete syntax). A representation of this tree can be seen using the golo diagnose command.

As an example, the following Golo code

gives the following (simplified) IR:

Golo macros are functions that manipulate this IR tree at compile time, between the steps 2 and 3 above. They are similar to C preprocessing macros, but much more powerful and robust.

Using macros, one can generate functions and types and inject them in the program, create alternative control structures that will be transformed into regular ones, or create instructions computed at compile time instead of runtime (e.g. display debug messages if a environment variable is set).

More generally, macros can be seen as a way to trade dynamic runtime dependencies for static compile time ones. Indeed, many dynamic Golo features, like module imports or named augmentations, can be made static by using macros instead.

Macros are regular functions (or Java static methods) whose parameters are IR nodes, and that return an IR node.

In order to identify macro calls in the IR and to provide some checks, macros need to be identified as such. A Java static method intended to be used as a macro must be annotated with the org.eclipse.golo.compiler.macro.Macro annotation. In the same way, a Golo function that is actually a macro is declared using the macro keyword instead of function. It is otherwise a regular function.

Most macros work by returning a new node that will replace the macro call in the final IR tree (see Substituting macros). It is thus necessary to create a subtree representing the Golo code that will be compiled. To ease this creation, a fluent API over the IR tree elements is provided.

Since macros are expanded at compile time, they can be difficult to test and debug. Here are some advices.

As already said, the diagnose command displays the internal representation of the parsed code. Its --stage option can configure which compilation step is dumped:

These options are useful to inspect the result of expanding macros, for debugging purpose for instance. The golo.macros.recursion-limit system property can be used to tweek the nested macros expansion, to dump intermediary expansion steps.

As an alternative, it is possible to dump the same representation of any IR node using its dump method. This can be used to inspect the arguments of a macro, or the produced node, when debugging a macro. It is moreover possible to manually expand the macros in a node by using the expand and expandOnce methods of the compiler (which can be accessed using gololang.Runtime.classLoader(): compiler()).

To debug macros, the expansion process can be tuned using some predefined special macros that configure the recursion limit, regular call expansion, and so on (see the gololang.macros module).

The golo.debug.macros system property can be set to true to allow the expansion process to be really verbose about its work.

To ease the tests and debugging of macro functions, as well as improve code reuse, it is strongly recommended to define regular functions that create IR nodes, and call these functions from macros. Indeed, it is easier to call such a function in a test suite to inspect its result. In anyway, a macro can be called as a regular function (i.e. at runtime) either by using the dontExpandRegularCalls special macro and calling the macro without the & prefix (e.g. in a test module) or by using a function reference (e.g. ^module::macro()). Calling a special or contextual macro as a regular function is however tricky since the implicit arguments (the macro call and the expansion engine resp.) are not injected and must therefore be supplied explicitly.

Here are some example of macros, to whet your appetite.

Golo provides a support for documentation blocks on modules, functions, augmentations, structs and unions, as well as fields. Blocks are delimited by ---- and contain free-form Markdown ^[7] text.

Here is a quick example:

Sections can be added in the documentation using the normal markdown syntax. The level of the titles is adapted to the generated documentation. For instance:

The first sentence of a module documentation is displayed in module indexes.

Packages does not exists per se in Golo, but are represented in the form of module qualified names. However, it is common practice to group the modules of the same namespace into a common directory. There exists several ways to document such packages. The first is to create an empty golo module named after the package, containing the documentation. This file can have any name and be in any directory. For instance, given several modules pkg.MyModule and pkg.OtherModule, one can document the pkg package by creating a module containing:

No class will be compiled from this module, only a documentation page.

The other way to document the pkg package, assuming that both modules are in src/pkg/MyModule.golo and src/pkg/OtherModule.golo respectively, is to create pure markdown file, containing the documentation for the package. This file must be named either src/pkg/README.md, src/pkg/package.md or src/pkg.md. If a golo file corresponding to the package exists, these files are ignored.

If several candidates are found, only the first one is used, and a warning is printed. It can be disabled by setting the golo.warnings.doc.multiple-package-desc system property to false.

The golo doc command can render documentation in html (the default) or markdown format:

In addition, golo doc can also produce ctags tags file, to be used by editors such as Vim or emacs. In this mode, the special output target - can be used to print the tags on standard output, which is needed by some editors or extensions.

Please consult golo --usage doc for more details.

It is sometimes necessary to indent documentation blocks to match the surrounding code format. Documentation blocks erase indentation based on the indentation level of the opening block:

When generating documentation from the code above, the documentation block of the toURL function is unindented of 2 spaces.

This Golo module provides standard augmentations for various classes of the Java standard classes and Golo types. It does not have to be imported explicitely.

Here are a few examples.

Java collections can be have functional methods:

Insert a map entry only if the key is not present, and get a default value if an entry is missing:

Repeat an operation many times:

Golo includes the JSON Simple library to provide JSON support.

While json-simple only supports encoding from lists and maps, this API brings support for sets, arrays, Golo tuples, dynamic objects and structs.

Given a simple data structure, we can obtain a JSON representation:

Given some JSON as text, we can get back a data structure:

The gololang.JSON module also provides helpers for JSON serialization and deserialization with both dynamic objects and structs.

Golo has a DynamicVariable type that mimics the eponymous class from the Scala standard library.

A dynamic variable has inheritable thread-local semantics: updates to its value are confined to the current thread and its future child threads.

Given the following code:

one gets an output similar to:

with the 69 and 666 swapping order over runs.

An observable value notifies observers of updates in a thread-safe manner. An observable can also be constructed from another observable using the map and filter combinators:

This yields the following output:

This module offers asynchronous programming helpers, especially execution context agnostic promises and futures. The provided APIs are orthogonal to the execution strategy: it is up to you to execute code from the same thread, from a separate thread, or by pushing new tasks to a service executor.

Here is an example:

This example takes advantages of an executor augmentation and composable promises and futures to compute Fibonacci numbers.

This module defines a lazy list structure, as well as some utilities to work with it.

A lazy list behaves like an immutable linked list whose elements are evaluated only when needed, as can be found in Haskell for example.

The next element in the list (the tail) is represented by a closure. The generated value is cached so that the closure representing the next element is evaluated only once.

This is very useful when using higher order function such as map. Mapping a long lazy list with a function and using only the 3 first elements will only apply the function to these elements, as opposed to regular lists.

Since the tail closure will be called at most once, and we can’t guarantee when, or even if, it will be called, this closure must be a pure, side-effect free, function.

Lazy lists can also be used to create infinite lists, also known as generators (or anamorphisms).

Lastly, they allow for elegant recursive implementations of several classical algorithms.

For instance, one can create a infinite lazy list containing integers as:

To construct a infinite list of all even multiples of 3, one can then use:

The cons function returns a new lazy list whose head is its first argument, and the tail its second.

A lazy list implement the Collection interface, while remaining lazy. It is thus possible to use it in imperative style with a foreach construct, or recursively using head and tail. On the other hand, functions or methods like equals, size or contains are not very efficients, since they must evaluate the whole list, and thus negate the laziness. They are here for completeness and compatibility with the regular lists interface, but you should avoid such methods.

The gololang.AnsiCodes modules offers a set of functions to work with ANSI codes.

The following would print Hello world! in blinking yellow text:

The gololang.Errors module offers types, augmentations and decorators to deal with errors in a more functional way. This is similar for instance to Haskell Maybe and Either or Rust Option and Result.

Golo does not have a new operator for allocating objects. Instead, one should just call a constructor as a function:

Golo does not have star imports like in Java. Imports are only used at runtime as Golo tries to resolve names of types, functions, and so on.

You must think of import statements as a notational shortcut, nothing else. Golo tries to resolve a name as-is, then tries to complete with every import until a match is found.

Keep in mind that instance methods are invoked using the : operator, not with dots (.) like in many languages.

This is a common mistake!

One thing to keep in mind is that match returns a value, and that it is not a closure unless you want it to.

When running shebang scripts, the sub-folders are being scanned for .jar and .golo files. This is useful for automatically:

Be aware that this may lead to surprising errors if you run code from, say, a clone of the Golo source code repository since it contains duplicated type and module definitions, as well as files from the test suite that have errors on purpose.