Egglog.Program (EgglogElixir v0.1.0)

Copy Markdown

Loaded egglog program used for query-local runs.

A Program is a plain handle to a loaded native egglog base e-graph containing static declarations, rulesets, rules, and any persistent theory facts. Each run/3 call clones that base inside native egglog and executes the supplied input as query-local work.

Concurrent calls against the same Program are safe and query-local, but they are serialized by that native resource. This protects the loaded base and the clone/run operation for one handle without introducing a process-wide lock or an Elixir worker pool. Load multiple Program handles explicitly when you need parallel throughput.

Summary

Types

input()

Query-local input for run/3, check/4, extract/4, eval/4, and lookup/5.

request()

One output-producing egglog request.

run_result()

Result returned by run/3.

t()
value()

Decoded value returned by eval/4 and lookup/5.

Functions

check(program, input, fact, opts \\ [])

Runs a native egglog check and returns {:ok, true} or {:ok, false}.

check?(program, input, fact, opts \\ [])

Boolean variant of check/4.

check_fail(program, input, fact, opts \\ [])

Asserts that a native egglog check fails.

close(program)

Closes the native loaded-program resource.

eval(program, input, expr, opts \\ [])

Evaluates an egglog expression after applying query-local input.

eval!(program, input, expr, opts \\ [])

Bang variant of eval/4.

extract(program, input, expr, opts \\ [])

Extracts the cheapest native egglog term for expr.

extract!(program, input, expr, opts \\ [])

Bang variant of extract/4.

load(theory_spec, opts \\ [])

Loads a static egglog program into a reusable native handle.

load!(theory_spec, opts \\ [])

Bang variant of load/2.

lookup(program, input, name, arg_exprs, opts \\ [])

Looks up a function row after evaluating the given argument expressions.

lookup!(program, input, name, arg_exprs, opts \\ [])

Bang variant of lookup/5.

num_tuples(program)

Returns native egglog's tuple count for the loaded base program.

parse(source)

Parses egglog source into a reusable command handle.

parse!(source)

Bang variant of parse/1.

run(program, input, opts \\ [])

Runs query-local egglog code against the loaded program.

run!(program, input, opts \\ [])

Bang variant of run/3.

snapshot(program, input, opts \\ [])

Builds a query-local e-graph snapshot.

snapshot!(program, input, opts \\ [])

Bang variant of snapshot/3.

Types

input()

@type input() ::
  %{
    optional(:source) => String.t(),
    optional(:program) => String.t(),
    optional(:commands) => [String.t()],
    optional(:facts) => [String.t()],
    optional(:terms) => %{required(String.t()) => String.t()},
    optional(:sets) => [{String.t(), String.t()}],
    optional(:unions) => [{String.t(), String.t()}],
    optional(:requests) => [request()],
    optional(:schedule) => String.t(),
    optional(:snapshot) => :dot | :json | :none | String.t() | boolean(),
    optional(:snapshot_max_functions) => non_neg_integer(),
    optional(:snapshot_max_calls_per_function) => non_neg_integer(),
    optional(:snapshot_inline_leaves) => non_neg_integer(),
    optional(:snapshot_split_primitive_outputs) => boolean(),
    optional(:mode) => atom() | String.t(),
    optional(:budget) => map()
  }
  | %{optional(String.t()) => term()}
  | Egglog.Commands.t()

Query-local input for run/3, check/4, extract/4, eval/4, and lookup/5.

Strings are passed as raw egglog source. Lists are joined as egglog commands. Parsed Egglog.Commands handles can be reused when the same source is run or inspected repeatedly. Maps let Elixir code build common egglog commands without string concatenation.

request()

@type request() ::
  String.t()
  | %{type: :check, expr: String.t()}
  | %{
      :type => :extract,
      :expr => String.t(),
      optional(:variants) => pos_integer(),
      optional(:limit) => pos_integer()
    }
  | %{:type => :print_size, optional(:name) => String.t()}
  | %{
      :type => :print_function,
      :name => String.t(),
      optional(:limit) => pos_integer()
    }
  | %{optional(String.t()) => term()}

One output-producing egglog request.

