# Documentation for gololang.Errors

Useful augmentations, decorators and function to deal with errors in Golo.

## Augmentations

### java.util.Optional¶

#### and(this, other)¶

Conjunctive chaining.

This is equivalent to `:flatMap(|_| -> other)`, i.e. applicative or monadic sequence with discarding. (Can also be seen as `:map(const(^id)): apply(other)`)

For instance:

    Some(1): `and(None()) == None()
    None(): `and(Some(1)) == None()
    Some(1): `and(Some("2")) == Some("2")

Note that this method is eager. If you want laziness, use the `flatMap` equivalent.

- param `other` the other optional
- return `other` if this optional is present, otherwise `this`

#### andThen(this, f)¶

Same as `map` or `flatMap`, depending on the type returned by `f`.

This is a generic version for `map` and `flatMap`: if `f` returns an `Optional`, it's equivalent to `flatMap`, otherwise, it's equivalent to `map`.

This allows code such as:

    Some(21): andThen(|x| -> x + 1): andThen(|x| -> Some(2 * x)) == Some(42)

#### apply(this, arg)¶

Apply the function contained is this optional to the given optional. If the function has several parameters, an optional containing a partialized version is returned, that can be `apply`ed to subsequent optionals. This makes `Optional` an “applicative functor”.

For instance:

    let f = Some(|x| -> x + 10)
    f: apply(Some(32)) # Some(42)
    f: apply(None())  # None()

    Some(|a, b| -> a + b): apply(Some(21)): apply(Some(21)) # Some(42)

#### either(this, mapping, default)¶

Case analysis for the option.

If the result is not empty, apply the first function (similar to `flatMap`), otherwise invoke the second function (similar to `orElseGet`). For instance:

    Some(21): either(|x| -> x * 2, -> "plop") == 42
    None(): either(|x| -> x * 2, -> "plop") == "plop"

This is indeed equivalent to

    opt: map(mapping): orElseGet(default)

- param `mapping`: the function to apply to the contained value
- param `default`: the function to invoke if the option is empty (takes no arguments)
- return the result of applying the corresponding function

#### flattened(this)¶

Remove one level of optional.

This is actually equivalent to `:flatMap(identity)` (or `:flatMap(f)` is equivalent to `:map(f): flattened()`).

For instance:

    Some(Some(42)): flattened() == Some(42)
    None(): flattened() == None()
    Some(None()): flattened() == None()

#### isEmpty(this)¶

Test if this optional is empty.

#### isNone(this)¶

Alias for `isEmpty`

#### isSome(this)¶

Alias for `isPresent`

#### isSome(this, value)¶

Test if this optional contains a value equals to the provided one.

#### iterator(this)¶

Test if this optional contains a value equals to the provided one.

#### or(this, other)¶

Disjunctive chaining.

For instance:

    Some(1): `or(Some(2)) == Some(1)
    None(): `or(Some(1)) == Some(1)
    Some(1): `or(None()) == Some(1)
    None(): `or(None()) == None()

Note that this method is eager.

Some(1): orElseGet(-> Some(2)) None(): orElseGet(-> Some(2))

- param `other` the other optional
- return `other` if this optional is empty, otherwise `this`

#### reduce(this, init, func)¶

Reduce this option using `func` with `init` as initial value.

For instance:

    Some("b"): reduce("a", |x, y| -> x + y) == "ab"
    None(): reduce(42, |x, y| -> x + y) == 42

- param `init` the initial value
- param `func` the aggregation function
- return the initial value if this is empty, the aggregated result otherwise

#### toList(this)¶

Convert this optional into a list

- return a singleton list containing the value if present, otherwise an empty list

#### toResult(this)¶

Disjunctive chaining.

For instance:

    Some(1): `or(Some(2)) == Some(1)
    None(): `or(Some(1)) == Some(1)
    Some(1): `or(None()) == Some(1)
    None(): `or(None()) == None()

Note that this method is eager.

Some(1): orElseGet(-> Some(2)) None(): orElseGet(-> Some(2))

- param `other` the other optional
- return `other` if this optional is empty, otherwise `this`

#### toResult(this, param)¶

Disjunctive chaining.

For instance:

    Some(1): `or(Some(2)) == Some(1)
    None(): `or(Some(1)) == Some(1)
    Some(1): `or(None()) == Some(1)
    None(): `or(None()) == None()

Note that this method is eager.

Some(1): orElseGet(-> Some(2)) None(): orElseGet(-> Some(2))

- param `other` the other optional
- return `other` if this optional is empty, otherwise `this`

## Functions

### catcher(recover)¶

Create a catcher that execute the given block dealing with exceptions.

This is similar to `trying`, but encapsulate the `catch` function instead of returning a `Result`. It is also similar to `catching`, but the block is the block take no parameter and is immediately executed.

    let recover = catcher(|ex| -> match {
      when ex oftype IllegalArgumentException.class then "default"
      otherwise ""
    })

    let result = recover({
      let a = bar()
      let r = foo(42)
      return "foo: " + r
    )}

This function can be used as a decorator:

    @!catcher
    function recoverIAE = |ex| -> match {
      when ex oftype IllegalArgumentException.class then "default"
      otherwise ""
    }

    let result = recoverIAE({
      let a = bar()
      let r = foo(42)
      return "foo: " + r
    })

It is somewhat equivalent to a `trying` followed by `either` as in:

    let recover = |ex| -> match { ... }

    result = catcher(recover)({
      // some code that can fail
    })

    result = trying({
      // some code that can fail
    }): either(^gololang.Functions::id, recover)

- param `recover`: the value to return if a exception occurred, or the function to apply to the exception.

See also `trying`, `catching`

### catching(default)¶

Allows an unary function to be called with an `Optional` or a `Result` value. Similar to `flatMap`, but using `default` on the exception if the call failed.

For instance:

    let foo = |x| -> x: toUpperCase()

    let safeFoo = catching("plop")(foo)

    safeFoo(null)         # "plop"
    safeFoo(None())       # "plop"
    safeFoo(Error("err")) # "plop"
    safeFoo(Ok("a"))      # "A"
    safeFoo(Some("a"))    # "A"

    catching(^gololang.error.Result::error)(foo)(null) # Result.error(NullPointerException())

Can be used as a decorator.

- param `default`: the value to return if a exception occurred, or the function to apply to the exception.

See also `trying`, `result`, `option`

### Empty()¶

Constructor for an empty `gololang.error.Result`.

### Error(message)¶

Constructor for `gololang.error.Result` errors.

- param `message`: the message for the error in the `Result`

### None()¶

Constructor for an empty `java.util.Optional`.

### nullify(f)¶

Transform a function into one that can return `null` if something went wrong (i.e. None, Error or exception).

Can be used as a decorator.

### Ok(value)¶

Constructor for `gololang.error.Result` values.

- param `value`: the value to encapsulate in the `Result`

### Option(v)¶

“Smart” constructor for `java.util.Optional`.

If the given value is already an `Optional`, returns it unchanged; if it's a `Result`, converts it into an `Optional`, and create an `Optional` otherwise (using `ofNullable`)

### option(f)¶

Transform a function raising an exception into a function returning a option. The resulting function returns `Option(f(x))` if `f(x)` succeeds and `None` if `f(x)` raises an exception.

Can be used as a decorator.

See also `raising`

### raising(f)¶

Transforms a function returning a result or an option into a function returning the associated value or raising an exception.

This is the inverse behavior of `result` and `option`

Can be used as a decorator.

See also `result`, `option`

### Result(v)¶

“Smart” constructor for `gololang.error.Result`.

If the given value is already a `Result`, returns it unchanged and create an `Optional` otherwise.

### result(f)¶

Transform a function raising an exception into a function returning a `Result`. The resulting function returns `Result.ok(f(x))` if `f(x)` succeeds and `Result.error(e)` if `f(x)` raises `e`.

Can be used as a decorator.

### Some(value)¶

Constructor `java.util.Optional` values.

- param `value`: the value to encapsulate in the `Optional`

### trying(f)¶

Execute the given block and return a `Result`.

This is similar to `result`, except that the block take no parameter and is immediately executed. This is not a decorator, but rather a replacement for a `try catch` block.

For instance:

    let res = trying({
      let f = foo()
      let x = bar()
      let z = f(x)
      return z + plop()
    })

If any of the operation in the block raises an exception, `res` will be a `Result.error` containing the exception, otherwise it will be a `Result.ok` containing the returned value.

See also `result`, `catching`