@spec atom_decoder(
  atom() | String.t(),
  keyword()
) :: RustQ.Rust.Fragment.t()

Builds a decoder from Rustler atoms into a Rust enum/value type.

RustQ.Rustler.atom_decoder(:decode_blend_mode,
  returns: :BlendMode,
  cases: [src_over: "BlendMode::SrcOver", multiply: "BlendMode::Multiply"]
)

The generated function returns NifResult<returns> by default. Pass :result to override the full return type, :input to override the input type, :atoms to override the atoms module, and :unknown to override the fallback branch.

@spec atom_dispatch(
  atom() | String.t(),
  keyword()
) :: RustQ.Rust.Function.t()

Builds a function that dispatches on an atom expression.

RustQ.Rustler.atom_dispatch(:draw_command,
  args: [surface: "&mut Surface", command: "Term<'a>"],
  on: "command.map_get(atoms::op())?.decode::<Atom>()?",
  cases: [rect: "draw_rect(surface, command)"],
  unknown: "Ok(())"
)

This is intentionally generic: use it for command dispatch, tagged map dispatch, AST node dispatch, or any other Rustler atom switch.

@spec atoms(
  [atom() | String.t() | {atom() | String.t(), String.t()}],
  keyword()
) :: RustQ.Rust.Fragment.t()

Builds a rustler::atoms! block.

@spec cached_atoms(
  [atom() | String.t() | {atom() | String.t(), String.t()}],
  keyword()
) :: [RustQ.Rust.Fragment.t()]

Builds cached atom helper functions backed by OnceLock<Atom>.

@spec init(module() | String.t()) :: RustQ.Rust.Fragment.t()

Builds the rustler::init! declaration for an Elixir module.

@spec nif(
  atom() | String.t(),
  keyword()
) :: RustQ.Rust.Function.t()

Builds a Rustler NIF function declaration.

Options include :args, :returns, :body, :vis, and :schedule.

@spec nif_export(
  atom() | String.t(),
  keyword()
) :: RustQ.Rust.Function.t()

Builds a single exported Rustler NIF function.

@spec nif_exports([{atom() | String.t(), keyword()}]) :: [RustQ.Rust.Function.t()]

Builds exported Rustler NIF functions that delegate to implementation functions.

This is useful when the exported Rustler surface is repetitive but the implementation bodies should stay handwritten.

RustQ.Rustler.nif_exports([
  render_png: [
    args: [env: "Env<'a>", batch: "Term<'a>"],
    returns: "NifResult<Term<'a>>",
    lifetime: :a,
    schedule: :dirty_cpu
  ]
])

Generates a #[rustler::nif] fn render_png(...) { render_png_impl(...) } export. Pass :impl to override the implementation function name.

@spec nif_struct(atom() | String.t(), module() | String.t(), keyword()) ::
  RustQ.Rust.Fragment.t()

Builds a Rust struct deriving NifStruct for an Elixir struct module.

@spec nif_term_builders(keyword()) :: [RustQ.Rust.Fragment.t()]

Builds raw NIF_TERM map/struct helpers.

These helpers generate unsafe Rust and are intended for low-level Rustler code where raw terms are required. Prefer term_builders/1 when Term<'a> is available.

@spec opts_decoder(
  atom() | String.t(),
  keyword()
) :: [RustQ.Rust.Fragment.t()]

Builds an options struct plus decoder function for keyword/options.

Field specs may be explicit Rust boundary specs:

RustQ.Rustler.opts_decoder(:RectOpts,
  fields: [x: [type: :f32, decode: RustQ.Rustler.Decode.opt_decode(:opt_f32, :opts, :x)]]
)

Or structural RustQ types, where the builder derives the Rust boundary type and decoder from RustQ.Meta.Type.category/1:

RustQ.Rustler.opts_decoder(:RectOpts,
  fields: [x: [type: RustQ.Spec.type(quote(do: RustQ.Type.f32())), required: true]]
)

Structural external/domain types remain Term<'a> at the boundary unless an explicit :decode expression is supplied.

@spec opts_helpers(keyword()) :: [RustQ.Rust.Fragment.t()]

Builds keyword/options helper functions over &[(Atom, Term<'a>)].

By default this includes decode_opts, decode_args, opt_term, opt_f32, opt_f32_option, opt_f32_default, opt_bool_option, and opt_atom_option. Pass :include or :exclude to select helpers.

RustQ.Rustler.opts_helpers(include: [:decode_opts, :decode_args, :opt_term])

decode_opts extracts from atoms::opts() by default. Pass :key to use a different map key expression. decode_args extracts from atoms::args() by default; pass :args_key to use a different map key expression.

@spec resource(
  atom() | String.t(),
  keyword()
) :: [RustQ.Rust.Fragment.t()]

Builds a Rustler resource struct and resource registration helpers.

@spec resource_arc(atom() | String.t()) :: String.t()

Returns the ResourceArc<...> Rust type for a resource.

@spec resource_decoder(
  atom() | String.t(),
  keyword()
) :: RustQ.Rust.Fragment.t()

Builds a decoder function for a Rustler resource.

@spec resource_handle(
  atom() | String.t(),
  keyword()
) :: [RustQ.Rust.Fragment.t()]

Builds a Rustler resource plus an Elixir handle decoder.

The generated decoder extracts a ResourceArc<...> from a field on an Elixir-facing handle struct or map. The field defaults to "ref".

RustQ.Rustler.resource_handle(:EncodedImage,
  fields: [bytes: "Vec<u8>"],
  handle_field: "ref"
)

Pass :decoder to override the decoder function name.

@spec resource_init(atom() | String.t()) :: RustQ.Rust.Fragment.t()

Builds resource initialization code for a Rustler module.

@spec resource_type(
  atom() | String.t(),
  keyword()
) :: RustQ.Rust.TypeAlias.t()

Builds a type alias for a resource's ResourceArc type.

@spec schema_items(RustQ.Rustler.Schema.t()) :: [RustQ.Rust.Fragment.t()]

Returns Rust items for a RustQ.Rustler.Schema schema.

@spec tagged_enum(
  atom() | String.t(),
  keyword()
) :: [RustQ.Rust.Fragment.t()]

Builds a Rust enum that decodes tagged Elixir structs.

@spec term_builders(keyword()) :: [RustQ.Rust.Fragment.t()]

Builds safe Term<'a> map/struct helpers.

@spec term_decoder(
  atom() | String.t(),
  keyword()
) :: [RustQ.Rust.Fragment.t()]

Builds a decoder function from a Rustler map term into a Rust struct.

@spec term_helpers(keyword()) :: [RustQ.Rust.Fragment.t()]

Builds common map/term helper functions used by generated decoders.