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.

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

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, value)

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

isSome(this)

Alias for isPresent

iterator(this)

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

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

toList(this)

Convert this optional into a list

toResult(this)

toResult(this, param)

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)

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.

See also trying, result, option

Empty()

Constructor for an empty gololang.error.Result.

Error(message)

Constructor for gololang.error.Result errors.

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.

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

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)

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

Result(v)

“Smart” constructor for gololang.error.Result.

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

Some(value)

Constructor java.util.Optional values.

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