A request may be written directly as an egglog command string, or as a small Elixir map that the wrapper renders to native egglog syntax.

run_result()

@type run_result() :: %{
  :status => atom(),
  :outputs => [%{type: atom(), text: String.t()}],
  :stats => map(),
  :report => map(),
  optional(:snapshot) => map()
}

Result returned by run/3.

t()

@opaque t()

value()

@type value() :: %{sort: String.t(), type: atom(), value: term()}

Decoded value returned by eval/4 and lookup/5.

:value contains a native egglog e-class value rendered as text. Primitive egglog values are decoded to ordinary Elixir values when possible: integers, floats, booleans, strings, and nil for unit.

Functions

check(program, input, fact, opts \\ [])

@spec check(t(), input(), String.t(), keyword() | map()) ::
  {:ok, boolean()} | {:error, term()}

Runs a native egglog check and returns {:ok, true} or {:ok, false}.

Supported options are the same as run/3; they are passed through to the internal run after appending (check fact) to the input requests. Defaults are therefore the run/3 defaults.

Only a failed egglog check is converted to false; parse/type/native errors are returned as {:error, reason}. Snapshot and output options may affect the internal run, but their result data is not exposed by this function.

check?(program, input, fact, opts \\ [])

@spec check?(t(), input(), String.t(), keyword() | map()) :: boolean()

Boolean variant of check/4.

Runs a native egglog check and returns {:ok, true} or {:ok, false}.

Supported options are the same as run/3; they are passed through to the internal run after appending (check fact) to the input requests. Defaults are therefore the run/3 defaults.

Only a failed egglog check is converted to false; parse/type/native errors are returned as {:error, reason}. Snapshot and output options may affect the internal run, but their result data is not exposed by this function.

It raises on non-check errors so syntax/type mistakes are not silently treated as false mathematical assertions.

check_fail(program, input, fact, opts \\ [])

@spec check_fail(t(), input(), String.t(), keyword() | map()) ::
  :ok | {:error, term()}

Asserts that a native egglog check fails.

This maps to egglog's (fail (check ...)) form and is useful for tests and tutorials that want to show a negative example without surfacing an exception.

Supported options are the same as run/3; they are passed through to the internal run after appending (fail (check fact)) to the input requests. Defaults are therefore the run/3 defaults. Only :ok or {:error, reason} is returned.

close(program)

@spec close(t()) :: :ok | {:error, term()}

Closes the native loaded-program resource.

eval(program, input, expr, opts \\ [])

@spec eval(t(), input(), String.t(), keyword() | map()) ::
  {:ok, value()} | {:error, term()}

Evaluates an egglog expression after applying query-local input.

Primitive values are decoded into Elixir values. Non-primitive e-class values are returned with type: :value.

Supported options are the query-construction subset of run/3 options:

  • :mode - selected mode when no input :schedule is supplied. Defaults to input :mode, then :default.
  • :budget - map merged after program default budget and input :budget. Defaults to %{}. Currently :rounds/"rounds" can emit a (run n) command when no selected mode schedule exists.

:output_limit and snapshot options are not used by this function because it does not return command outputs or snapshots.

String option keys are also accepted, matching the rest of the wrapper.

eval!(program, input, expr, opts \\ [])

@spec eval!(t(), input(), String.t(), keyword() | map()) :: value()

Bang variant of eval/4.

Evaluates an egglog expression after applying query-local input.

Supported options are the query-construction subset of run/3 options:

  • :mode - selected mode when no input :schedule is supplied. Defaults to input :mode, then :default.
  • :budget - map merged after program default budget and input :budget. Defaults to %{}. Currently :rounds/"rounds" can emit a (run n) command when no selected mode schedule exists.

:output_limit and snapshot options are not used by this function because it does not return command outputs or snapshots.

String option keys are also accepted, matching the rest of the wrapper.

Raises if native egglog rejects the query-local input or expression.

extract(program, input, expr, opts \\ [])

@spec extract(t(), input(), String.t(), keyword() | map()) ::
  {:ok, String.t()} | {:error, term()}

Extracts the cheapest native egglog term for expr.

