Documentation for gololang.ir.DSL

This module provides some factory functions and augmentations on IR elements to improve fluent IR building.

See the gololang.ir java package javadoc for documentation on the IR elements themselves. See the gololang.ir.Quote module for an alternative way to create IR nodes.

Adds more fluent methods to build a block container.

Defines the block as the given statements

See body

Adds more fluent methods to build a case statement.

See CaseStatement and associated factory

Define the action for a when clause.

• param statements: the statements representing the actions in the block. A Block is created if needed.

See then

Adds more fluent methods to build a conditional branching IR

See ConditionalBranching and the associated factory

Returns the false block or the nested branch.

Defines the false block or nested conditional

• param statements: the statements to execute when the condition is false. A Block is created if needed.

See otherwise

Returns the true block.

Defines the true block.

• param statements: the statements to execute when the condition is true. A Block is created if needed.

See whenTrue

Allows to use operator factories as methods on expressions, to look more like infix operator.

For instance, plus(constant(38), constant(4)) can be written constant(38): plus(constant(4))

See ExpressionStatement

See and

See divide

See equals

See is

See isnt

See lessOrEquals

See lessThan

See moreOrEquals

See moreThan

See notEquals

See oftype

See or

See orIfNull

See plus

See times

Utility augmentation on all IR elements.

Prints a representation of this node subtree to the terminal.

Adds all the given elements to the module.

• returns the module itself

See TryCatchFinally and the corresponding factory

Defines the exception name and the statements in the catch block.

• param exceptionName: the name of the variable holding the exception.
• param statements: the statements in the catch block.

Defines the finally block.

• param statements: the statements in the finally block.

Creates a logical conjunction operation and.

• param left: the left expression.
• param right: the right expression.
• returns a BinaryOperation

See also the ExpressionStatement augmentation

Creates an array literal.

array(
  constant(42),
  constant(1337),
  call("f"): withArgs(constant("foo"))
)

creates

array[42, 1337, f("foo")]

• param values: the expressions representing the values in the array
• returns a CollectionLiteral node

Creates an array comprehension.

For instance:

arrayComprehension(
  plus(refLookup("i"), 1),
  `for(`var("i", 0),
       lessThan(refLookup("i"), 10),
       assign(plus(refLookup("i"), 1))
  )
)

creates

array[i + 1 for(var i = 0, i < 10, i = i + 1)]

• param expression: the comprehension expression.
• param loops: the loops of the comprehension.
• returns a CollectionComprehension node

Create a assignment statement.

For instance:

answer = 42

can be created with

assign(42): to("foo")

• param value: the value to assign to the variable.
• returns an AssignmentStatement or a DestructuringAssignment

Creates an assignment statement.

For instance:

assign("foo", 42)

creates

foo = 42

• param name: the name of the variable to define, or a tuple for destructuring
• param val: the value to assign to the variable.
• returns an AssignmentStatement or a DestructuringAssignment

Creates an augmentation on the target name.

Typical usage:

`augment(String.class): with(
  `function("foo"): withParameters("this")
    : returns(42))

creates

augment java.lang.String {
   function foo = |this| -> 42
}

• param target the name of the target (compatible with PackageAndClass.of)
• return a classical augmentation (Augmentation)

Creates a named augmentation.

Typical usage:

`augmentation("Fooable"): add(
  `function("foo"): withParameters("this")
    : returns(42))

creates

augmentation Fooable = {
   function foo = |this| -> 42
}

• param name: the name of the augmentation (compatible with PackageAndClass.of)
• return a named augmentation

Creates a block containing the given statements.

If only one statement is given and it is a block, it is returned unchanged.

• param statements: the statements to build the block from.
• returns a Block

Creates a break statement.

Call a function.

Delegates on FunctionInvocation.of.

• returns a FunctionInvocation

Creates a case statement.

For instance

