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:

  1. Calls parse_bound!/3 or parse_callback!/3 for the slot's input mode.
  2. Parses and validates params_ast with its own expression adapter in bound mode.
  3. Calls compile!/4 and emits declaration_ast at the declaration site.
  4. Uses target_ast after 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.

t()

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

action_option()

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

clause()

@type clause() :: {Macro.t(), Macro.t() | nil, Macro.t()}

One owner-function head: parameter pattern, optional guard, and body.

compilation()

@type compilation() :: %{target_ast: Macro.t(), declaration_ast: Macro.t()}

AST returned to a host. Emit the declaration before using the target.

compiler_option()

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

mode()

@type mode() :: :bound | :callback

The input contract selected by the host slot.

path()

@type path() :: [{atom(), atom() | String.t() | integer()}]

A typed host identity. It starts with :host and ends with :role.

remove_imports()

@type remove_imports() :: [{module(), [{atom(), non_neg_integer()}]}]

Declaration-only imports to remove from the body, by module and exact arity.

t()

@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

__using__(options)

(macro)

Installs owner hooks. Repeated use preserves declarations and host hooks.

compile!(path_ast, parsed, caller)

@spec compile!(Macro.t(), t(), Macro.Env.t()) :: compilation()

Compiles a declaration with an explicit name: and no compiler options. See compile!/4.

compile!(path_ast, parsed, caller, options)

@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 omit name:. 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.

parse_bound!(bindings, options, caller)

@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 to nil.
  • schema: and output_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_variable binds 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.

parse_callback!(pattern, options, caller)

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

setup!(caller)

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

target!(owner, path)

@spec target!(module(), path()) :: module()

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.