Supported options:

  • :variants - optional value inserted as the second argument to native egglog's (extract expr variants) command. Defaults to unset, which uses (extract expr).

All run/3 options are also accepted and passed through after appending the extract request to the input. Defaults are the run/3 defaults. Snapshot and output options may affect the internal run, but extract/4 returns only the extracted text.

String option keys are also accepted, matching the rest of the wrapper.

extract!(program, input, expr, opts \\ [])

@spec extract!(t(), input(), String.t(), keyword() | map()) :: String.t()

Bang variant of extract/4.

Extracts the cheapest native egglog term for expr.

Supported options:

  • :variants - optional value inserted as the second argument to native egglog's (extract expr variants) command. Defaults to unset, which uses (extract expr).

All run/3 options are also accepted and passed through after appending the extract request to the input. Defaults are the run/3 defaults. Snapshot and output options may affect the internal run, but extract/4 returns only the extracted text.

String option keys are also accepted, matching the rest of the wrapper.

Raises if native egglog rejects the input or extraction output is not available.

load(theory_spec, opts \\ [])

@spec load(String.t() | map(), keyword() | map()) :: {:ok, t()} | {:error, term()}

Loads a static egglog program into a reusable native handle.

The theory may be a raw egglog source string or a map containing :source or :program.

Supported options:

  • :name - human-readable program name stored in the returned struct. Defaults to nil; it is not passed to native egglog.

  • :proofs - create the native e-graph with proof support enabled. Defaults to false. Truthy values are true, "true", "1", and 1; all other values are treated as false.

  • :modes - map from mode names to egglog schedule forms or commands. Defaults to %{}. During run/3, the selected :mode is looked up by the mode value and by to_string(mode).

  • :default_budget - map merged into each non-parsed run/3 input budget. Defaults to %{}. Currently :rounds/"rounds" and :output_limit/"output_limit" are read by run/3.

String option keys are also accepted, matching the rest of the wrapper.

load!(theory_spec, opts \\ [])

@spec load!(String.t() | map(), keyword() | map()) :: t()

Bang variant of load/2.

Loads a static egglog program into a reusable native handle.

The theory may be a raw egglog source string or a map containing :source or :program.

Supported options:

  • :name - human-readable program name stored in the returned struct. Defaults to nil; it is not passed to native egglog.

  • :proofs - create the native e-graph with proof support enabled. Defaults to false. Truthy values are true, "true", "1", and 1; all other values are treated as false.

  • :modes - map from mode names to egglog schedule forms or commands. Defaults to %{}. During run/3, the selected :mode is looked up by the mode value and by to_string(mode).

  • :default_budget - map merged into each non-parsed run/3 input budget. Defaults to %{}. Currently :rounds/"rounds" and :output_limit/"output_limit" are read by run/3.

String option keys are also accepted, matching the rest of the wrapper.

Raises if native egglog rejects the loaded theory.

lookup(program, input, name, arg_exprs, opts \\ [])

@spec lookup(t(), input(), String.t(), [String.t()], keyword() | map()) ::
  {:ok, value() | nil} | {:error, term()}

Looks up a function row after evaluating the given argument expressions.

Returns {:ok, nil} when no row exists for the evaluated key.

Supported options are the query-construction subset of run/3 options:

  • :mode - selected mode when no input :schedule is supplied. Defaults to input :mode, then :default.
  • :budget - map merged after program default budget and input :budget. Defaults to %{}. Currently :rounds/"rounds" can emit a (run n) command when no selected mode schedule exists.

:output_limit and snapshot options are not used by this function because it does not return command outputs or snapshots.

String option keys are also accepted, matching the rest of the wrapper.

lookup!(program, input, name, arg_exprs, opts \\ [])

@spec lookup!(t(), input(), String.t(), [String.t()], keyword() | map()) ::
  value() | nil

Bang variant of lookup/5.

Looks up a function row after evaluating the given argument expressions.

Supported options are the query-construction subset of run/3 options:

  • :mode - selected mode when no input :schedule is supplied. Defaults to input :mode, then :default.
  • :budget - map merged after program default budget and input :budget. Defaults to %{}. Currently :rounds/"rounds" can emit a (run n) command when no selected mode schedule exists.