`case()
  : `when(equals(refLookup("x"), 0)): do(
    call("println"): withArgs(constant("null"))
  )
  : `otherwise(
    call("println").withArgs(constant("not null"))
  )

creates

case {
  when x == 0 {
    println("null")
  }
  otherwise {
    println("not null")
  }
}

See CaseStatement and associated augmentation

Void statement containing a message.

Same as noop, but the message can be used by diagnose or debug tools.

Creates a constant expression.

Constant expressions in the IR are numbers, strings or boolean values (namely literals).

• param value: the runtime value of this constant expression.
• returns a ConstantStatement

Creates a continue statement.

Create a function decorator from the given expression.

• param expr the expression representing the decorator or any element that can be converted into a valid ExpressionStatement
• returns a Decorator

See Decorator.of

Create a declaring assignment statement.

For instance:

let answer = 42

can be created with

define("answer"): as(42)

• param name: the name of the variable to define, or a tuple for destructuring
• returns an AssignmentStatement or a DestructuringAssignment

Create a destructuring assignment statement.

For instance:

a, b = foo()

can be created with

destruct(call("foo")): to("a", "b")

• param value: the value to assign to the variable.
• returns an AssignmentStatement or a DestructuringAssignment

Creates a division binary operation /.

• param left: the left expression.
• param right: the right expression.
• returns a BinaryOperation

See also the ExpressionStatement augmentation

Creates a equality binary operation ==.

• param left: the left expression.
• param right: the right expression.
• returns a BinaryOperation

See also the ExpressionStatement augmentation

Creates a for loop IR node.

For instance

`for(`var("x", 0),
     lessThan(refLookup("x"), 10),
     assign(plus(refLookup("x"), 1)): to("x")): do(
  call("println"): withArgs(refLookup("x"))
)

creates

for (var x = 0, x < 10, x = x + 1) {
  println(x)
}

• param init: the node representing the loop variable initialization.
• param cond: the node representing the loop halting condition.
• param post: the node representing the loop variable increment.
• returns a LoopStatement

See LoopStatement and the BlockContainer augmentation

Creates a foreach loop IR node.

Typical usage:

`foreach("x"): in(call("range"): withArgs(5)): do(
  call("println").withArgs(refLookup("x"))
)

creates

foreach x in range(5) {
  println(x)
}

• param vars: the loop variables destructured from the iterable elements
• returns a ForEachLoopStatement

See ForEachLoopStatement and the BlockContainer augmentation

Creates a function declaration

• param name: the name of the function
• returns a GoloFunction

See GoloFunction.function and lambda

Creates a reference to the named function.

For instance:

functionRef("foo")

creates

^foo

• param func the function description. Can be a String for the function name, a GoloFunction or a java.lang.reflect.Method.
• returns a constant statement containing the function reference.

Creates a reference to the named function and module.

• param mod a String giving the module name, the GoloModule itself, or the java.lang.Class of the module.
• param func the name of the function to reference.
• returns a constant statement containing the function reference.

Creates a reference to the named function and module with the given arity.

For instance:

functionRef(java.util.Objects.class, "equals", 2)

creates

^java.util.Objects::equals\2

• param mod a String giving the module name, the GoloModule itself, or the java.lang.Class of the module.
• param func the name of the function to reference.
• param arity the arity of the referenced function.
• returns a constant statement containing the function reference.

Creates a reference to the named function and module with the given (variable) arity.

For instance:

functionRef("java.util.Arrays", "asList", 1, true)

creates

^java.util.Arrays::asList\1...

• param mod a String giving the module name, the GoloModule itself, or the java.lang.Class of the module.
• param func the name of the function to reference.
• param arity the arity of the referenced function.
• param varargs whether the function is varargs or not.
• returns a constant statement containing the function reference.

Creates a conditional branching IR node.

For instance

if a != 0 {
  println(a)
} else {
  println("zero")
}

can be created by

`if(notEquals(refLookup("a"), 0)): `then(
  call("println"): withArgs(refLookup("a"))
): `else(
  call("println"): withArgs("zero")
)

• param cond: the condition node.
• returns a ConditionalBranching

See ConditionalBranching and the associated augmentation

Creates an IR import node.

• param mod: the module to import.

See ModuleImport.of

Invoke a method.

Delegates on MethodInvocation.invoke.

• returns a MethodInvocation

Creates an identity equality binary operation is.

• param left: the left expression.
• param right: the right expression.
• returns a BinaryOperation

See also the ExpressionStatement augmentation

Creates an identity difference binary operation isnt.

• param left: the left expression.
• param right: the right expression.
• returns a BinaryOperation

See also the ExpressionStatement augmentation

Creates an anonymous function.

Typical usage:

lambda("a", "b"): returns(plus(refLookup("a"), refLookup("b")))

creates

|a, b| -> a + b

• param parameters: the parameters names
• return the reference to the anonymous function

Creates a lesser comparison binary operation <=.

• param left: the left expression.
• param right: the right expression.
• returns a BinaryOperation

See also the ExpressionStatement augmentation

Creates a lesser strict comparison binary operation <.

• param left: the left expression.
• param right: the right expression.
• returns a BinaryOperation

See also the ExpressionStatement augmentation

Creates a let declaration.

For instance:

`let("answer", 42)

creates

let answer = 42

• param name: the name of the variable to define, or a tuple for destructuring
• param val: the value to assign to the variable.
• returns an AssignmentStatement or a DestructuringAssignment

Creates a list literal.

list(
  constant(42),
  constant(1337),
  call("f"): withArgs(constant("foo"))
)

creates

list[42, 1337, f("foo")]

• param values: the expressions representing the values in the list
• returns a CollectionLiteral node

Creates a list comprehension.

For instance:

listComprehension(
  plus(refLookup("i"), 1),
  `for(`var("i", 0),
       lessThan(refLookup("i"), 10),
       assign(plus(refLookup("i"), 1))
  )
)

