# `GgenIgniter.Engine`
[🔗](https://github.com/seanchatmangpt/ggen_igniter/blob/v26.9.8/lib/ggen_igniter/engine.ex#L1)

Behaviour every `--engine NAME` implementation satisfies, so
`Mix.Tasks.GgenIgniter.Sync` dispatches through a lookup table
(`GgenIgniter.Engine.registry/0`) instead of hardcoded, string-pattern-matched
function clauses (`run_queries("sparql", ...)`, `run_queries("qlever", ...)`,
etc.). Adding a new engine means adding one module + one registry entry, not
editing the sync task's dispatch logic.

Two callbacks, split so per-engine setup (e.g. `qlever`'s `--store-id`
lookup and Finch bootstrap) happens once per sync run, not once per query:

- `prepare!/2` — takes the loaded `%RDF.Graph{}` and the raw CLI opts,
  returns whatever context `run/2` needs (the graph itself, a loaded store
  struct, ...).
- `run/2` — takes that context and one query string, returns `[map()]` rows
  (the same row-list contract every engine module already honored before
  this abstraction existed).

# `prepare!`

```elixir
@callback prepare!(
  RDF.Graph.t(),
  keyword()
) :: term()
```

# `run`

```elixir
@callback run(term(), String.t()) :: [map()]
```

# `fetch!`

```elixir
@spec fetch!(String.t()) :: module()
```

Looks up the engine module for `name`, raising `ArgumentError` on an unknown
engine.

## Examples

    iex> GgenIgniter.Engine.fetch!("sparql")
    GgenIgniter.Engine.Sparql

    iex> GgenIgniter.Engine.fetch!("nope")
    ** (ArgumentError) invalid --engine "nope", must be one of: oxigraph, qlever, sparql

# `registry`

```elixir
@spec registry() :: %{optional(String.t()) => module()}
```

The `--engine` name => implementing module map. The single source of truth
for valid `--engine` values.

## Examples

    iex> GgenIgniter.Engine.registry()
    %{
      "sparql" => GgenIgniter.Engine.Sparql,
      "qlever" => GgenIgniter.Engine.Qlever,
      "oxigraph" => GgenIgniter.Engine.Oxigraph
    }

# `valid_names`

```elixir
@spec valid_names() :: [String.t()]
```

Valid `--engine` names, for CLI validation/error messages.

## Examples

    iex> GgenIgniter.Engine.valid_names()
    ["oxigraph", "qlever", "sparql"]

---

*Consult [api-reference.md](api-reference.md) for complete listing*