:output_limit and snapshot options are not used by this function because it does not return command outputs or snapshots.

String option keys are also accepted, matching the rest of the wrapper.

Raises if native egglog rejects the query-local input or lookup expression.

num_tuples(program)

@spec num_tuples(t()) :: {:ok, non_neg_integer()} | {:error, term()}

Returns native egglog's tuple count for the loaded base program.

This wraps Rust egglog's EGraph::num_tuples() for the reusable base program. Query-local facts inserted by run/3 do not mutate this base. For query-local node/class counts, visualization, or JSON inspection, use snapshot/3 on the query you want to inspect.

parse(source)

@spec parse(String.t()) :: {:ok, Egglog.Commands.t()} | {:error, term()}

Parses egglog source into a reusable command handle.

Parsed commands can be passed to run/3. This is useful when the same command sequence is executed repeatedly; native egglog parsing happens once, while execution still happens against a fresh clone of the loaded base program.

parse!(source)

@spec parse!(String.t()) :: Egglog.Commands.t()

Bang variant of parse/1.

run(program, input, opts \\ [])

@spec run(t(), input(), keyword() | map()) :: {:ok, run_result()} | {:error, term()}

Runs query-local egglog code against the loaded program.

The loaded base program is cloned inside native egglog for each run. The clone receives query-local input and the loaded base is not mutated.

input may be:

  • a raw egglog source string,
  • a list of raw egglog command strings,
  • a parsed %Egglog.Commands{} handle returned by parse/1, or
  • a map with structured fields rendered to egglog source.