creates

list[i + 1 for(var i = 0, i < 10, i = i + 1)]

• param expression: the comprehension expression.
• param loops: the loops of the comprehension.
• returns a CollectionComprehension node

Create a local reference with a generated name.

• returns a new LocalReference

Create a local reference with the name.

• param name: the name of the reference as a string or a ReferenceLookup
• returns a new LocalReference

Create a local reference with a generated name.

• returns a new LocalReference

Create a macro declaration.

This is just a function with a macro flag set.

See function

Call a macro.

• param name: the name of the macro
• returns a MacroInvocation

Creates a map literal.

For instance:

map(
  tuple(constant("a"), constant(1)),
  tuple(constant("b"), constant(2))
)

creates

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

• param values: instances of tuple CollectionLiteral
• returns a CollectionLiteral node

See tuple

Creates a map comprehension.

For instance:

mapComprehension(
  tuple(refLookup("i"), plus(refLookup("i"), 1)),
  `for(`var("i", 0),
       lessThan(refLookup("i"), 10),
       assign(plus(refLookup("i"), 1))
  )
)

creates

map[ [i, i + 1] for(var i = 0, i < 10, i = i + 1)]

• param expression: the comprehension expression.
• param loops: the loops of the comprehension.
• returns a CollectionComprehension node

Creates a match expression.

Typical usage:

