Jido. Action. Inline
(Jido Action v3.0.0-beta.12)
View Source
Compile-time inline Action support for host DSLs.
Call use Jido.Action.Inline in each owner module. A host macro then:
- Calls
parse_bound!/3orparse_callback!/3for the slot's input mode. - Parses and validates
params_astwith its own expression adapter in bound mode. - Calls
compile!/4and emitsdeclaration_astat the declaration site. - Uses
target_astafter that declaration AST to store an ordinary Action target.
For example, a host can use the path
[host: MyApp.DSL, declaration: "greet", role: :action]. It can later call
target!(Owner, path) to retrieve only the target, without the source mapping.
A host with nested declarations can add its own typed segments, such as
group: "billing" and operation: "charge".
Paths and Action metadata are separate. The host supplies a default metadata
name; a declaration can override it with name:. Generated module names are
implementation details, not public names or code versions.
Bodies keep the owner's lexical scope and private helpers. Deploy the owner and generated Action BEAM files together. Lookup is available only after the owner compiles. It does not execute work or create atoms. Do not pass runtime or stored code to the compile-time APIs.
This API requires 3.0.0-beta.6 or later. See
Building DSLs With Inline Actions for a complete public-only host
with bound input, callback input, schemas, execution context, and lookup.
Summary
Types
Action declaration options. Values are source AST evaluated or compiled in the owner.
One owner-function head: parameter pattern, optional guard, and body.
AST returned to a host. Emit the declaration before using the target.
Host compiler options. default_name is AST; the import list is an exact value.
The input contract selected by the host slot.
A typed host identity. It starts with :host and ends with :role.
Declaration-only imports to remove from the body, by module and exact arity.
Parsed compile-time code, not a runtime model.
Functions
Installs owner hooks. Repeated use preserves declarations and host hooks.
Compiles a declaration with an explicit name: and no compiler options. See compile!/4.
Builds declaration and target AST inside a compiling owner module.
Parses named bindings, a binding list, a sole map binding, or [].
Parses a named parameter variable or a map pattern for direct callback input.
Installs owner hooks during module construction. Usually called through use.
Returns the compiled Action for the owner's exact typed path.
Types
@type action_option() :: {:do, Macro.t()} | {:name, Macro.t()} | {:description, Macro.t()} | {:schema, Macro.t()} | {:output_schema, Macro.t()} | {:context, Macro.t()}
Action declaration options. Values are source AST evaluated or compiled in the owner.
One owner-function head: parameter pattern, optional guard, and body.
AST returned to a host. Emit the declaration before using the target.
@type compiler_option() :: {:default_name, Macro.t()} | {:remove_imports, remove_imports()}
Host compiler options. default_name is AST; the import list is an exact value.
@type mode() :: :bound | :callback
The input contract selected by the host slot.
A typed host identity. It starts with :host and ends with :role.
@type remove_imports() :: [{module(), [{atom(), non_neg_integer()}]}]
Declaration-only imports to remove from the body, by module and exact arity.
@type t() :: %Jido.Action.Inline{ body_ast: Macro.t(), clauses: [clause()] | nil, context_ast: Macro.t() | nil, mode: mode(), options: keyword(Macro.t()), params_ast: Macro.t() | nil, pattern_ast: Macro.t() | nil }
Parsed compile-time code, not a runtime model.
params_ast contains the source AST in bound mode and is nil only in
callback mode. pattern_ast matches validated Action input for a single
expression body. body_ast is the original do AST. clauses is set when
the body is a list of -> heads; the compiler then emits one owner def
per clause and ignores pattern_ast as the function head. options
contains metadata and schema AST; the parser extracts do and context
into body_ast and context_ast. Hosts must parse and validate source AST
before they compile a declaration.
Functions
Installs owner hooks. Repeated use preserves declarations and host hooks.
@spec compile!(Macro.t(), t(), Macro.Env.t()) :: compilation()
Compiles a declaration with an explicit name: and no compiler options. See compile!/4.
@spec compile!(Macro.t(), t(), Macro.Env.t(), [compiler_option()]) :: compilation()
Builds declaration and target AST inside a compiling owner module.
path_ast must evaluate to a typed path with a host namespace, one or more
declaration segments, and a final role. Each segment is an atom key paired
with a non-nil atom, string, or integer. The path is evaluated once, when the
emitted declaration executes. A false compile-time branch creates no target.
Options:
default_name:is metadata AST used when the parsed options omitname:. Supply it unless the declaration has an explicit name.remove_imports:lists exact declaration-only imports to remove from the body. Other imports remain available. The default is[].
Metadata and schemas evaluate in the owner at the declaration site, under
normal Action configuration and static-schema rules. context: binds the
actual callback context without changing parameters or schemas.
Raises CompileError for invalid configuration, paths, duplicate identities,
reserved owner functions, or calls outside a compiling owner. The returned
AST is a compile-time implementation detail; it is not a runtime model.
@spec parse_bound!(Macro.t(), [action_option()], Macro.Env.t()) :: t()
Parses named bindings, a binding list, a sole map binding, or [].
A named binding is value <- source. A list groups named bindings. A sole
map binding, such as %{name: name} <- source, uses the complete source as
Action params. [] produces an empty parameter map. Duplicate names, mixed
map and named bindings, bare _, pins, header guards, and top-level struct
patterns are not supported.
A do body of only -> clauses compiles to several owner-function heads
over the validated parameter map. Binding-header guards stay illegal.
Clause heads may use when.
Options:
do:is the required Action body, either expressions or->clauses.name:overrides the host's default public Action name, not its identity.description:sets public Action metadata; it defaults tonil.schema:andoutput_schema:use static Action schemas and default to[]. Schemas are not inferred from patterns. Input defaults apply before the body matches its parameters.context: named_variablebinds actual callback context without adding a parameter or a schema field. It must not collide with a pattern variable.
Parsing checks header and option shape only. The host must parse and
validate the returned source AST before calling compile!/4. The parser
does not expand or evaluate source calls. Bindings belong to the host's
parameter mapping; they are not retained by an extracted Action target.
Raises CompileError for an invalid header or option, at the source location.
@spec parse_callback!(Macro.t() | nil, [action_option()], Macro.Env.t()) :: t()
Parses a named parameter variable or a map pattern for direct callback input.
Accepts the same options as parse_bound!/3, but rejects source bindings.
There is no host parameter mapping and params_ast is nil. Normal Action
input validation still runs, including schema defaults before the callback
pattern matches. Pass nil as the pattern when the body is a -> clause
list. A clause body cannot combine with a header pattern. Raises
CompileError for invalid headers or options.
@spec setup!(Macro.Env.t()) :: :ok
Installs owner hooks during module construction. Usually called through use.
Repeated setup preserves existing inline declarations and the host's hooks.
Raises CompileError outside a compiling module or for reserved function
conflicts. Setup does not run an inline body.
Returns the compiled Action for the owner's exact typed path.
Raises ArgumentError for an invalid or unknown path, an owner without inline
targets, or an owner that is still compiling. Lookup does not create atoms,
compile code, execute a body, or return the original source mapping.
Deploy the owner and generated Action BEAM files together. Path identity identifies the declaration, not a code version. The returned module is an ordinary Action target for Exec or a trusted host Registry.