Structured input map fields:

  • :source or :program - raw egglog source emitted first. Defaults to unset.
  • :commands - list of raw egglog commands emitted after source. Defaults to [].
  • :terms - map rendered as (let name expr) commands. Defaults to %{}.
  • :facts - list of raw fact/command strings. Defaults to [].
  • :sets - list of {call, value} tuples rendered as (set call value). Defaults to [].
  • :unions - list of {left, right} tuples rendered as (union left right). Defaults to [].
  • :requests - list of output-producing requests emitted last. Defaults to []. Supported request maps are :check, :extract, :print_size, and :print_function; raw request strings are also accepted.
  • :schedule - egglog schedule string. Defaults to unset. Blank strings emit no schedule; strings starting with (run are emitted unchanged; other nonblank strings are wrapped as (run-schedule schedule).
  • :mode - mode name used when no :schedule is supplied. Defaults to :default.
  • :budget - map merged after the program default budget and before the opts[:budget] map. Defaults to %{}.
  • snapshot fields listed below may also be supplied in the input map; opts take precedence over input map snapshot fields.

Supported options:

  • :mode - selected mode when no input :schedule is supplied. Defaults to input :mode, then :default. The selected mode is looked up in the program's :modes map before :budget rounds are considered.

  • :budget - map merged after program.default_budget and input :budget. Defaults to %{}. Currently :rounds/"rounds" emits (run rounds) when positive and no selected mode schedule exists. :output_limit/"output_limit" is used as the default output limit for non-parsed inputs.

  • :output_limit - maximum number of native command outputs to keep in the returned :outputs list. Defaults to budget[:output_limit] for non-parsed inputs and unset for parsed command handles. Values must be positive integers; invalid values are ignored. When outputs are truncated, the returned result has status: :limit.

  • :snapshot - request a native snapshot after the input has run. Defaults to input :snapshot, then :none.

    Accepted values:

    • :none, "none", false, or nil - do not include a snapshot.
    • :dot, "dot", or true - include native Graphviz DOT text.
    • :json or "json" - include native JSON snapshot text.

    run/3 does not render DOT to SVG. Use snapshot/3 when you want render: :auto or render: :svg post-processing.

  • :snapshot_max_functions - value passed to native egglog's SerializeConfig.max_functions when :snapshot is enabled. Defaults to input :snapshot_max_functions, then 0. Values greater than 0 become Some(value); 0 and invalid values become None.

  • :snapshot_max_calls_per_function - value passed to native egglog's SerializeConfig.max_calls_per_function when :snapshot is enabled. Defaults to input :snapshot_max_calls_per_function, then 0. Values greater than 0 become Some(value); 0 and invalid values become None.

  • :snapshot_inline_leaves - number of native leaf-inlining passes to use on the serialized snapshot before producing DOT or JSON text. Defaults to input :snapshot_inline_leaves, then 0. Negative or invalid values behave like 0.

  • :snapshot_split_primitive_outputs - whether the native serialized snapshot should split primitive outputs into separate classes before producing DOT or JSON text. Defaults to input :snapshot_split_primitive_outputs, then false.

For parsed %Egglog.Commands{} input, :output_limit and the snapshot options above are used. :mode is passed through to native result metadata, but no mode schedule is injected because the command sequence is already parsed. Structured input fields and budget-derived schedules are not rebuilt.

The returned result map contains:

  • :status - native run status, or :limit when :output_limit truncated outputs.
  • :outputs - list of %{type: atom(), text: String.t()} command outputs.
  • :stats - compact numeric/text stats from native egglog.
  • :report - per-rule/per-ruleset reporting data from native egglog.
  • :snapshot - present only when :snapshot is :dot or :json; contains %{format: :dot | :json, text: binary(), omitted: term()}.

String option keys are also accepted, matching the rest of the wrapper.

run!(program, input, opts \\ [])

@spec run!(t(), input(), keyword() | map()) :: run_result()

Bang variant of run/3.

Runs query-local egglog code against the loaded program.

The loaded base program is cloned inside native egglog for each run. The clone receives query-local input and the loaded base is not mutated.

input may be:

  • a raw egglog source string,
  • a list of raw egglog command strings,
  • a parsed %Egglog.Commands{} handle returned by parse/1, or
  • a map with structured fields rendered to egglog source.

Structured input map fields:

  • :source or :program - raw egglog source emitted first. Defaults to unset.
  • :commands - list of raw egglog commands emitted after source. Defaults to [].
  • :terms - map rendered as (let name expr) commands. Defaults to %{}.
  • :facts - list of raw fact/command strings. Defaults to [].
  • :sets - list of {call, value} tuples rendered as (set call value). Defaults to [].
  • :unions - list of {left, right} tuples rendered as (union left right). Defaults to [].
  • :requests - list of output-producing requests emitted last. Defaults to []. Supported request maps are :check, :extract, :print_size, and :print_function; raw request strings are also accepted.
  • :schedule - egglog schedule string. Defaults to unset. Blank strings emit no schedule; strings starting with (run are emitted unchanged; other nonblank strings are wrapped as (run-schedule schedule).
  • :mode - mode name used when no :schedule is supplied. Defaults to :default.
  • :budget - map merged after the program default budget and before the opts[:budget] map. Defaults to %{}.
  • snapshot fields listed below may also be supplied in the input map; opts take precedence over input map snapshot fields.

Supported options:

  • :mode - selected mode when no input :schedule is supplied. Defaults to input :mode, then :default. The selected mode is looked up in the program's :modes map before :budget rounds are considered.

  • :budget - map merged after program.default_budget and input :budget. Defaults to %{}. Currently :rounds/"rounds" emits (run rounds) when positive and no selected mode schedule exists. :output_limit/"output_limit" is used as the default output limit for non-parsed inputs.

  • :output_limit - maximum number of native command outputs to keep in the returned :outputs list. Defaults to budget[:output_limit] for non-parsed inputs and unset for parsed command handles. Values must be positive integers; invalid values are ignored. When outputs are truncated, the returned result has status: :limit.

  • :snapshot - request a native snapshot after the input has run. Defaults to input :snapshot, then :none.

    Accepted values:

    • :none, "none", false, or nil - do not include a snapshot.
    • :dot, "dot", or true - include native Graphviz DOT text.
    • :json or "json" - include native JSON snapshot text.

    run/3 does not render DOT to SVG. Use snapshot/3 when you want render: :auto or render: :svg post-processing.

  • :snapshot_max_functions - value passed to native egglog's SerializeConfig.max_functions when :snapshot is enabled. Defaults to input :snapshot_max_functions, then 0. Values greater than 0 become Some(value); 0 and invalid values become None.

  • :snapshot_max_calls_per_function - value passed to native egglog's SerializeConfig.max_calls_per_function when :snapshot is enabled. Defaults to input :snapshot_max_calls_per_function, then 0. Values greater than 0 become Some(value); 0 and invalid values become None.

  • :snapshot_inline_leaves - number of native leaf-inlining passes to use on the serialized snapshot before producing DOT or JSON text. Defaults to input :snapshot_inline_leaves, then 0. Negative or invalid values behave like 0.

  • :snapshot_split_primitive_outputs - whether the native serialized snapshot should split primitive outputs into separate classes before producing DOT or JSON text. Defaults to input :snapshot_split_primitive_outputs, then false.

For parsed %Egglog.Commands{} input, :output_limit and the snapshot options above are used. :mode is passed through to native result metadata, but no mode schedule is injected because the command sequence is already parsed. Structured input fields and budget-derived schedules are not rebuilt.

The returned result map contains:

  • :status - native run status, or :limit when :output_limit truncated outputs.
  • :outputs - list of %{type: atom(), text: String.t()} command outputs.
  • :stats - compact numeric/text stats from native egglog.
  • :report - per-rule/per-ruleset reporting data from native egglog.
  • :snapshot - present only when :snapshot is :dot or :json; contains %{format: :dot | :json, text: binary(), omitted: term()}.

String option keys are also accepted, matching the rest of the wrapper.

Raises if native egglog rejects the input or any option validation raises.

snapshot(program, input, opts \\ [])

@spec snapshot(t(), input(), keyword() | map()) :: {:ok, map()} | {:error, term()}

Builds a query-local e-graph snapshot.

This is a convenience wrapper around run/3: it runs the query-local input against a native clone of the loaded program, requests a native DOT or JSON snapshot, then optionally renders or writes the serialized graph.

Supported options:

  • :render - output format to return. Defaults to :auto.

    Accepted values:

    • :auto, "auto", or true - render SVG with Graphviz when the dot executable is available on PATH; otherwise return DOT text.
    • :svg or "svg" - require Graphviz SVG rendering. Returns {:error, {:graphviz_missing, message}} if dot is unavailable.
    • :dot, "dot", false, or nil - return Graphviz DOT text.
    • :json or "json" - return egglog's native JSON snapshot.

    Internally, :render determines the native :snapshot format passed to run/3: :json requests JSON; every other render value requests DOT.

  • :mode - selected mode when no input :schedule is supplied. Defaults to input :mode, then :default.

  • :budget - map merged after program default budget and input :budget. Defaults to %{}. Currently :rounds/"rounds" can emit a (run n) command when no selected mode schedule exists.

  • :output_limit - passed to the underlying run/3; it can truncate snapshot.result.outputs. Defaults to budget[:output_limit] for non-parsed inputs and unset for parsed command handles.

  • :snapshot_max_functions - value passed to native egglog's SerializeConfig.max_functions. Defaults to input :snapshot_max_functions, then 0. Values greater than 0 become Some(value); 0 and invalid values become None.

  • :snapshot_max_calls_per_function - value passed to native egglog's SerializeConfig.max_calls_per_function. Defaults to input :snapshot_max_calls_per_function, then 0. Values greater than 0 become Some(value); 0 and invalid values become None.

  • :snapshot_inline_leaves - number of native leaf-inlining passes to use on the serialized snapshot before producing DOT or JSON text. Defaults to input :snapshot_inline_leaves, then 0. Negative or invalid values behave like 0.

  • :snapshot_split_primitive_outputs - whether the native serialized snapshot should split primitive outputs into separate classes before producing DOT or JSON text. Defaults to input :snapshot_split_primitive_outputs, then false.

  • :path - optional file path where the returned :text payload is written. Defaults to unset.

  • :dot_path - optional file path where DOT is written when DOT text is available. Defaults to unset. For render: :json, this key is recorded as nil if provided because no DOT text is produced.

  • :svg_path - optional file path where SVG is written when SVG rendering succeeds. Defaults to unset. For non-SVG renders, this key is recorded as nil if provided.

  • :json_path - optional file path where JSON is written when render: :json is used. Defaults to unset. For non-JSON renders, this key is recorded as nil if provided.

The returned snapshot map contains:

  • :format - one of :dot, :svg, or :json.
  • :text - the primary payload for the selected render.
  • :dot, :svg, or :json - the format-specific payload when present.
  • :omitted - native omission metadata for capped snapshots.
  • :stats - snapshot-specific native stats, currently :snapshot_nodes and :snapshot_classes when available.
  • :result - the underlying run/3 result used to obtain the native serialization.
  • any provided artifact path keys after successful writes.

String option keys are also accepted, matching the rest of the wrapper.

snapshot!(program, input, opts \\ [])

@spec snapshot!(t(), input(), keyword() | map()) :: map()

Bang variant of snapshot/3.

Builds a query-local e-graph snapshot.

This is a convenience wrapper around run/3: it runs the query-local input against a native clone of the loaded program, requests a native DOT or JSON snapshot, then optionally renders or writes the serialized graph.

Supported options:

  • :render - output format to return. Defaults to :auto.

    Accepted values:

    • :auto, "auto", or true - render SVG with Graphviz when the dot executable is available on PATH; otherwise return DOT text.
    • :svg or "svg" - require Graphviz SVG rendering. Returns {:error, {:graphviz_missing, message}} if dot is unavailable.
    • :dot, "dot", false, or nil - return Graphviz DOT text.
    • :json or "json" - return egglog's native JSON snapshot.

    Internally, :render determines the native :snapshot format passed to run/3: :json requests JSON; every other render value requests DOT.

  • :mode - selected mode when no input :schedule is supplied. Defaults to input :mode, then :default.

  • :budget - map merged after program default budget and input :budget. Defaults to %{}. Currently :rounds/"rounds" can emit a (run n) command when no selected mode schedule exists.

  • :output_limit - passed to the underlying run/3; it can truncate snapshot.result.outputs. Defaults to budget[:output_limit] for non-parsed inputs and unset for parsed command handles.

  • :snapshot_max_functions - value passed to native egglog's SerializeConfig.max_functions. Defaults to input :snapshot_max_functions, then 0. Values greater than 0 become Some(value); 0 and invalid values become None.

  • :snapshot_max_calls_per_function - value passed to native egglog's SerializeConfig.max_calls_per_function. Defaults to input :snapshot_max_calls_per_function, then 0. Values greater than 0 become Some(value); 0 and invalid values become None.

  • :snapshot_inline_leaves - number of native leaf-inlining passes to use on the serialized snapshot before producing DOT or JSON text. Defaults to input :snapshot_inline_leaves, then 0. Negative or invalid values behave like 0.

  • :snapshot_split_primitive_outputs - whether the native serialized snapshot should split primitive outputs into separate classes before producing DOT or JSON text. Defaults to input :snapshot_split_primitive_outputs, then false.

  • :path - optional file path where the returned :text payload is written. Defaults to unset.

  • :dot_path - optional file path where DOT is written when DOT text is available. Defaults to unset. For render: :json, this key is recorded as nil if provided because no DOT text is produced.

  • :svg_path - optional file path where SVG is written when SVG rendering succeeds. Defaults to unset. For non-SVG renders, this key is recorded as nil if provided.

  • :json_path - optional file path where JSON is written when render: :json is used. Defaults to unset. For non-JSON renders, this key is recorded as nil if provided.

The returned snapshot map contains:

  • :format - one of :dot, :svg, or :json.
  • :text - the primary payload for the selected render.
  • :dot, :svg, or :json - the format-specific payload when present.
  • :omitted - native omission metadata for capped snapshots.
  • :stats - snapshot-specific native stats, currently :snapshot_nodes and :snapshot_classes when available.
  • :result - the underlying run/3 result used to obtain the native serialization.
  • any provided artifact path keys after successful writes.

String option keys are also accepted, matching the rest of the wrapper.

Raises if native egglog rejects the input, Graphviz rendering fails, or artifact writing fails.