invoke

By Goblin Docs ~ 8 min read

:invoke calls an action by name at runtime, passing arguments dynamically.

Overview

:invoke takes an action name as a string and calls it with the provided arguments. This lets you treat action names as data — store them in variables, pass them around, or read them from config.

Try this in the REPL:

gbln(1): act double(x) => return x * 2
gbln(2): :invoke("double", 5)
10
gbln(3): :invoke("double", [5])
10

gbln(1): act double(x) => return x * 2
gbln(2): :invoke("double", 5)
10
gbln(3): :invoke("double", [5])
10

Basic Usage

Pass args directly

act add(a, b) => return a + b

:invoke("add", 3, 4)    /// 7

act add(a, b) => return a + b

:invoke("add", 3, 4)    /// 7

Pass args as an array

:invoke("add", [3, 4])  /// 7

:invoke("add", [3, 4])  /// 7

Both forms are equivalent. Use whichever is more convenient.

Namespaced Actions

Actions inside modules are called with :: in the name string:

:invoke("trailboss::rewrite_wiki_links", ctx)
:invoke("markdown_core::render", ctx)

:invoke("trailboss::rewrite_wiki_links", ctx)
:invoke("markdown_core::render", ctx)

With Collection Operations

:invoke is the mechanism behind _where predicates in collection operations. The predicate is an action name passed as a string:

act is_big(x) => return x > 10

items | [3, 7, 12, 18, 2]
big | :grab_where(items, "is_big")   /// [12, 18]

act is_big(x) => return x > 10

items | [3, 7, 12, 18, 2]
big | :grab_where(items, "is_big")   /// [12, 18]

Goblin calls :invoke("is_big", element) on each item internally.

Signature

:invoke(name, arg)
:invoke(name, arg1, arg2, ...)
:invoke(name, [arg1, arg2, ...])

:invoke(name, arg)
:invoke(name, arg1, arg2, ...)
:invoke(name, [arg1, arg2, ...])

Argument	Type	Description
`name`	string	The action name to call. Use `"ns::action"` for module actions.
`args`	any	Arguments to forward. Can be passed directly or as an array.

Errors

Passing a non-string as the first argument raises a type error:

:invoke(42, 5)
/// error: T0205 type-mismatch: first argument must be a string

:invoke(42, 5)
/// error: T0205 type-mismatch: first argument must be a string

Passing an unknown action name raises an unknown-action error:

:invoke("does_not_exist", 5)
/// error: A0401 unknown-action

:invoke("does_not_exist", 5)
/// error: A0401 unknown-action

Passing the wrong number of arguments raises a wrong-arity error:

act add(a, b) => return a + b
:invoke("add", 1)
/// error: R0301 wrong-arity

act add(a, b) => return a + b
:invoke("add", 1)
/// error: R0301 wrong-arity