This is the documentation for the Golo programming language.

Copyright and License Notice
Copyright 2012-2014 Institut National des Sciences Appliquées de Lyon (INSA-Lyon)

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
limitations under the License.


Let us start with the Golo basics.

Editor / IDE support

Editor and IDE support for Golo is available for:

Hello world

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:

module hello.World

function main = |args| {
  println("Hello world!")

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.

Note Newlines are important in Golo, so make sure that your editor ends files with a newline.
Note Golo identifiers can be non-ascii characters (e.g., Japanese, Emoji, Arabic, etc).

Running "Hello world"

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:

  • version to query the Golo version, and

  • compile to compile some Golo code to JVM classes, and

  • run to execute some already compiled Golo code, and

  • golo to directly execute Golo code from source files, and

  • diagnose to print compiler internal diagnosis information, and

  • doc to generate module(s) documentation, and

  • new to generate new project(s).

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

Important The golo script comes with JVM tuning settings that may not be appropriate to your environment. We also provide a vanilla-golo script with no tuning. You may use the $JAVA_OPTS environment variable to provide custom JVM tuning to vanilla-golo.

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

$ golo golo --files samples/helloworld.golo
Hello world!
$ golo golo --files samples/ --module hello.World
Hello world!

golo golo takes several Golo source files (*.golo and directories) as input. It expects the last one 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:

module EchoArgs

function main = |args| {
  foreach arg in args {
    println("->  " + arg)

We may invoke it as follows:

$ golo golo --files samples/echo-args.golo --args plop da plop
-> plop
-> da
-> plop

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. See the golo help command for details on the various Golo commands.

Compiling Golo source code

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

Compiling Golo files is straightforward:

$ golo compile --output classes samples/helloworld.golo

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

$ tree classes/
└── hello
    └── World.class

1 directory, 1 file

Running compiled Golo code

Golo provides a golo command for running compiled Golo code:

$ cd classes
$ golo run --module hello.World
Hello world!

Simple, isn’t it?

Passing JVM-specific flags

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:

# Exporting an environment variable
$ export JAVA_OPTS=-XX:+PrintCompilation
$ golo golo --files samples/fibonacci.golo

# ...or you may use this one-liner
$ JAVA_OPTS=-XX:+PrintCompilation golo golo --files samples/fibonacci.golo

Bash autocompletion

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.

Tip Not sure where your bash_completion.d/ folder is? Try /etc/bash_completion.d/ on Linux or /usr/local/etc/bash_completion.d/ for Mac Homebrew users.

Zsh autocompletion

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:

# This is a comment
println("WTF?") # it works here, too

Variable and constant references

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:

# Ok
var i = 3
i = i + 1

# The assignment fails because truth is a constant
let truth = 42
truth = 666

# Invalid statement, variables / constants have to be initialized
var foo

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.

# Ok, but not necessarily great for humans...
let _$_f_o_$$666 = 666

# Wrong!
let 666_club = 666

Data literals

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.

Java type Golo literals




true or false


"hello world"


'a', 'b', …


123, -123, 1_234, …


123_L, -123_L, 1_234_L, …


1.234, -1.234, 1.234e9, …


1.234_F, -1.234_F, 1.234e9_F, …


String.class, java.lang.String.class, gololang.Predef.module, …


^foo, ^some.module::foo, …

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

let text = """This is
a multi-line string.


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

This is
a multi-line string.

Collection literals

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

let s = set[1, 2, "a", "b"]
let v = vector[1, 2, 3]
let m = map[[1, "a"], [2, "b"]]
# (...)

The syntax and type matchings are the following:

Collection Java type Syntax



tuple[1, 2, 3], or simply [1, 2, 3]



array[1, 2, 3]



list[1, 2, 3]



vector[1, 2, 3]



set[1, 2, 3]



map[[1, "a"], [2, "b"]]



[1..10], ['a'..'f']

A note on tuples

Tuples essentially behave as immutable arrays.

The gololang.Tuple class provides the following methods:

  • a constructor with a variable-arguments list of values,

  • a get(index) method to get the element at a specified index,

  • size() and isEmpty() methods that do what their names suggest,

  • an iterator() method because tuples are iterable, and

  • equals(other), hashCode() and toString() do just what you would expect.

A note on maps

The map collection literal expects entries to be specified as tuples where the first entry is the key, and the second entry is the value. This allows nested structures to be specified as in:

  ["foo", "bar"],
  ["plop", set[1, 2, 3, 4, 5]],
  ["mrbean", map[
    ["name", "Mr Bean"],
    ["email", ""]

There are a few rules to observe:

  • not providing a series of tuples will yield class cast exceptions,

  • tuples must have at least 2 entries or will yield index bound exceptions,

  • tuples with more than 2 entries are ok, but only the first 2 entries matter.

Because of that, the following code compiles but raises exceptions at runtime:

let m1 = map[1, 2, 4, 5]
let m2 = map[
  ["a", "b"]

The rationale for map literals to be loose is that we let you put any valid Golo expression, like functions returning valid tuples:

let a = -> [1, 'a']
let b = -> [2, 'b']
let m = map[a(), b()]


Golo supports the following set of operators.

Symbol(s) Description Examples


Addition on numbers and strings.

1 + 2 gives 3.

"foo" + "bar" gives "foobar".

"foo" + something where something is any object instance is equivalent to "foo" + something.toString() in Java.


Subtraction on numbers.

4 - 1 gives 3.


Multiplication on numbers and strings.

2 * 2 gives 4.

"a" * 3 gives "aaa".


Division on numbers.

4 / 2 gives 2.


Modulo on numbers.

4 % 2 gives 0, 3 % 2 gives 1.

"<", "<=", "==", "!=", ">", ">="

Comparison between numbers and objects that implement java.lang.Comparable. == is equivalent to calling Object#equals(Object) in Java.

1 < 2 gives true.

is, isnt

Comparison of reference equality.

a is b gives true only if a and b reference the same object instance.

and, or, not

Boolean operators. not is of course a unary operator.

true and true gives true, not(true) gives false.


Checks the type of an object instance, equivalent to the instanceof operator in Java.

("plop" oftype String.class) gives true.


Evaluates an expression and returns the value of another one if null.

null orIfNull "a" gives "a". foo() orIfNull 0 gives the value of calling foo(), or 0 if foo() returns null.

Calling a method

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:

println(123: toString())
println(someObject: toString())

Java / JVM arrays

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:

  • get(index) returns the value at index,

  • set(index, value) sets value at index,

  • length() and size() return the array length,

  • iterator() returns a java.util.Iterator,

  • toString() delegates to java.util.Arrays.toString(Object[]),

  • asList() delegates to java.util.Arrays.asList(Object[]),

  • equals(someArray) delegates to java.util.Arrays.equals(this, someArray),

  • getClass() return the array class.

Given a reference a on some array:

# Gets the element at index 0
a: get(0)

# Replaces the element at index 1 with "a"
a: set(1, "a")

# Nice print
println(a: toString())

# Convert to a real collection
let list = a: asList()
Warning The methods above do not perform array bound checks.

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

let a = Array(1, 2, 3, 4)
let b = Array("a", "b")

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

let a = array[1, 2, 3, 4]
let b = array["a", "b"]

Creating new project(s)

The golo new command can create new Golo project(s):

$ golo new Foo

The command creates a new Golo module named Foo in a main.golo file with a simple function named main that takes an argument for the JVM program arguments.

By default we create a new free-form project but you can specify the type of project with the --type command argument. Three types of projects are currently available:

  • Free-form project,

  • Maven-driven project,

  • Gradle-driven project.

As an example if you want to create a Maven-driven project, just add --type maven:

$ golo new Foo --type maven

By default we create the project directory where the golo command is run. If you need to create your project directory elsewhere you can use the --path command argument:

$ golo new Bar --path /opt/golo

This creates the project directory named Bar in /opt/golo.

Free-form project

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

$ tree Foo
├── imports
├── jars
└── main.golo

Maven-driven project

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

$ tree Foo
├── pom.xml
└── src
    └── main
        └── golo
            └── main.golo

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

$ mvn package

You can now run the module Foo with:

  • mvn

$ mvn exec:java
  • java

$ java -jar target/Foo-*-jar-with-dependencies.jar
  • golo

$ cd target/classes
$ golo run --module Foo

Gradle-driven project

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

$ tree Foo
├── build.gradle
└── src
    └── main
        └── golo
            └── main.golo

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

$ gradle build

You can now run the module Foo with:

  • gradle

$ gradle run
  • golo

$ cd build/classes/main
$ golo run --module Foo


Functions are first-class citizen in Golo. Here is how to define and call some.

Parameter-less functions

Golo modules can define functions as follows:

module sample

function hello = {
  return "Hello!"

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

let str = hello()

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:

function printer = {

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

# result will be null
let result = printer()

Functions with parameters

Of course functions may take some parameters, as in:

function addition = |a, b| {
  return a + b
Note Parameters are constant references, hence they cannot be reassigned.

Invoking functions that take parameters is straightforward, too:

let three = addition(1, 2)
let hello_world = addition("hello ", "world!")

Variable-arity functions

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

function foo = |a, b, c...| {
  # ...

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:

# a=1, b=2, c=[]
foo(1, 2)

# a=1, b=2, c=[3]
foo(1, 2, 3)

# a=1, b=2, c=[3,4]
foo(1, 2, 3, 4)

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

function elementAt = |index, args...| {
  return args: get(index)


# prints "2"
println(elementAt(1, 1, 2, 3))

Functions from other modules and imports

Suppose that we have a module foo.Bar:

module foo.Bar

function f = {
  return "f()"

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

let r = foo.Bar.f()

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

module Somewhere.Else

import foo.Bar

function plop = {
  return f()
Note Imports in Golo do not work as in Java. Golo is a dynamic language where symbols are being resolved at runtime. Module imports are not checked at compilation time, and their sole purpose is to help in dynamic resolution. Back to the previous example, f cannot be resolved from the current module, and the Golo runtime subsequently tries to resolve f from each import statement. Also, note that the order of import statements is important, as the resolution stops at the first module having the f function.

Last but not least, you may prepend the last piece of the module name. The following invocations are equivalent:

module Somewhere.Else

import foo.Bar

function plop = {
  let result = f()
  let result_bis = Bar.f()
  let result_full = foo.Bar.f()
  return result

Golo modules have a set of implicit imports:

  • gololang.Predefined,

  • gololang.StandardAugmentations,

  • gololang,

  • java.lang.

Local functions

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

module Foo

local function a = {
  return 666

function b = {
  return a()

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:

module Bogus

function i_will_crash = {
  return Foo.a()

Module-level state

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

module Sample

let a = 1

var b = truth()

local function truth = {
  return 42

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.

Caution Global state is a bad thing in general. We strongly advise you to think twice before you introduce module-level state. Beware of potential memory leaks, just like static class fields in the Java programming language.

Java interoperability

Golo aims at providing a seamless 2-way interoperability with the Java programming language.

Main function Java compliance

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:

module mainEntryPoint

function main = |args| {
  println("-> " + args: get(0))

Once compiled, we may invoke it as follows:

$ golo compile mainEntryPoint.golo
$ java -cp ".:golo.jar" mainEntryPoint GoloRocks
-> GoloRocks

Calling static methods

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

module sample

import java.util.Arrays

function oneTwoThree = {
  return asList(1, 2, 3)

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).

Calling instance methods

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:

println(">>> " + someObject: toString())

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.

null-safe instance method invocations

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:

  • foo?: bar() simply returns null, and

  • null?: anything() returns null, too.

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:

let person = dao: findByName("Mr Bean")
let city = person?: address()?: city() orIfNull "n/a"

This is more elegant than, say:

let person = dao: findByName("Mr Bean")
var city = "n/a"
if person isnt null {
  let address = person: address()
  if address isnt null {
    city = address: city() ofIfNull "n/a"
Note The runtime implementation of null-safe method invocations is optimistic as it behaves like a try block catching a NullPointerException. Performance is good unless most invocations happen to be on null, in which case using ?: is probably not a great idea.

Creating objects

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:

module sample

import java.util

function aList = {
  return LinkedList()

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

function str_build = {
  return java.lang.StringBuilder("h"):

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

Static fields

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

module samples.MaxInt

local function max_int = {
  return java.lang.Integer.MAX_VALUE()

function main = |args| {
Note Given than most static fields are used as constants in Java, Golo does not provide support to change their values. This may change in the future if compelling general-interest use-cases emerge.

Instance fields

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

public class Foo {
  public String bar;

We can access the bar field as follows:

let foo = Foo()

# Write
foo: bar("baz")

# Read, prints "baz"
println(foo: bar())

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:

public class Foo {
  public String bar;
  public String baz;

We can set all fields by chaining invocations as in:

let foo = Foo(): bar(1): baz(2)

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

What happens if there is both a field and a method with the same names?

Back to the previous example, suppose that we have both a field and a method with the same name, as in:

public class Foo {
  public String bar;

  public String bar() {
    return bar;

Golo resolves methods first, fields last. Hence, the following Golo code will resolve the bar() method, not the bar field:

let foo = Foo()

# Write the field
foo: bar("baz")

# Calls the bar() method
println(foo: bar())

Inner classes and enumerations

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.

  1. Inner classes are identified by their real name in the JVM, with nested classes being separated by a $ sign. Hence, Thread.State in Java is written Thread$State in Golo.

  2. Enumerations are just normal objects. They expose each entry as a static field, and each entry is an instance of the enumeration class.

Let us consider the following example:

module sample.EnumsThreadState

import java.lang.Thread$State

function main = |args| {

  # Call the enum entry like a function
  let new = Thread$State.NEW()
  println("name=" + new: name() + ", ordinal=" + new: ordinal())

  # Walk through all enum entries
  foreach element in Thread$State.values() {
    println("name=" + element: name() + ", ordinal=" + element: ordinal())

Running it yields the following console output:

$ golo golo --files samples/enums-thread-state.golo
name=NEW, ordinal=0
name=NEW, ordinal=0
name=RUNNABLE, ordinal=1
name=BLOCKED, ordinal=2
name=WAITING, ordinal=3
name=TIMED_WAITING, ordinal=4
name=TERMINATED, ordinal=5

Clashes with Golo operators and escaping

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:

# Function call

# Method call
someObject: foo(): is(): not(): bar()

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:

# Function call

# Method call
someObject: foo(): `is(): `not(): bar()

Golo class loader

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


public class Foo {

  public static void main(String... args) throws Throwable {
    GoloClassLoader classLoader = new GoloClassLoader();
    Class<?> moduleClass = classLoader.load("foo.golo", new FileInputStream("/path/to/foo.golo"));
    Method bar = moduleClass.getMethod("bar", Object.class);
    bar.invoke(null, "golo golo");

This would work with a Golo module defined as in:

module foo.Bar

function bar = |wat| -> println(wat)

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

Important GoloClassLoader is rather dumb at this stage, and you will get an exception if you try to load two Golo source files with the same module name declaration. This is because it will attempt to redefine an already defined class.
Caution Later in the glorious and glamorous future, Golo will have objects and not just functions. Be patient, it’s coming in!

Control flow

Control flow in Golo is imperative and has the usual constructions found in upstream languages.

Conditional branching

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

if goloIsGreat() {
  println("Golo Golo")

if (someCondition) {
} else if someOtherCondition {
} else {

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

case branching

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

function what = |obj| {
  case {
    when obj oftype String.class {
      return "String"
    when obj oftype Integer.class {
      return "Integer"
    otherwise {
      return "alien"

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:

function what = |obj| {
  if obj oftype String.class {
    return "String"
  } else if obj oftype Integer.class {
    return "Integer"
  } else {
    return "alien"
Important when clauses are being evaluated in the declaration order, and only the first satisfied one is being executed.

match statements

The match statement 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 destructuring.

match is a great addition to the Golo programmer:

let item = ""

let what_it_could_be = -> match {
  when item: contains("@") then "an email?"
  when item: startsWith("+33") then "a French phone number?"
  when item: startsWith("http://") then "a website URL?"
  otherwise "I have no clue, mate!"

# prints "an email?"

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

While loops in Golo are straightforward:

function times = |n| {
  var times = 0
  while (times < n) { times = times + 1 }
  return times

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

for loops

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

  1. a variable declaration and initialization (a Golo variable is always initialized anyway), and

  2. a loop progress condition, and

  3. a loop progress statement.

The following function shows a for loop:

function fact = |value, n| {
  var result = 1
  for (var i = 0, i < n, i = i + 1) {
    result = result * value
  return result

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

  • the for loop elements are separated by ',' instead of ';', and

  • there cannot be multiple variables in the loop, and

  • there cannot be multiple loop progress statements.

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

foreach loops

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:

function concat_to_string = |iterable| {
  var result = ""
  foreach item in iterable {
    result = result + item
  return result

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.

Note Although Java arrays (Object[]) are not real objects, they can be used with foreach loops. Golo provides a iterator() method for them.

break and continue

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:

  • break exits the current inner-most loop, and

  • continue skips to the next iteration of the current inner-most loop.

Consider the following contrived example:

module test

function main = |args| {
  var i = 0
  while true {
    i = i + 1
    if i < 40 {
    } else {
      print(i + " ")
    if i == 50 {

It prints the following output:

40 41 42 43 44 45 46 47 48 49 50 bye

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

Why no value from most control flow constructions?

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:

println(if (4 % 2 == 0) "even" else "odd")

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.


Exception handling in Golo is simple. There is no distinction between checked and unchecked exceptions.

Raising exceptions

Golo provides 2 predefined functions for raising exceptions:

  • raise(message) throws a java.lang.RuntimeException with a message given as a string, and

  • raise(message, cause) does the same and specifies a cause which must be an instance of java.lang.Throwable.

Throwing an exception is thus as easy as:

if somethingIsWrong() {

Raising specialized exceptions

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:

module golotest.execution.Exceptions

import java.lang.RuntimeException

function runtimeException = {
  throw RuntimeException("w00t")

Exception handling

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.

# Good old try / catch
try {
} catch (e) {
  e: printStackTrace()

# A try / finally
try {
} finally {

# Full try / catch / finally construct
try {
} catch (e) {
  e: printStackTrace()
  case {
    when e oftype IOException.class {
      println("Oh, an I/O exception that I was expecting!")
    when e oftype SecurityException.class {
      println("Damn, I didn't expect a security problem...")
      throw e
    otherwise {
      throw e
} finally {
Tip Because Golo is a weakly typed dynamic language, you need to check for the exception type with the oftype operator. In a statically typed language like Java, you would instead have several catch clauses with the exception reference given a specific type. We suggest that you take advantage of the case branching statement.


Golo supports closures, which means that functions can be treated as first-class citizen.

Defining and using a closure

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

let adder = |a, b| {
  return a + b

At runtime, a closure is an instance 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:

let adder = |a, b| {
  return a + b
println(adder: invokeWithArguments(1, 2))

let addToTen = adder: bindTo(10)
println(addToTen: invokeWithArguments(2))

As one would expect, this prints 3 and 12.

Compact closures

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:

let adder = |a, b| -> a + b

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

module Foo

local function sayHello = |who| -> "Hello " + who + "!"

# Prints "Hello Julien!"
function main = |args| {

Calling closures

While you may take advantage of closures being method handles and call them using invokeWithArguments, 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:

let adder = |a, b| -> a + b
println(adder(1, 2))

let addToTen = adder: bindTo(10)


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

function plus_3 = {
  let foo = 3
  return |x| -> x + foo

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:

var a = 1
let f = {
  a = 2   # Compilation error!

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:

let list = java.util.LinkedList()
let pump_it = {
  list: add("I heard you say")
  list: add("Hey!")
  list: add("Hey!")

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

Closures to single-method interfaces

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:

let button = JButton("Click me!")
let handler = |event| -> println("Clicked!")
button: addActionListener(asInterfaceInstance(ActionListener.class, handler))

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

local function listener = |handler| -> asInterfaceInstance(ActionListener.class, handler)

# (...)
let button = JButton("Click me!")
button: addActionListener(listener(|event| -> println("Clicked!")))

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:

function give_me_hey = {
  let executor = Executors.newSingleThreadExecutor()
  let future = executor: submit(asInterfaceInstance(Callable.class, -> "hey!"))
  let result = future: get()
  executor: shutdown()
  return result

Direct closure passing works

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

# (...)
let button = JButton("Click me!")
button: addActionListener(|event| -> println("Clicked!"))

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 or the to conversion method described hereafter.

Conversion to single-method interfaces

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:

# Calling asInterfaceInstance
future = executor: submit(asInterfaceInstance(Callable.class, -> "hey!"))

# Using a class augmentation
future = executor: submit((-> "hey!"): to(Callable.class))

Getting a reference to a closure / Golo function

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

import golotest.Closures

local function local_fun = |x| -> x + 1

function call_local_fun = {

  # local_fun, with a parameter
  var f = fun("local_fun", golotest.Closures.module, 1)

  # ...or just like this if there is only 1 local_fun definition
  f = fun("local_fun", golotest.Closures.module)

  return f(1)

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

import golotest.Closures

local function local_fun = |x| -> x + 1

function call_local_fun = {

  # In the current module
  var f = ^fun

  # ...or with a full module name
  f = ^golotest.Closures::fun

  return f(1)

Binding and composing

Because closure references are just instances of java.lang.invoke.MethodHandle, you can bind its first argument using the bindTo(value) method. If you need to bind an argument at another position than 0, you may take advantage of the bindAt(position, value) augmentation:

let diff = |a, b| -> a - b
let minus10 = diff: bindAt(1, 10)

# 10

You may compose function using the andThen augmentation method:

let f = (|x| -> x + 1): andThen(|x| -> x - 10): andThen(|x| -> x * 100)

# -500


function foo = |x| -> x + 1
function bar = |x| -> 2 * x

function main = |args| {
  let newFunction = ^foo: andThen(^bar)

  # 8

Calling functions that return functions

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

let f = |x| -> |y| -> |z| -> x + y + z

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

let f1 = f(1)
let f2 = f1(2)
let f3 = f2(3)

# Prints '6'

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

# Prints '6'

This syntax only works following a function or method invocation, not on expressions. This means that:

foo: bar()("baz")

is valid, while:

(foo: bar())("baz")

is not. Let us say that "It is not a bug, it is a feature".

Predefined functions

Every Golo module definition comes with gololang.Predefined as a default import. It provides useful functions.

Console output

print and println do just what you would expect.



Console input

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.

let name = readln("what's your name? ")
let value = readln()
let pwd = readpwd("type your password:")

Number type conversions

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.

let i = intValue("666")   # 666 (string to integer)
let j = intValue(1.234)   # 1 (double to integer)
let k = intValue(666_L)   # 666 (long to integer)
# etc


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.

try {
  raise("Somehow something is wrong")
} catch (e) {
  raise("Something was wrong, and here is the cause", e)


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.

function foo = |a| {
  require(a oftype String.class, "a must be a String")

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

function foo = |a| {


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:

let data = newTypedArray(java.lang.String.class, 3)
data: set(0, "A")
data: set(1, "B")
data: set(2, "C")


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

# Prints 1 2 (...) 100
foreach i in range(1, 101) {
  print(i + " ")

# Prints a b c d
foreach c in range('a', 'e') {
  print(c + " ")

let r = range(0, 6): incrementBy(2)
println("Start: " + r: from())
println("End: " + r: to())
foreach i in r {

println("Increment: " + r: increment())

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:

# Prints nothing
foreach i in range(3, 0) {
  print(i + " ")

# Prints 3 2 1
foreach i in range(3, 0): incrementBy(-1) {
  print(i + " ")

# Prints 0 -2 -4
foreach i in range(0, -6):decrementBy(2) {
  print(i + " ")

The reversed_range function is an alias for range with an increment of -1, such that reversed_range(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, reversed_range(5) == reversed_range(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 closure reference or a method handle, one can convert it to an instance of an interface with a single method declaration, as in:

local function listener = |handler| -> asInterfaceInstance(ActionListener.class, handler)

# (...)
let button = JButton("Click me!")
button: addActionListener(listener(|event| -> println("Clicked!")))

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:

if isClosure(value) {
  map: put(key, value())
} else {
  map: put(key, value)

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

import golotest.Closures

local function local_fun = |x| -> x + 1

function call_local_fun = {
  let f = fun("local_fun", golotest.Closures.module)
  return f(1)

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

import golotest.Closures

local function local_fun = |x| -> x + 1

function call_local_fun = {
  let f = fun("local_fun", golotest.Closures.module, 1)
  return f(1)

File I/O

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

let text = fileToText("/some/file.txt", "UTF-8")

The first parameter is either a java.lang.String, a 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:

textToFile("Hello, world!", "/foo/bar.txt")

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.

if fileExists("/foo/bar.txt") {
  println("file found!")

As in the other File I/O methods, the parameter is either a java.lang.String, a 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.


Array types

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

Instead, we provide 3 helper functions.

  • isArray(object): returns a boolean if object is an array.

  • objectArrayType(): returns Object[].class.

  • arrayTypeOf(type): given type as a java.lang.Class, returns an array of type type[].


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

let e = mapEntry("foo", "bar")

# prints "foo => bar"
println(e: getKey() + " => " + e: getValue())

Class augmentations

Many dynamic languages support the ability to extend existing classes by adding new methods to them. You may think of categories in Objective-C and Groovy, or open classes in Ruby.

This is generally implemented by providing meta-classes. When some piece of code adds a method foo to, say, SomeClass, then all instances of SomeClass get that new foo method. While very convenient, such an open system may lead to well-known conflicts between the added methods.

Golo provides a more limited but explicit way to add methods to existing classes in the form of class augmentations.

Wrapping a string with a function

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:

function wrap = |left, str, right| -> left + str + right

# (...)
let str = wrap("(", "foo", ")")
println(str) # prints "(abc)"

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?

Augmenting classes

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

module foo

augment java.lang.String {
  function wrap = |this, left, right| -> left + this + right

function wrapped = -> "abc": wrap("(", ")")

More specifically:

  1. a augment definition is made on a fully-qualified class name, and

  2. an augmentation function takes the receiver object as its first argument, followed by optional arguments, and

  3. there can be as many augmentation functions as you want, and

  4. there can be as many augmentations as you want.

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:

augment java.lang.String {

  function concatWith = |this, args...| {
    var result = this
    foreach(arg in args) {
      result = result + arg
    return result

# (...)
function varargs = -> "a": concatWith("b", "c", "d")

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:

augment java.util.Collection {
  function plop = |this| -> "plop!"

# (...)
function plop_in_a_list = -> java.util.LinkedList(): plop()

Augmentation scopes, reusable augmentations

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:

module my.StringUrlAugmentations


augment java.lang.String {

  function toURL = |this| -> URL(this)

  function httpGet = |this| {
    # Open the URL, get a connection, grab the body as a string, etc
    # (...)

  # (...)

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

module my.App

import my.StringUrlAugmentations

function googPageBody = -> "": httpGet()
Tip As a matter of style, we suggest that your module names end with Augmentations. Because importing a module imports all of its augmentation definitions, we suggest that you modularize them with fine taste (for what it means).

Named augmentations

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 traits
[ Wikipedia: Traits ]
, or mixin
[ Wikipedia: Mixin ]
, as found in Rust, Groovy or Scala.

Named augmentations are defined with the augmentation keyword.

As an example:

augmentation FooBar = {
  function foo = |this| -> "foo"
  function bar = |this, a| -> this: length() + a

augmentation Spamable = {
  function spam = |this| -> "spam"

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

augment java.util.Collection with FooBar

augment MyStruct with Spamable

augment java.lang.String with FooBar, Spamable

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

module MyAugmentations

augmentation Searchable = {
  function search = |this, value| -> ...

augment java.util.Collection with Searchable

and import it, we can use the applied augmentation

import MyAugmentations

list[1, 2, 3, 4]: search(2)

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

augment java.lang.String with MyAugmentations.Searchable


import MyAugmentations

augment java.lang.String with Searchable
Note If several imported modules define augmentations with the same name, the first imported one will be used.

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

augment java.lang.String with Searchable

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.

Important As for every augmentation, no checks are made that the augmentation can be applied to the augmented class. For instance, augmenting java.lang.Number with the previous FooBar augmentation will raise java.lang.NoSuchMethodError: class java.lang.Integer::length at runtime when trying to call 1:bar(1). Calling 1:foo() will be OK however.

Augmentations Resolution Order

The augmentations resolution order is as follows:

  1. native java method (i.e. an augmentation can’t override a native java method),

  2. locally applied augmentations:

    1. simple augmentations: augment MyType { ... },

    2. named augmentations: augmentation Foo = { ... } and augment MyType with Foo in the current module. Multiple applications are searched in the application order,

    3. externally defined named augmentations with fully qualified name: augmentation Foo = { ... } in module Augmentations, and augment MyType with Augmentations.Foo in the current module,

    4. named augmentation defined in an imported module: augmentation Foo = { ... } in module Augmentations, and augment MyType with Foo in the current module that import Augmentations (imported module are searched in the importation order),

  3. augmentations applied in imported modules: using the same order than locally applied ones, in the importation order.

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).

Tip Since importing a module imports all the applied augmentations, and given the somewhat complex resolution order when involving simple and named augmentations, being local, external or imported, and involving class hierarchies, knowing which method will be applied on a given type can be difficult. A good modularisation and a careful application are recommended.

Standard augmentations

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:

let odd = [1, 2, 3, 4, 5]: filter(|n| -> (n % 2) == 0)

let m = map[]
println(m: getOrElse("foo", -> "bar"))

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


Golo allows the definition of simple structures using the struct keyword. They resemble structures in procedural languages such as C struct or Pascal records. They are useful to store data when the set of named entries is fixed.


Structures are defined at the module-level:

module sample

struct Person = { name, age, email }

function main = |args| {
  let p1 = Person("Mr Bean", 54, "")
  println(p1: name())
  let p2 = Person(): name("John"): age(32): email("")
  println(p2: age())

When declaring a structure, it also defines two factory functions: one with no arguments, 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.

JVM existence

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


module sample

struct Point = { x, y }

a class sample.types.Point is being generated.

It is important to note that:

  1. each struct class is final,

  2. each struct class inherits from gololang.GoloStruct,

  3. proper definitions of toString(), hashCode() and equals() are being provided.

toString() behavior

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

Given the following program:

module test

struct Point = { x, y }

function main = |args| {
  println(Point(1, 2))

running it prints the following console output:

struct Point{x=1, y=2}

Immutable structs

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

module test

struct Point = { x, y }

function main = |args| {

  let p = ImmutablePoint(1, 2)

  try {
    # Fails! (p is immutable)
    p: x(100)
  } catch (expected) {
    println(expected: getMessage())


Instances of a structure provide copying methods:

  • copy() returns a shallow copy of the structure instance, and

  • frozenCopy() returns a read-only shallow copy.

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

Important The result of calling copy() on a frozen instance is a mutable copy, not a frozen copy.

equals() and hashCode() semantics

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:

module test

struct Point = { x, y }

function main = |args| {

  let p1 = Point(1, 2)
  let p2 = Point(1, 2)
  let p3 = p1: frozenCopy()
  let p4 = p1: frozenCopy()

  println("p1 == p2 " + (p1 == p2))
  println("p1 == p3 " + (p1 == p3))
  println("p3 == p4 " + (p3 == p4))

  println("#p1 " + p1: hashCode())
  println("#p2 " + p2: hashCode())
  println("#p3 " + p3: hashCode())
  println("#p4 " + p4: hashCode())

the console output is the following:

p1 == p2 false
p1 == p3 false
p3 == p4 true
#p1 1555845260
#p2 104739310
#p3 994
#p4 994
Tip It is recommended that you use Immutable<name of struct>(...) or frozenCopy() when you can, especially when storing values into collections.

Helper methods

A number of helper methods are being generated:

  • members() returns a tuple of the member names,

  • values() returns a tuple with the current member values,

  • isFrozen() returns a boolean to check for frozen structure instances,

  • iterator() provides an iterator over a structure where each element is a tuple [member, value],

  • get(name) returns the value of a member by its name,

  • set(name, value) updates the value of a member by its name, and returns the same structure.

Private members

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

struct Foo = { a, _b, c }

# (...)

let foo = Foo(1, 2, 3)

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:

  • a function from the declaring module, or

  • an augmentation defined in the declaring module.

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

Private struct members also have the following impact:

  • they do not appear in members() and values() calls, and

  • they are not iterated through iterator()-provided iterators, and

  • they are being used like other members in equals() and hashCode(), and

  • they do not appear in toString() representations.

Augmenting structs

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

Augmenting structs is encouraged, as in:

module Plop

struct Point = { _id, x, y }

augment Plop.types.Point {

  function str = |this| -> "{id=" + this: _id() + ",x=" + this: x() + ",y=" + this: y() + "}"

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

module Plop

struct Point = { _id, x, y }

augment Point {

  function str = |this| -> "{id=" + this: _id() + ",x=" + this: x() + ",y=" + this: y() + "}"

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

Don’t do this at home

Of course doing the following is a bad idea, with the concise augmentation taking over the fully-qualified one:

module Foo

struct Value = { v }

augment Foo.types.Value {

  function a = |this| -> "a"

# This will discard the previous augmentation...
augment Value {

  function b = |this| -> "a"

function check = {
  let v = Value(666)

  # Ok
  v: b()

  # Fails, the concise augmentation overrides the fully-qualifed one
  v: a()

Dynamic objects

Dynamic objects can have values and methods being added and removed dynamically at runtime. You can think of it as an enhancement over using hash maps and putting closures in them.

Creating dynamic objects

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

let foo = DynamicObject()

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

  • define(name, value) allows to define an object property, which can be either a value or a closure, and

  • get(name) gives the value or closure for a property name, or null if there is none, and

  • undefine(name) removes a property from the object, and

  • mixin(dynobj) mixes in all the properties of the dynamic object dynobj, and

  • copy() gives a copy of a dynamic object, and

  • freeze() locks an object, and calling define will raise an IllegalStateException, and

  • isFrozen() checks whether a dynamic object is frozen or not, and

  • properties() gives the set of entries in the dynamic object, and

  • hasMethod(name) checks if a method is defined or not in the dynamic object, and

  • invoker(name, type) which is mostly used by the Golo runtime internals, and

  • fallback(handler) defines a fallback behavior for property invocation.

Defining values

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

let person = DynamicObject():
  define("name", "MrBean"):
  define("email", "")

# prints "Mr Bean"
println(person: name())

# prints "Mr Beanz"
person: name("Mr Beanz")
println(person: name())

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

let person = DynamicObject(): name("MrBean"): email("")

# prints "Mr Bean"
println(person: name())

# prints "Mr Beanz"
person: name("Mr Beanz")
println(person: name())

Defining methods

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:

local function mrbean = -> DynamicObject():
  name("Mr Bean"):
  define("toString", |this| -> this: name() + " <" + this: email() + ">")

function main = |args| {

  let bean = mrbean()
  println(bean: toString())

  bean: email("")
  println(bean: toString())
Warning You cannot overload methods, that is, providing methods with the same name but different signatures.

It is strongly recommended that you use define to create and update methods. Consider the following example:

let obj = DynamicObject():
  plop(|this| -> "Plop!")

Any call such as obj: plop() properly calls plop(). Because the dynamic object is fresh and new, the first call to plop creates a property since it is currently missing.

That being said, the following would fail:

obj: plop(|this| -> "Plop it up!")

Indeed, when the value of a dynamic object property is a function, it is understood to be a method, hence calling plop like it would be a setter method fails because there already exists a property that is a function, and it has a different signature. It needs to be updated as in:

obj: define('plop', |this| -> "Plop it up!")

As a rule of thumb, prefer named setters for values and define for methods. It is acceptable to have named definitions for methods if and only if a call happens after the object creation and before any call to mixin (remember that it injects properties from other objects, including methods).

Querying the properties

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

function dump = |obj| {
  foreach prop in obj: properties() {
    println(prop: getKey() + " -> " + prop: getValue())

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

Defining a fallback behavior

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.

Note Calling a setter method for a non-existent property defines it, thus the fallback is not applicable for setters.
let dynob = DynamicObject():
  fallback(|this, method, args...| {
    return "Dispatch failed for method: " + method + ", with args: " + args: asList(): join(" ")

println(dynob: casperGetter())
println(dynob: casperMethod("foo", "bar"))
Dispatch failed for method: casperGetter, with args:
Dispatch failed for method: casperMethod, with args: foo bar


There is already much you can do while in Golo land using functions, closures, structs, augmentations and dynamic objects.

Yet, the JVM is a wider ecosystem and you will soon be tempted to integrate existing Java libraries into your code. Calling Java libraries from Golo is quite easy, but what happens when you need to subclass classes or provide objects that implement specific interfaces?

As you can easily guess, this is all what adapters are about: they allow the definition of objects at runtime that can extend and inherit Java types.

A simple example

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

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

module sparky

import spark
import spark.Spark

function main = |args| {
  let conf = map[   # 1
    ["extends", "spark.Route"],   # 2
    ["implements", map[   # 3
      ["handle", |this, request, response| {  # 4
        return "Golo, world!"
  let fabric = AdapterFabric()  # 5
  let routeMaker = fabric: maker(conf)  # 6
  let route = routeMaker: newInstance("/hello")   # 7
  get(route)  # 8
1 An adapter configuration is provided by a map object.
2 The extends key allows specifying the name of the parent class (java.lang.Object by default).
3 The implements provides a map of method implementations.
4 The implementation is given by a closure whose signature matches the parent class definition, and where the first argument is the receiver object that is going to be the adapter instance.
5 An adapter fabric provides context for creating adapters. It manages its own class loader.
6 An adapter maker creates instances based on a configuration.
7 The newInstance() method calls the right constructor based on the parent class constructors and provided argument types.
8 The spark.Spark.get() static is method is happy as we feed it a subclass of spark.Route.
Note Adapter objects implement the gololang.GoloAdapter marker interface, so you can do type checks on them a in: (foo oftype gololang.GoloAdapter.class).

Implementing interfaces

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

let result = array[1, 2, 3]
let conf = map[
  ["interfaces", ["", "java.lang.Runnable"]],
  ["implements", map[
    ["run", |this| {
      for (var i = 0, i < result: length(), i = i + 1) {
        result: set(i, result: get(i) + 10)
let runner = AdapterFabric(): maker(conf): newInstance()
runner: run() # 1
1 As you may guess, this changes the result array values to [11, 12, 13].


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:

let conf = map[
  ["overrides", map[
    ["toString", |super, this| -> ">>> " + super(this)]
println(AdapterFabric(): maker(conf): newInstance(): toString()) # 1
1 This prints something like: >>> $Golo$Adapter$0@12fc7ceb.
Note You can mix both implementations and overrides in an adapter configuration.

Star implementations and overrides

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:

let carbonCopy = list[] # 1
let conf = map[
  ["extends", "java.util.ArrayList"],
  ["overrides", map[
    ["*", |super, name, args| { # 2
      if name == "add" {
        if args: length() == 2 {
          carbonCopy: add(args: get(1))  # 3
        } else {
          carbonCopy: add(args: get(1), args: get(2)) # 4
      return super: spread(args)  # 5
let list = AdapterFabric(): maker(conf): newInstance()
list: add("bar")
list: add(0, "foo")
list: add("baz")  # 6
1 We create an empty list, more on that later.
2 A star override takes 3 parameters: the parent class implementation, the method name and the arguments into an array (the element at index 0 is the receiver).
3 We copy into carbonCopy.
4 Same here, but we dispatch to a different method
5 We just call the parent class implementation of whatever method it is. Note that spread allows to dispatch a closure call with an array of arguments.
6 At this point carbonCopy contains ["foo", "bar", "baz"] (and so does list, too).

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.


Golo feature Python-like decorators.


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.

Note Higher order functions (HOF) are functions that process functions, i.e. that take a function as parameter, and may return a new function.

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
[ Wikipedia: 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 java.lang.invoke.MethodHandle).

Principles and syntax

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

function deco1 = |fun| {
  return |args...| {
    return "deco1 + " + fun: invokeWithArguments(args)

It can be used as:

function foo = |a| {
  return "foo: " + a

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 invokeWithArguments, 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:

function add = |a,b| -> a + b

Such a decorator can be implemented as:

function dec = |func| -> |a, b| -> func(a, b)

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

function dec = |func| -> |args...| -> func(args)

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:

function dec = |func| -> |args...| -> func(args: get(0), args: get(1))

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

function dec = |func| -> |args...| -> func: invokeWithArguments(args)

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:

function bar = |a| -> "bar: " + a

function main = |args| {

  let decobar = deco1(^bar)

  println(deco1(|a| -> "bar: "+a)(1))

prints all deco1 + bar: 1.

Decorators can also be stacked. For instance:

function deco2 = |fun| {
  return |args...| {
    return "deco2 + " + fun: invokeWithArguments(args)

function baz = |a| -> "baz: " + a

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

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

let deco3 = ^deco1: andThen(^deco2)

function spam = |a| -> "spam: " + a

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:

module tests.LogDeco

function log = |msg| -> |fun| -> |args...| {
  return fun: invokeWithArguments(args)

@log("calling foo")
function foo = |a| {
  println("foo got a " + a)

@log("I'am a bar")
function bar = |a| -> 2*a

function main = |args| {

will print

calling foo
foo got a bar
I'am a bar

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:

let sayHello = log("Hello")

function baz = -> "Goodbye"

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:

function log = |msgBefore| -> |msgAfter| -> |func| -> |args...| {
  let res = func: invokeWithArguments(args)
  return res

@log("enter foo")("exit foo")
function foo = |a| {
  println("foo: " + a)

where a call foo("bar") will print

enter foo
foo: bar
exit foo

and with

function logEnterExit = |name| -> log("# enter " + name)("# exit " + name)

function bar = { println("doing something...") }

calling bar() will print

# enter bar
doing something...
# exit bar

or even, without decorator syntax:

function main = |args| {
  let strange_use = log("hello")("goodbye")({println(":p")})


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

Use cases and examples

Use cases are at least the same as aspect oriented programming
[ Wikipedia: Aspect Oriented Programming ]
(AOP) and the decorator design pattern
[ Wikipedia: Decorator Design Pattern ]
, but your imagination is your limit. Some are presented here for illustration.


Logging is a classical example use case of AOP. See the Principles and syntax section for an example.

Pre/post conditions checking

Decorators can be used to check pre-conditions, that is conditions that must hold for arguments, and post-conditions, that is conditions that must hold for returned values, of a function.

Indeed, a decorated can execute code before delegating to the decorated function, of after the delegation.

The module gololang.Decorators provide two decorators and several utility functions to check pre and post conditions.

checkResult is a parametrized decorator taking a checker as parameter. It checks that the result of the decorated function is valid.

checkArguments is a variable arity function, taking as much checkers as the decorated function arguments. It checks that the arguments of the decorated function are valid according to the corresponding checker (1st argument checked by 1st checker, and so on).

A checker is a function that raises an exception if its argument is not valid (e.g. using require) or returns it unchanged, allowing checkers to be chained using the andThen method.

As an example, one can check that the arguments and result of a function are integers with:

let isInteger = |v| {
  require(v oftype Integer.class, v + "is not an Integer")
  return v

@checkArguments(isInteger, isInteger)
function add = |a, b| -> a + b

or that the argument is a positive integer:

let isPositive = |v| {
  require(v > 0, v + "is not > 0")
  return v

@checkArguments(isInteger: andThen(isPositive))
function inv = |v| -> 1.0 / v

Of course, again, you can take shortcuts:

let isPositiveInt = isInteger: andThen(isPositive)

function double = |v| -> 2 * v

or even

let myCheck = checkArguments(isInteger: andThen(isPositive))

function inv = |v| -> 1.0 / v

function mul = |v| -> 10 * v

Several factory functions are available in gololang.Decorators to ease the creation of checkers:

  • any is a void checker that does nothing. It can used when you need to check only some arguments of a n-ary function.

  • asChecker is a factory that takes a boolean function and an error message and returns the corresponding checker. For instance:

let isPositive = asChecker(|v| -> v > 0, "is not positive")
  • isOfType is a factory function that returns a function checking types, e.g.

let isInteger = isOfType(Integer.class)

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


As seen, decorator can be used to wrap a function call between checking operation, but also between a lock/unlock in a concurrent context:

import java.util.concurrent.locks

function withLock = |lock| -> |fun| -> |args...| {
  lock: lock()
  try {
    return fun: invokeWithArguments(args)
  } finally {
    lock: unlock()

let myLock = ReentrantLock()

function foo = |a, b| {
  return a + b


Memoization is the optimization technique that stores the results of a expensive computation to return them directly on subsequent calls. It is quite easy, using decorators, to transform a function into a memoized one. The decorator creates a closure on a hashmap, and check the existence of the results before delegating to the decorated function, and storing the result in the hashmap if needed.

Such a decorator is provided in the gololang.Decorators module, presented here as an example:

function memoizer = {
  var cache = map[]
  return |fun| {
    return |args...| {
      let key = [fun: hashCode(), Tuple(args)]
      if (not cache: containsKey(key)) {
        cache: add(key, fun: invokeWithArguments(args))
      return cache: get(key)

The cache key is the decorated function and its call arguments, thus the decorator can be used for every module functions. It must however be put in a module-level state, since in the current implementation, the decoration is invoked at each call. For instance:

let memo = memoizer()

function fib = |n| {
  if n <= 1 {
    return n
  } else {
    return fib(n - 1) + fib(n - 2)

function fact = |n| {
  if n == 0 {
    return 1
  } else {
    return n * fact(n - 1)

Generic context

Decorators can be used to define a generic wrapper around a function, that extends the previous example (and can be used to implement most of them). This functionality is provided by the gololang.Decorators.withContext standard decorator. This decorator take a context, such as the one returned by gololang.Decorators.defaultContext function.

A context is an object with 4 defined methods:

  • entry, that takes and returns the function arguments. This method can be used to check arguments or apply transformation to them;

  • exit, that takes and returns the result of the function. This method can be used to check conditions or transform the result;

  • catcher, that deal with exceptions that occurs during function execution. It takes the exception as parameter;

  • finallizer, that is called in a finally clause after function execution.

The context returned by gololang.Decorators.defaultContext is a void one, that is entry and exit return their parameters unchanged, catcher rethrow the exception and finallizer does nothing.

The workflow of this decorator is as follow:

  1. the context entry method is called on the function arguments;

  2. the decorated function is called with arguments returned by entry;

    1. if an exception is raised, catcher is called with it as parameter;

    2. else the result is passed to exit and the returned value is returned

  3. the finallizer method is called.

Any of theses methods can modify the context internal state.

Here is an usage example:

module samples.ContextDecorator

import gololang.Decorators

let myContext = defaultContext():
  define("entry", |this, args| {
    this: count(this: count() + 1)
    println("hello:" + this: count())
    return args
  define("exit", |this, result| {
    require(result >= 3, "wrong value")
    return result
  define("catcher", |this, e| {
    println("Caught " + e)
    throw e
  define("finallizer", |this| {println("do some cleanup")})

function foo = |a, b| {
  println("Hard computation")
  return a + b

function main = |args| {
  println(withContext(myContext)(|a| -> 2*a)(3))
  try {
    println(foo(1, 1))
  } catch (e) { }

which prints

Hard computation
do some cleanup
do some cleanup
Hard computation
Caught java.lang.AssertionError: wrong value
do some cleanup

Since the context is here shared between decorations, the count attribute is incremented by each call to every decorated function, thus the output.

This generic decorator can be used to easily implement condition checking, logging, locking, and so on. It can be more interesting if you want to provide several functionalities, instead of stacking more specific decorators, since stacking, or decorator composition, adds indirection levels and deepen the call stack.

Banged function call

Golo uses invokedynamic
[ Oracle Java Magazine 2013-01-02 ]

[ Oracle Java Magazine 2013-05-06 ]
to dynamically link at runtime an invocation instruction to the target code that will be effectively executed.

An invocation is done in three steps:

  • first, a computation is executed to find the target code,

  • then, the call site of the invocation is plugged to this target,

  • finally the target code is executed as if it had been linked at load time.

The first two phases are mostly executed once for a call site, according there’s no need to re-link the call site to his target code.

A function call marked with bang (!) is directly linked to the result returned by the target execution.

A banged invocation is executed like this:

  • first, a computation is executed to find the target code,

  • then the target code is executed,

  • finally, the call site of the invocation is plugged to a constant MethodHandle
    [ Constant MethodHandle ]
    which returns the target computation result as a constant value.

Principles and syntax

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:

module sample

function take_a_while  = {
  # ... complex computation
  return 42

function main = |args| {

  foreach i in range(0, 100) {


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.

Note The ! notation can only be used on regular function calls. Indeed, since methods are context dependant (the object itself), it is not allowed to “bang” them. As a consequence, a function invocation using the invoke or invokeWithArguments method of the MethodHandle object can’t use this feature.

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

module sample

function hello = |name| {
  return "Hello " + name + "!"

function main = |args| {
  foreach name in ["Peter", "John", "James"] {
    println( hello!(name) # will always print 'Hello Peter!'

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.

Warning Functions having side effects should not be marked, since the computation is not done for subsequent calls, and thus the side effect can’t happen. In the same way, function that depends on an outside context are risky. Indeed, a change in the context won’t imply a change in the result any more. In other words, only pure functions should be marked with a !. No check is done by the language, use it at your own risk.

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

module sample

function hello = |name| {
  return "Hello " + name + "!"

function main = |args| {
  println( hello!("Foo") ) # will print 'Hello Foo!'
  println( hello!("Bar") ) # will print 'Hello Bar!'
  foreach name in ["Peter", "John", "James"] {
   println( hello!(name) # will always print 'Hello Peter!'
  foreach name in ["Peter", "John", "James"] {
   println( hello(name) # will print 'Hello Peter!', 'Hello John!', 'Hello James!'

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:

module sample

function closure = |x| {
  return |y| {
    return x * y

function singleton = -> java.lang.Object!()

function main = |args| {

  foreach i in range(0, 100) {
    println( closure(i)!(i) ) # will always print 0

    singleton(): hashCode() == singleton(): hashCode(),
    "Houston, ..."

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

  • closure(i) returns a closure (|y| -> x * y) with x as enclosed variable

  • closure(i) is computed for each value of i

  • the closure returned by closure(i) is called at the first iteration with 0 for x and y

  • for every subsequent call closure(i) is still computed but ignored because the anonymous call is replaced by the return of a constant value

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.

Banged decorators

As explained in the decorators part the following identity function:

function decorator =  |func| -> |x| -> func(x)

function identity = |x| -> x

is expanded to:

function decorator =  |func| -> |x| -> func(x)

function identity = |x| -> decorator(|x| -> x)(x)

A banged decorator declared with the @! syntax:

function decorator =  |func| -> |x| -> func(x)

function identity = |x| -> x

is expanded to:

function decorator =  |func| -> |x| -> func(x)

function identity = |x| -> decorator!(|x| -> x)(x)

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:

function decorator =  |arg| -> |func| -> |x| -> func(x)

function identity = |x| -> x

is expanded to:

function decorator =  |arg| -> |func| -> |x| -> func(x)

function identity = |x| -> decorator(42)!(|x| -> x)(x)
Note Considering the return of a banged call is constant, a common pitfall is to think that differents calls share the same "context" regardless where the call is located into the code.

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

function foo = |a| -> a

function bar = |b| -> b

These functions are expanded to

function foo = |a| -> deco("a")!(|a| -> a)(a)

function bar = |b| -> deco("b")!(|b| -> b)(b)

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:

function foo = |a| -> func_a(a)

function bar = |b| -> func_b(b)

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.

Dynamic code evaluation

Golo provides facilities for dynamically evaluating code from strings in the form of the gololang.EvaluationEnvironment class. It provides an API that is useful both when used from Golo code, or when used from a polyglot JVM application that embeds Golo.

Loading a module

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

let env = gololang.EvaluationEnvironment()
let code =
module foo

function a = -> "a!"
function b = -> "b!"
let mod = env: asModule(code)
let a = fun("a", mod)
let b = fun("b", mod)

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.

Anonymous modules

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

let env = gololang.EvaluationEnvironment()
let code =
function a = -> "a!"
function b = -> "b!"
let mod = env: anonymousModule(code)
let a = fun("a", mod)
let b = fun("b", mod)

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:

let env = gololang.EvaluationEnvironment()
let code = "return (a + b) * 2"
let f = env: asFunction(code, "a", "b")
println(f(10, 20))

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:

  imports("java.util.LinkedList", "java.util.HashMap"):
  asFunction("""let l = LinkedList()
let m = HashMap()""")

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

let env = gololang.EvaluationEnvironment()
let code = "|a, b| -> (a + b) * 2"
let f = env: def(code)
println(f(10, 20))

Running code

The first form of run method works as follows:

let env = gololang.EvaluationEnvironment()
let code = """println(">>> run")
foreach i in range(0, 3) {
return 666"""
println(env: run(code)) # => "w00t"x3 and "666"

The second form allows passing parameter values in a map:

let env = gololang.EvaluationEnvironment()
let code = """println(">>> run_map")
let values = java.util.TreeMap(): add("a", 1): add("b", 2)
env: run(code, values)

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.

Concurrency with workers

Concurrency is hard. Fortunately for us the java.util.concurrent packages bring useful abstractions, data types and execution mechanisms to get concurrency "a little bit better".

Golo doesn’t provide a equivalent to the synchronized keyword of Java. This is on-purpose: when facing concurrency, we advise you to just use whatever is in java.util.concurrent.

That being said we provide a simple abstraction for concurrent executions in the form of workers. They pretty much resemble JavaScript web workers or isolates in Dart, albeit they do not really isolate the workers data space.

The big picture

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

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:

  • withCachedThreadPool() uses a cached thread pool,

  • withFixedThreadPool(size) uses a fixed number of threads in a pool,

  • withFixedThreadPool() uses a pool with 1 thread per processor core,

  • withSingleThreadExecutor() uses a single executor thread.

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.

Spawning a worker and passing messages

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:

let env = WorkerEnvironment.builder(): withFixedThreadPool()
let port = env: spawn(|message| -> println(">>> " + message))

A port provides a send(message) method:

port: send("hello"): send("world")

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

A complete and useless example

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

module SampleWithWorkers

import java.lang.Thread
import java.util.concurrent
import gololang.concurrent.workers.WorkerEnvironment

local function pusher = |queue, message| -> queue: offer(message) # 3

local function generator = |port, message| { # 1
  foreach i in range(0, 100) {
    port: send(message)                      # 2

function main = |args| {

  let env = WorkerEnvironment.builder(): withFixedThreadPool()
  let queue = ConcurrentLinkedQueue()

  let pusherPort = env: spawn(^pusher: bindTo(queue))
  let generatorPort = env: spawn(^generator: bindTo(pusherPort))

  let finishPort = env: spawn(|any| -> env: shutdown()) # 5

  foreach i in range(0, 10) {
    generatorPort: send("[" + i + "]")
  finishPort: send("Die!") # 4

  env: awaitTermination(2000)
  println(queue: reduce("", |acc, next| -> acc + " " + next))

In this example, we spawn 3 workers:

1 the first repeats a message 100 times,
2 …forwarding them to another one,
3 …that ultimately pushes them to a concurrent queue.
4 A message is sent to a final worker,
5 …that shuts the workers environment down.

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:

  • ^pusher: bindTo(queue), and

  • ^generator: bindTo(pusherPort), and

  • env: spawn(|any| -> env: shutdown()) where the worker function is defined as a closure, and implicitly captures its env dependency from the surrounding context.

Golo template engine

Golo comes with a built-in template engine that is reminiscent of Java Server Pages or Ruby ERB. It compiles template text into Golo functions.


Consider the following example.

let template = """
<%@params posts %>
<!DOCTYPE html>
    <title>Golo Chat</title>
  <form action="/" method="post">
    <input type="text" name="msg">
    <input type="submit" value="Send">
    <h3>Last posts</h3>
    <% foreach post in posts { %>
        <%= post %>
    <% } %>

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

let tpl = gololang.TemplateEngine(): compile(template)
println(tpl(someDataModel: posts()))


As you may have guess from the previous example:

  • Golo code snippets are placed in <% %> blocks, and

  • expressions can output values using <%= %>, and

  • <%@import %> causes to be imported, and

  • <%@params foo, bar, baz %> causes the template function to have 3 parameters, i.e., it is a |foo, bar, baz| { ... } function.

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

Warning The template engine is a simple one and makes no verification either on the templates or the resulting Golo source code. The compile method may throw a GoloCompilation exception though, and you can query the exception getSourceCode() and getProblems() methods to obtain more details.

Documenting Golo code

Of course you can document your code using comments (#), but who reads source code?

Documentation blocks

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

Here is a quick example:

This is a *nice* module that does a bunch of useless things.

See more at [our website](
module Hello

Adds 2 elements, which is quite surprising given the name.

* `x` is the first argument,
* `y` is the second argument.

The following snipped prints `3`:

    let result = adder(1, 2)

function adder = |x, y| -> x + y

Rendering documentation

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

$ golo doc --output target/documentation src/**/*.golo

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 help 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:

The most useful augmentation *ever*.
augment java.lang.String {

  Creates a URL from a string, as in: `let url = "": toURL()`.
  function toURL = |this| ->

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

Misc. modules

Not everything fits into the main documentation. We encourage you to also look at the javadocs and golodocs.

The next subsections provide summaries of misc. modules found as part of Golo.

Standard augmentations (gololang.StandardAugmentations)

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:

println(list[1, 2, 3, 4]: filter(|n| -> (n % 2) == 0))
println(list[1, 2, 3]: map(|n| -> n * 10))

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

map: putIfAbsent(key, -> expensiveOperation())
map: getOrElse(key, "n/a")

Repeat an operation many times:

3: times(-> println("Hey!")
3: times(|i| -> println(i))

Function references are method handles, and there are augmentations for them:

# Composition
let f = |x| -> x + 1
let g = |y| -> y * 10
let h = f: andThen(g)

# Partial application
let adder = |x, y| -> x + y
let add2 = adder: bindAt(1, 2)    # binds 'y'

JSON support (gololang.JSON)

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:

let data = map[
  ["name", "Somebody"],
  ["age", 69],
  ["friends", list[
    "Mr Bean", "John B", "Larry"
let asText = JSON.stringify(data)

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

let data = JSON.parse(text)
println(data: get("name"))

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

Scala-like dynamic variable (gololang.DynamicVariable)

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:

let dyn = DynamicVariable("Foo")
println(dyn: value())

let t1 = Thread({
  dyn: withValue(666, {
    println(dyn: value())

let t2 = Thread({
  dyn: withValue(69, {
    println(dyn: value())

t1: start()
t2: start()
t1: join()
t2: join()
println(dyn: value())

one gets an output similar to:


with the 69 and 666 swapping order over runs.

Observable references (gololang.Observable)

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:

let foo = Observable("Foo")
foo: onChange(|v| -> println("foo = " + v))

let mapped = foo: map(|v| -> v + "!")
mapped: onChange(|v| -> println("mapped = " + v))

foo: set("69")

This yields the following output:

foo = 69
mapped = 69!

Asynchronous programming helpers (gololang.Async)

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:

module samples.Concurrency

import java.util.concurrent
import gololang.Async

local function fib = |n| {
  if n <= 1 {
    return n
  } else {
    return fib(n - 1) + fib(n - 2)

function main = |args| {
  let executor = Executors.newFixedThreadPool(2)
  let results = [30, 34, 35, 38, 39, 40, 41, 42]:
    map(|n| -> executor: enqueue(-> fib(n)):
      map(|res| -> [n, res]))
  reduce(results, "", |acc, next| -> acc + next: get(0) + " -> " + next: get(1) + "\n"):
    onSet(|s| -> println("Results:\n" + s)):
    onFail(|e| -> e: printStackTrace())
  executor: shutdown()
  executor: awaitTermination(120_L, TimeUnit.SECONDS())

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

Common pitfalls

Discovering a new programming language is fun. Yet, we all make mistakes in the beginning, as we idiomatically repeat habits from other languages.

Because Golo works closely with the Java programming language, it is likely that Java programmers will make some of the following mistakes early on.


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

# Good
let foo = java.util.LinkedList()

# Compilation fails
let foo = new java.util.LinkedList()


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.

import java.util
import java.util.concurrent.AtomicInteger

# (...)

# Direct resolution at runtime
let foo = java.util.LinkedList()

# Resolution with the 1st import
let foo = LinkedList()

# Resolution with the 2nd import
let foo = AtomicInteger(666)

Method invocations

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

This is a common mistake!

# Calls toString() on foo
foo: toString()

# Looks for a function toString() in module foo

match is not a closure

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

let foo = match {
  case plop then 1
  case ploped then 2
  otherwise -1

# Ok

# Bad! foo is an integer!