`let("r", match()
  : when(refLookup("x": equalsTo(0)): then(constant("null"))
  : otherwise(constant("non null")))

creates

let r = match {
  when x == 0 then "null"
  otherwise "non null"
}

See MatchExpression

Creates a member for structures and union values.

Builder API on these objects implicitly create the member when needed. However, this builder can be useful if one wants to customize the member (e.g. by adding a golodoc).

Creates a subtraction binary operation -.

• param left: the left expression.
• param right: the right expression.
• returns a BinaryOperation

See also the ExpressionStatement augmentation

Creates a module with the given name.

For instance:

`module("MyModule"): `with(
  `struct("Foo"): members("bar", "baz"),
  `function("foo"): withParameters("x")
    : returns(plus(refLookup("x"), constant(1))))

creates

module MyModule

struct Foo = { bar, baz }

function foo = |x| -> x + 1

• param name the name of the module.

Creates a modulo binary operation %.

• param left: the left expression.
• param right: the right expression.
• returns a BinaryOperation

See also the ExpressionStatement augmentation

Creates a greater comparison binary operation >=.

• param left: the left expression.
• param right: the right expression.
• returns a BinaryOperation

See also the ExpressionStatement augmentation

Creates a greater strict comparison binary operation >.

• param left: the left expression.
• param right: the right expression.
• returns a BinaryOperation

See also the ExpressionStatement augmentation

Creates a named argument in a call.

For instance:

call("foo"): withArgs(
  namedArgument("b", 42),
  namedArgument("a", "answer"))

creates

foo(b=42, a="answer")

• param name: the name of the argument
• param value: the expression node representing the value
• returns a NamedArgument

Void statement.

Since this statement is ignored, it can be used to replace a statement in the tree instead of removing it.

Creates a logical negation operation not

• param value: the expression to negate
• returns a UnaryOperation

Creates a difference binary operation !=.

• param left: the left expression.
• param right: the right expression.
• returns a BinaryOperation

See also the ExpressionStatement augmentation

Creates a type-checking binary operation oftype.

• param left: the left expression.
• param right: the right expression.
• returns a BinaryOperation

See also the ExpressionStatement augmentation

Creates a logical disjunction operation or.

• param left: the left expression.
• param right: the right expression.
• returns a BinaryOperation

See also the ExpressionStatement augmentation

Creates a null-checking binary operation orIfNull.

• param left: the left expression.
• param right: the right expression.
• returns a BinaryOperation

See also the ExpressionStatement augmentation

Creates an addition binary operation +

• param left: the left expression
• param right: the right expression
• returns a BinaryOperation

See also the ExpressionStatement augmentation

Creates a range literal.

range(constant(1), constant(10))

creates

[1..10]

• param values: the expressions representing the start and end values of the range
• returns a CollectionLiteral node

Creates a reference lookup.

• param name: the name of the variable to lookup as a string or a LocalReference
• returns a ReferenceLookup

See LocalReference

Creates a return statement.

Creates a set literal.

set(
  constant(42),
  constant(1337),
  call("f"): withArgs(constant("foo"))
)

creates

set[42, 1337, f("foo")]

• param values: the expressions representing the values in the set
• returns a CollectionLiteral node

Creates a set comprehension.

For instance:

setComprehension(
  plus(refLookup("i"), 1),
  `for(`var("i", 0),
       lessThan(refLookup("i"), 10),
       assign(plus(refLookup("i"), 1))
  )
)

creates

set[i + 1 for(var i = 0, i < 10, i = i + 1)]

• param expression: the comprehension expression.
• param loops: the loops of the comprehension.
• returns a CollectionComprehension node

Creates a structure

Creates a throw statement.

Creates a multiplication binary operation *

• param left: the left expression
• param right: the right expression
• returns a BinaryOperation

See also the ExpressionStatement augmentation

Create a container for top-level elements

See ToplevelElements.of

Creates a try...catch...finally statement IR node.

For instance:

`try(
  `let("a", 10),
  call("println"): withArgs(refLookup("a"))
): `catch("ex",
  call("println"): withArgs(constant("An error occured"))
  call("println"): withArgs(refLookup("ex"))
): `finally(
  call("cleanUp")
)

creates

try {
  let a = 10
  println(a)
} catch(ex) {
  println("An error occured")
  println(ex)
} finally {
  cleanUp()
}

• param statements: the statements in the try block.
• returns a TryCatchFinally node

See TryCatchFinally and the corresponding augmentation

Creates a tuple literal.

tuple(constant(42), constant(1337))

creates

[42, 1337]

• param values: the expressions representing the values in the tuple
• returns a CollectionLiteral node

Creates a tuple comprehension.

For instance:

tupleComprehension(
  plus(refLookup("i"), 1),
  `for(`var("i", 0),
       lessThan(refLookup("i"), 10),
       assign(plus(refLookup("i"), 1))
  )
)

creates

tuple[i + 1 for(var i = 0, i < 10, i = i + 1)]

• param expression: the comprehension expression.
• param loops: the loops of the comprehension.
• returns a CollectionComprehension node

Create an union type

Creates a var declaration.

For instance:

`var("answer", 42)

creates

var answer = 42

• param name: the name of the variable to define, or a tuple for destructuring
• param val: the value to assign to the variable.
• returns an AssignmentStatement or a DestructuringAssignment

Creates a vector literal.

vector(
  constant(42),
  constant(1337),
  call("f"): withArgs(constant("foo"))
)

creates

vector[42, 1337, f("foo")]

• param values: the expressions representing the values in the vector
• returns a CollectionLiteral node

Creates a vector comprehension.

For instance:

vectorComprehension(
  plus(refLookup("i"), 1),
  `for(`var("i", 0),
       lessThan(refLookup("i"), 10),
       assign(plus(refLookup("i"), 1))
  )
)

creates

vector[i + 1 for(var i = 0, i < 10, i = i + 1)]

• param expression: the comprehension expression.
• param loops: the loops of the comprehension.
• returns a CollectionComprehension node

Creates a while loop IR node.

For instance

block(
  `var("x", 0),
  `while(lessThan(refLookup("x"), 10)): do(
    call("println"): withArgs(refLookup("x")),
    assign(plus(refLookup("x"), 1)): to("x")
  )
)

creates

var x = 0
while x < 10 {
  println(x)
  x = x + 1
}

• param cond: the node representing the while condition.
• returns a LoopStatement

See LoopStatement and the BlockContainer augmentation