KiwiCodec.RustlerGenerator (kiwi_codec v0.7.0)

Copy Markdown View Source

Generates Rust that decodes Kiwi data for a schema inside a Rustler NIF.

source/2 returns a complete Rust source file: decoders for the schema's definitions, the helpers they share, and NIF entrypoints. Call it from rustq.exs, where mix rustq.gen writes the file and mix rustq.gen --check keeps it fresh. The crate provides the Decoder<'a> the generated code reads with; KiwiCodec.RustlerGenerator.Decoder describes it and ships a complete one.

The generator needs RustQ, an optional dependency, and exists only where RustQ is available. Native decoders covers each feature.

Summary

Types

entrypoint()

Functions

source(schema, opts)

Returns a complete Rust source file for generated Rustler decoders.

Types

entrypoint()

@type entrypoint() :: {atom() | String.t(), String.t()}

Functions

source(schema, opts)

@spec source(
  KiwiCodec.Schema.t(),
  keyword()
) :: String.t()

Returns a complete Rust source file for generated Rustler decoders.

generate :native_decoders, "native/my_nif/src/generated.rs" do
  schema = KiwiCodec.parse_schema!(File.read!("priv/schema.kiwi"))

  content KiwiCodec.RustlerGenerator.source(schema,
    entrypoints: ["Node"],
    module_prefix: "Example.Schema"
  )
end

Options:

  • :definitions - schema definition names to generate, including their dependencies. Defaults to the requested entrypoint definitions, or all definitions when no entrypoints are requested.
  • :entrypoints - :all, {:nif_stubs, module}, a NIF stub module, definition names, or {nif_name, definition_name} entries for generated NIFs. Definition names infer decode_<definition_name> NIFs. :all generates one inferred NIF for every schema definition. A NIF stub module infers entries from one-arity decode_* stubs whose suffix matches a schema definition. For {:nif_stubs, module}, the module must expose stubs/0.
  • :module_prefix - Elixir module prefix for decoded structs.
  • :decoder - Rust path imported as Decoder. Defaults to "crate::runtime::Decoder". Its methods have the signatures KiwiCodec.RustlerGenerator.Decoder lists.
  • :features - decoder families to generate. Defaults to [:full]. Use :sparse and :skip for generic sparse map decoders and skip helpers used by projection-oriented native backends, and :records for native records Rust code can work with before encoding them; see KiwiCodec.RustlerGenerator.Records.
  • :unknown_fields - how message decoders handle fields the schema does not define: :error (default) rejects the data; :runtime_schema skips them using a schema read with the data. See KiwiCodec.RustlerGenerator.UnknownFields for the Decoder contract.