The Golo Programming Language

Editor and IDE support for Golo is available for:

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

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

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

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

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

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

The complete commands usage instructions can be listed by running golo --help.

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

golo golo takes several Golo source files as input. It expects the last one to have a main function to call. The Golo code is compiled on the fly and executed straight into a JVM.

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

We may invoke it as follows:

Note that args is expected to be an array.

Finally, the --classpath flag allows to specify a list of classpath elements, which can be either directories or .jar files. See the golo help command for details on the various Golo commands.

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:

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

Golo provides a golo command for running compiled Golo code:

Simple, isn’t it?

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

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

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

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

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

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

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

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

Here are a few examples:

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

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

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

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

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

The syntax and type matchings are the following:

Golo supports the following set of operators.

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

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

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

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

Given a reference a on some array:

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

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

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

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

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

You can now run the module Foo with:

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

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

You can now run the module Foo with:

Golo modules can define functions as follows:

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

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

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

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

Of course functions may take some parameters, as in:

Invoking functions that take parameters is straightforward, too:

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

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

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

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

then:

Suppose that we have a module foo.Bar:

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

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

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

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

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

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

Suppose that we have the following Golo module:

Once compiled, we may invoke it as follows:

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

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

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

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

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

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

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

By contrast:

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

This is more elegant than, say:

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

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

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

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

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

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

We can access the bar field as follows:

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

Suppose that we have a Java class as follows:

We can set all fields by chaining invocations as in:

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

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

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

Let us consider the following example:

Running it yields the following console output:

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

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

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

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

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

This would work with a Golo module defined as in:

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

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

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

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

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

The match 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:

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

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

While loops in Golo are straightforward:

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

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

The following function shows a for loop:

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

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

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

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

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

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

Like in Java and many other languages:

Consider the following contrived example:

It prints the following output:

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

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

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

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

Golo provides 2 predefined functions for raising exceptions:

Throwing an exception is thus as easy as:

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

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

The following snippets show each exception handling form.

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

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

As one would expect, this prints 3 and 12.

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

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

While you may 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:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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:

You may compose function using the andThen augmentation method:

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

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

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

print and println do just what you would expect.

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

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

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

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

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

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

Golo provides functions to deal with Java arrays (Object[]).

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

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

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:

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

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

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

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

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

We can write some text to a file, too:

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

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

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

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

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

Instead, we provide 3 helper functions.

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

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

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

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

More specifically:

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

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

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

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

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

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

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

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

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

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

Here is an example:

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

Structures are defined at the module-level:

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

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

Given:

a class sample.types.Point is being generated.

It is important to note that:

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

Given the following program:

running it prints the following console output:

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

Instances of a structure provide copying methods:

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

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

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

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

Consider the following program:

the console output is the following:

A number of helper methods are being generated:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Let us see a concrete example:

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

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

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

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

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

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

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

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

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

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

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

The first form of run method works as follows:

The second form allows passing parameter values in a map:

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

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

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

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

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

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

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

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

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

A port provides a send(message) method:

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

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

In this example, we spawn 3 workers:

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

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

Consider the following example.

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

As you may have guess from the previous example:

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

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

Here is a quick example:

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

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:

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

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

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

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

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

This is a common mistake!

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