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.

Augmentations

gololang.ir.BlockContainer

Adds more fluent methods to build a block container.

do(this, statements...)

Defines the block as the given statements

See body

gololang.ir.CaseStatement

Adds more fluent methods to build a case statement.

See CaseStatement and associated factory

do(this, statements...)

Define the action for a when clause.

See then

gololang.ir.ConditionalBranching

Adds more fluent methods to build a conditional branching IR

See ConditionalBranching and the associated factory

else(this)

Returns the false block or the nested branch.

else(this, statements...)

Defines the false block or nested conditional

See otherwise

then(this)

Returns the true block.

then(this, statements...)

Defines the true block.

See whenTrue

gololang.ir.ExpressionStatement

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

and(this, other)

See and

divide(this, other)

See divide

equalsTo(this, other)

See equals

is(this, other)

See is

isnt(this, other)

See isnt

lessOrEquals(this, other)

See lessOrEquals

lessThan(this, other)

See lessThan

moreOrEquals(this, other)

See moreOrEquals

moreThan(this, other)

See moreThan

notEquals(this, other)

See notEquals

oftype(this, other)

See oftype

or(this, other)

See or

orIfNull(this, other)

See orIfNull

plus(this, other)

See plus

times(this, other)

See times

gololang.ir.GoloElement

Utility augmentation on all IR elements.

dump(this)

Prints a representation of this node subtree to the terminal.

gololang.ir.GoloModule

with(this, elements...)

Adds all the given elements to the module.

gololang.ir.TryCatchFinally

See TryCatchFinally and the corresponding factory

catch(this, exceptionName, statements...)

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

finally(this, statements...)

Defines the finally block.

Functions

and(left, right)

Creates a logical conjunction operation and.

See also the ExpressionStatement augmentation

array(values...)

Creates an array literal.

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

creates

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

arrayComprehension(expression, loops...)

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

assign(value)

Create a assignment statement.

For instance:

answer = 42

can be created with

assign(42): to("foo")

assign(name, value)

Creates an assignment statement.

For instance:

assign("foo", 42)

creates

foo = 42

augment(target)

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
}

augmentation(name)

Creates a named augmentation.

Typical usage:

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

creates

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

block(statements...)

Creates a block containing the given statements.

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

break()

Creates a break statement.

call(fun)

Call a function.

Delegates on FunctionInvocation.of.

case()

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

comment(message)

Void statement containing a message.

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

constant(value)

Creates a constant expression.

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

continue()

Creates a continue statement.

decorator(expr)

Create a function decorator from the given expression.

See Decorator.of

define(name)

Create a declaring assignment statement.

For instance:

let answer = 42

can be created with

define("answer"): as(42)

destruct(value)

Create a destructuring assignment statement.

For instance:

a, b = foo()

can be created with

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

divide(left, right)

Creates a division binary operation /.

See also the ExpressionStatement augmentation

equals(left, right)

Creates a equality binary operation ==.

See also the ExpressionStatement augmentation

for(init, cond, post)

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

See LoopStatement and the BlockContainer augmentation

foreach(vars...)

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

See ForEachLoopStatement and the BlockContainer augmentation

function(name)

Creates a function declaration

See GoloFunction.function and lambda

functionRef(func)

Creates a reference to the named function.

For instance:

functionRef("foo")

creates

^foo

functionRef(mod, func)

Creates a reference to the named function and module.

functionRef(mod, func, arity)

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

functionRef(mod, func, arity, varargs)

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

if(cond)

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

See ConditionalBranching and the associated augmentation

import(mod)

Creates an IR import node.

See ModuleImport.of

invoke(meth)

Invoke a method.

Delegates on MethodInvocation.invoke.

is(left, right)

Creates an identity equality binary operation is.

See also the ExpressionStatement augmentation

isnt(left, right)

Creates an identity difference binary operation isnt.

See also the ExpressionStatement augmentation

lambda(parameters...)

Creates an anonymous function.

Typical usage:

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

creates

|a, b| -> a + b

lessOrEquals(left, right)

Creates a lesser comparison binary operation <=.

See also the ExpressionStatement augmentation

lessThan(left, right)

Creates a lesser strict comparison binary operation <.

See also the ExpressionStatement augmentation

let(name, val)

Creates a let declaration.

For instance:

`let("answer", 42)

creates

let answer = 42

list(values...)

Creates a list literal.

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

creates

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

listComprehension(expression, loops...)

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

localRef()

Create a local reference with a generated name.

localRef(name)

Create a local reference with the name.

localRef(name, kind)

Create a local reference with a generated name.

macro(name)

Create a macro declaration.

This is just a function with a macro flag set.

See function

macroCall(name)

Call a macro.

map(values...)

Creates a map literal.

For instance:

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

creates

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

See tuple

mapComprehension(expression, loops...)

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

match()

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

member(name)

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

minus(left, right)

Creates a subtraction binary operation -.

See also the ExpressionStatement augmentation

module(name)

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

modulo(left, right)

Creates a modulo binary operation %.

See also the ExpressionStatement augmentation

moreOrEquals(left, right)

Creates a greater comparison binary operation >=.

See also the ExpressionStatement augmentation

moreThan(left, right)

Creates a greater strict comparison binary operation >.

See also the ExpressionStatement augmentation

namedArgument(name, value)

Creates a named argument in a call.

For instance:

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

creates

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

noop()

Void statement.

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

not(value)

Creates a logical negation operation not

notEquals(left, right)

Creates a difference binary operation !=.

See also the ExpressionStatement augmentation

oftype(left, right)

Creates a type-checking binary operation oftype.

See also the ExpressionStatement augmentation

or(left, right)

Creates a logical disjunction operation or.

See also the ExpressionStatement augmentation

orIfNull(left, right)

Creates a null-checking binary operation orIfNull.

See also the ExpressionStatement augmentation

plus(left, right)

Creates an addition binary operation +

See also the ExpressionStatement augmentation

range(values...)

Creates a range literal.

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

creates

[1..10]

refLookup(name)

Creates a reference lookup.

See LocalReference

return(value)

Creates a return statement.

set(values...)

Creates a set literal.

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

creates

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

setComprehension(expression, loops...)

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

struct(name)

Creates a structure

throw(ex)

Creates a throw statement.

times(left, right)

Creates a multiplication binary operation *

See also the ExpressionStatement augmentation

toplevels(elements...)

Create a container for top-level elements

See ToplevelElements.of

try(statements...)

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()
}

See TryCatchFinally and the corresponding augmentation

tuple(values...)

Creates a tuple literal.

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

creates

[42, 1337]

tupleComprehension(expression, loops...)

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

union(name)

Create an union type

var(name, val)

Creates a var declaration.

For instance:

`var("answer", 42)

creates

var answer = 42

vector(values...)

Creates a vector literal.

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

creates

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

vectorComprehension(expression, loops...)

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

while(cond)

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
}

See LoopStatement and the BlockContainer augmentation