# Documentation for gololang.ir

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.

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

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

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

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

See `otherwise`

#### then(this)¶

Returns the true block.

#### then(this, statements...)¶

Defines the true block.

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

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.

- returns the module itself

### gololang.ir.TryCatchFinally¶

See `TryCatchFinally` and the corresponding factory

#### catch(this, exceptionName, statements...)¶

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.

#### finally(this, statements...)¶

Defines the `finally` block.

- param `statements`: the statements in the `finally` block.

## Functions

### and(left, right)¶

Creates a logical conjunction operation `and`.

- param `left`: the left expression.
- param `right`: the right expression.
- returns a `BinaryOperation`

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

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

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

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

### assign(value)¶

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`

### assign(name, value)¶

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`

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

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

### augmentation(name)¶

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

### block(statements...)¶

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`

### break()¶

Creates a `break` statement.

### call(fun)¶

Call a function.

Delegates on `FunctionInvocation.of`.

- returns a `FunctionInvocation`

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

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

### continue()¶

Creates a `continue` statement.

### decorator(expr)¶

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`

### define(name)¶

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`

### destruct(value)¶

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`

### divide(left, right)¶

Creates a division binary operation `/`.

- param `left`: the left expression.
- param `right`: the right expression.
- returns a `BinaryOperation`

See also the `ExpressionStatement` augmentation

### equals(left, right)¶

Creates a equality binary operation `==`.

- param `left`: the left expression.
- param `right`: the right expression.
- returns a `BinaryOperation`

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

- 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

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

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

See `ForEachLoopStatement` and the `BlockContainer` augmentation

### function(name)¶

Creates a function declaration

- param `name`: the name of the function
- returns a `GoloFunction`

See `GoloFunction.function` and `lambda`

### functionRef(func)¶

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.

### functionRef(mod, func)¶

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.

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

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

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

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

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

- param `cond`: the condition node.
- returns a `ConditionalBranching`

See `ConditionalBranching` and the associated augmentation

### import(name)¶

Creates an IR `import` node.

- param `name`: the name of the module to import.

### invoke(meth)¶

Invoke a method.

Delegates on `MethodInvocation.invoke`.

- returns a `MethodInvocation`

### is(left, right)¶

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

### isnt(left, right)¶

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

### lambda(parameters...)¶

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

### lessOrEquals(left, right)¶

Creates a lesser comparison binary operation `<=`.

- param `left`: the left expression.
- param `right`: the right expression.
- returns a `BinaryOperation`

See also the `ExpressionStatement` augmentation

### lessThan(left, right)¶

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

### let(name, val)¶

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`

### list(values...)¶

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

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

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

### localRef()¶

Create a local reference with a generated name.

- returns a new `LocalReference`

### localRef(name)¶

Create a local reference with the name.

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

### localRef(name, kind)¶

Create a local reference with a generated name.

- returns a new `LocalReference`

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

- param `values`: instances of tuple `CollectionLiteral`
- returns a `CollectionLiteral` node

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

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

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

- param `left`: the left expression.
- param `right`: the right expression.
- returns a `BinaryOperation`

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

- param `name` the name of the module.

### modulo(left, right)¶

Creates a modulo binary operation `%`.

- param `left`: the left expression.
- param `right`: the right expression.
- returns a `BinaryOperation`

See also the `ExpressionStatement` augmentation

### moreOrEquals(left, right)¶

Creates a greater comparison binary operation `>=`.

- param `left`: the left expression.
- param `right`: the right expression.
- returns a `BinaryOperation`

See also the `ExpressionStatement` augmentation

### moreThan(left, right)¶

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

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

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

### noop()¶

Void statement.

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

### not(value)¶

Creates a logical negation operation `not`

- param `value`: the expression to negate
- returns a `UnaryOperation`

### notEquals(left, right)¶

Creates a difference binary operation `!=`.

- param `left`: the left expression.
- param `right`: the right expression.
- returns a `BinaryOperation`

See also the `ExpressionStatement` augmentation

### oftype(left, right)¶

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

### or(left, right)¶

Creates a logical disjunction operation `or`.

- param `left`: the left expression.
- param `right`: the right expression.
- returns a `BinaryOperation`

See also the `ExpressionStatement` augmentation

### orIfNull(left, right)¶

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

### plus(left, right)¶

Creates an addition binary operation `+`

- param `left`: the left expression
- param `right`: the right expression
- returns a `BinaryOperation`

See also the `ExpressionStatement` augmentation

### range(values...)¶

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

### refLookup(name)¶

Creates a reference lookup.

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

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

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

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

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

### struct(name)¶

Creates a structure

### throw(ex)¶

Creates a `throw` statement.

### times(left, right)¶

Creates a multiplication binary operation `*`

- param `left`: the left expression
- param `right`: the right expression
- returns a `BinaryOperation`

See also the `ExpressionStatement` augmentation

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

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

See `TryCatchFinally` and the corresponding augmentation

### tuple(values...)¶

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

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

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

### union(name)¶

Create an union type

### var(name, val)¶

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`

### vector(values...)¶

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

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

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

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

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

See `LoopStatement` and the `BlockContainer` augmentation