Egglog.EGraph (EgglogElixir v0.1.0)

Copy Markdown

Process-owned mutable native egglog e-graph session.

Egglog.EGraph is the interactive counterpart to Egglog.Program. Use it when you want egglog state to persist across calls, as in a REPL, Livebook, or exploratory workflow:

{:ok, eg} = Egglog.EGraph.new()
{:ok, _} = Egglog.EGraph.run(eg, "(datatype T (A) (B))")
{:ok, _} = Egglog.EGraph.run(eg, "(let x (A))")

Each successful run/3 mutates the native e-graph owned by this session's Elixir process. Concurrent callers are serialized through that owner process. This is intentionally different from Egglog.Program.run/3, which runs each query against a native clone of a loaded base program.

push/2 and pop/2 delegate to native egglog's (push) and (pop) commands. They are useful for temporary experiments:

:ok = Egglog.EGraph.push(eg)
{:ok, _} = Egglog.EGraph.run(eg, "(let tmp (A))")
:ok = Egglog.EGraph.pop(eg)

The result shape of run/3 matches Egglog.Program.run/3: outputs are a list of %{type: atom(), text: String.t()} maps and stats are a compact map.

Summary

Types

input()

Raw or parsed egglog commands accepted by run/3.

run_result()

Result returned by run/3.

t()
value()

Decoded value returned by eval/2 and lookup/3.

Functions

check(egraph, fact, opts \\ [])

Runs a native egglog check against the current mutable session.

check?(egraph, fact, opts \\ [])

Boolean variant of check/3.

check_fail(egraph, fact, opts \\ [])

Asserts that a native egglog check fails.

close(egraph)

Closes the native mutable e-graph and stops the session process.

eval(e_graph, expr)

Evaluates an egglog expression in the current mutable session.

eval!(egraph, expr)

Bang variant of eval/2.

extract(egraph, expr, opts \\ [])

Extracts the cheapest native egglog term for expr in the current session.

extract!(egraph, expr, opts \\ [])

Bang variant of extract/3.

lookup(e_graph, name, arg_exprs)

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

lookup!(egraph, name, arg_exprs)

Bang variant of lookup/3.

new(source \\ "", opts \\ [])

Creates a process-owned mutable native e-graph session.

num_tuples(e_graph)

Returns native egglog's tuple count for the current mutable session.

parse(source)

Parses egglog source into a reusable command handle.

parse!(source)

Bang variant of parse/1.

pop(egraph, count \\ 1)

Pops native egglog rollback points.

push(egraph, count \\ 1)

Pushes a native egglog rollback point.

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

Runs egglog code against the mutable session.

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

Bang variant of run/3.

snapshot(egraph, opts \\ [])

Builds a snapshot of the current mutable e-graph.

snapshot!(egraph, opts \\ [])

Bang variant of snapshot/2.

Types

input()

@type input() :: String.t() | [String.t()] | Egglog.Commands.t()

Raw or parsed egglog commands accepted by run/3.

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/2 and lookup/3.

: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(egraph, fact, opts \\ [])

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

Runs a native egglog check against the current mutable session.

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

Only the check result is returned. Snapshot and output options may affect the internal run, but their result data is not exposed by this function.

check?(egraph, fact, opts \\ [])

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

Boolean variant of check/3.

Runs a native egglog check against the current mutable session.

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

Only the check result is returned. Snapshot and output options may affect the internal run, but their result data is not exposed by this function.

Raises on non-check errors so syntax/type/native errors are not silently treated as false mathematical assertions.

check_fail(egraph, fact, opts \\ [])

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

Asserts that a native egglog check fails.

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

close(egraph)

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

Closes the native mutable e-graph and stops the session process.

eval(e_graph, expr)

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

Evaluates an egglog expression in the current mutable session.

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

eval!(egraph, expr)

@spec eval!(t(), String.t()) :: value()

Bang variant of eval/2.

extract(egraph, expr, opts \\ [])

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

Extracts the cheapest native egglog term for expr in the current session.

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 to the internal extract run. Defaults are the run/3 defaults. Snapshot and output options may affect the internal run, but extract/3 returns only the extracted text.

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

extract!(egraph, expr, opts \\ [])

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

Bang variant of extract/3.

Extracts the cheapest native egglog term for expr in the current session.

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 to the internal extract run. Defaults are the run/3 defaults. Snapshot and output options may affect the internal run, but extract/3 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.

lookup(e_graph, name, arg_exprs)

@spec lookup(t(), String.t(), [String.t()]) :: {: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.

lookup!(egraph, name, arg_exprs)

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

Bang variant of lookup/3.

new(source \\ "", opts \\ [])

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

Creates a process-owned mutable native e-graph session.

source is optional initial egglog code. Unlike Egglog.Program, this state is not a read-only base: later run/3 calls mutate it directly through the session owner process.

Options:

  • :name - human-readable session 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.

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

num_tuples(e_graph)

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

Returns native egglog's tuple count for the current mutable session.

This wraps Rust egglog's EGraph::num_tuples(). It is a coarse database-size counter, not a graph summary. For node/class counts, visualization, or JSON inspection, use snapshot/2.

parse(source)

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

Parses egglog source into a reusable command handle.

parse!(source)

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

Bang variant of parse/1.

pop(egraph, count \\ 1)

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

Pops native egglog rollback points.

count defaults to 1. Popping too much returns an error from native egglog.

push(egraph, count \\ 1)

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

Pushes a native egglog rollback point.

count defaults to 1. This corresponds to (push) for 1, or (push count) for larger counts.

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

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

Runs egglog code against the mutable session.

On success, native egglog state is retained for future calls. On error, egglog may have applied commands that appeared before the failing command in the same program; use push/2 and pop/2 around speculative work when you need an explicit rollback point.

input may be:

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

Supported options:

  • :output_limit - maximum number of native command outputs to keep in the returned :outputs list. Defaults to unset, meaning all outputs are kept. 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 :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/2 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 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 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 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 false.

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!(egraph, input, opts \\ [])

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

Bang variant of run/3.

Runs egglog code against the mutable session.

On success, native egglog state is retained for future calls. On error, egglog may have applied commands that appeared before the failing command in the same program; use push/2 and pop/2 around speculative work when you need an explicit rollback point.

input may be:

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

Supported options:

  • :output_limit - maximum number of native command outputs to keep in the returned :outputs list. Defaults to unset, meaning all outputs are kept. 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 :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/2 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 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 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 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 false.

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(egraph, opts \\ [])

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

Builds a snapshot of the current mutable e-graph.

This runs no new egglog commands; it asks native egglog to serialize the session's current state, then optionally renders or writes that 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.

  • :snapshot_max_functions - value passed to native egglog's SerializeConfig.max_functions. Defaults to 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 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 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 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!(egraph, opts \\ [])

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

Bang variant of snapshot/2.

Builds a snapshot of the current mutable e-graph.

This runs no new egglog commands; it asks native egglog to serialize the session's current state, then optionally renders or writes that 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.

  • :snapshot_max_functions - value passed to native egglog's SerializeConfig.max_functions. Defaults to 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 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 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 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 snapshot serialization, Graphviz rendering, or artifact writing fails.