std only.Expand description
Process-backed implementations of the ASIMOV program patterns.
Each wrapper owns an Executor, its input/output
configuration, and a pattern-specific options value re-exported here from
asimov-patterns. Constructors prepare commands; execution validates any
supplied capabilities before starting a child. A zero-limit Lister
returns immediately after validation without spawning.
Every wrapper also implements Execute
and its corresponding pattern trait.
All wrappers set Execute::Error to ExecutorError.
Generic bounds use associated-type equality, for example
asimov_patterns::Fetcher<JsonlStream, Error = ExecutorError> or
asimov_patterns::Indexer<Error = ExecutorError>.
§Choosing a program
The table covers the wrappers available in this crate. Roles and intended payloads follow the specification; the Rust API transports serialized bytes.
| Type | Role | Input supplied to the child | Intended output |
|---|---|---|---|
Adapter | RDF dataset proxy | SPARQL on stdin | RDF |
Compiler | Prompt compiler | Natural-language text on stdin | SPARQL query |
Emitter | Value generator | No stdin | RDF |
Fetcher | URL protocol client | URL as an argument | RDF |
Indexer | Persistent RDF dataset indexer | RDF on stdin | No output value |
Lister | Directory iterator | URL as an argument | RDF |
Matcher | Exact or approximate matcher | RDF on stdin | RDF describing matches |
Prompter | LLM inference provider | Formatted Prompt on stdin | Response text |
Reader | RDF dataset importer | Arbitrary bytes on stdin | RDF |
Reasoner | RDF dataset entailer | RDF on stdin | Entailed RDF |
Resolver | URI resolver | URI as an argument | Parsed absolute URLs |
Runner | Language runtime engine | Program text on stdin | Execution result as text |
Writer | RDF dataset exporter | RDF on stdin | Serialized bytes |
All thirteen patterns in the specification have wrappers here and
corresponding traits and options in asimov-patterns.
Content types describe the external program’s contract. These wrappers do
not parse graphs or transcode input based on format options; they pass options
to the child as arguments. The other options are appended as individual
arguments, without shell expansion. Positional identifiers follow them.
Optional format fields are emitted only when set, so leaving one unset
delegates its default to the child program. The specification generally uses
jsonl for RDF streams, text for prompts and responses, and auto for a
reader’s input format or a writer’s output format.
The jsonl token alone does not establish RDF interoperability: connected
programs must agree on a documented RDF mapping profile.
The option types’ field-level contracts and defaults are documented in
asimov-patterns.
Command construction uses CommandExt::option
for optional --name=value arguments, preserving literal values and order
without building temporary argument vectors. Capability-based omission is
expressed by filtering the optional value before passing it to the helper.
§File operands
options.input and options.output name formats, not filenames. Use
options.other for supported file operands, keeping additional options
before them. For patterns accepting input and output files, a single operand
selects input; use - followed by the destination to select stdin and an
output file. An indexer’s final operand is always its required index path.
Adapter, compiler, and runner programs accept only an input-file operand.
A named input file replaces stdin as the program’s payload source. For
stream-input wrappers, pair it with Input::Ignored
to avoid also copying bytes to stdin. The prompter always writes its stored
prompt, so it does not offer that input-stream choice. A named output file
replaces stdout as the payload destination; these wrappers do not read the
file back into the returned result.
§Execution and results
Graph producers (Adapter, Emitter, Fetcher, Lister, Matcher,
Reader, and Reasoner) return a live JsonlStream.
Execution returns after spawning; polling yields JsonlBatch
values containing immutable JsonlLine values, preserving LF/CRLF terminators and an
unterminated final line. Spawn errors are returned directly; input, read, and
exit errors are stream items after any buffered complete lines. Consume the stream to
completion to check process success. Ignored or inherited stdout yields no
batches but still checks the exit status when polled to completion.
Graph producers expose with_batching(BatchOptions) to configure the captured
output stream. Defaults are 256 lines, a 256 KiB target, and 10 ms after a batch
begins. EOF or an error flushes a partial batch; no empty batches are emitted.
An oversized line is a singleton batch. Backpressure bounds read-ahead, and
batching needs a Tokio runtime with time enabled. Batch boundaries are not
graph/entry boundaries or additional subprocess framing. Use
flatten_batches for individual-line consumers.
Lister enforces its configured limit locally as a stdout line cap in every
output mode. Native --limit support is optional: the flag is forwarded for
unknown/supported capability and omitted when explicitly unsupported. The
local cap always applies, including protection against buggy subprograms.
--sort, --offset, --before, and --after are also optional native
capabilities. Supply support using Lister::with_capabilities and
ListerCapabilities. Unknown
and supported requests are forwarded; explicitly unsupported typed requests
fail before spawning with ExecutorError::UnsupportedOption.
There is no automatic discovery or emulation of sorting, offset, or cursor
bounds. Numeric offset and URI cursors are alternative pagination modes;
before/after bounds are exclusive in the chosen sort order, using entry
JSON-LD @id URIs. Limit applies after sorting and pagination. On reaching
the line cap it stops the child
and ends the stream without checking eventual exit status. A zero limit does
not spawn a child. This cap counts serialized lines, not batches or logical
RDF entries, and is applied before batching so the child stops promptly.
Graph consumers (Matcher, Reasoner, Indexer, and Writer) accept
GraphInput::Jsonl for direct stream composition.
Byte readers produce shared-buffer lines that are grouped into batches. Batch
input uses contiguous zero-copy views or bounded vectored I/O when available,
falling back to a reusable coalescing buffer. An LF is appended to each line
if missing. Existing LF/CRLF
endings are preserved. Empty input batches are ignored and blank lines are
preserved; JSON, UTF-8, and RDF are not validated. Use jsonl (the pattern
default) for graph format options; selecting another format does not change
the line-based transport.
Input feeding, stdout reading, and stderr draining run concurrently with
backpressure. Graph-output execution transfers input ownership into the
returned stream after successful spawning; subsequent executions have no
input. Output writers also move into graph streams after spawning; subsequent
calls on that wrapper discard stdout. Other stream-input wrappers consume input from its current position;
the prompter resends its stored prompt. None rewind stream input.
Once early child completion is observed, any pending feed is cancelled.
A zero exit status with an unfinished feed produces
ExecutorError::IncompleteInput, not
silent success. For intentional early exit, the low-level
Executor::execute_with_io_completion
returns separate process and input outcomes. Convenience APIs use the error
precedence in ExecutionCompletion::into_result:
source errors and non-broken-pipe stdin errors precede exit errors, which
precede broken-pipe or incomplete-input errors. Transport/forwarding and wait
failures are returned directly. Successful input delivery confirms bytes
reached the pipe, not that the child processed them at the application level.
Writer retains arbitrary-format, buffered output; Compiler and
Runner also return in-memory cursors. Indexer discards stdout and
returns () on success. Prompter decodes captured stdout as UTF-8 text;
Resolver parses it as ordered, validated absolute URL lines, preserving
spelling and duplicates. Both buffer captured output before decoding.
Output::Captured returns the payload. Ignored,
inherited, or forwarded output returns an empty cursor, stream, string, or
vector as appropriate, while still checking execution success.
Output::AsyncWrite forwards stdout incrementally
with backpressure and flushes the writer at EOF, without shutting it down or
also capturing the bytes. Write/flush failures fail execution and terminate
the child. Graph streams drive forwarding when polled; buffered wrappers
await it and retain their writer for reuse. Forwarded bytes are not decoded.
All wrappers capture stderr without a size bound for
ExecutorError diagnostics on unsuccessful exits.
Successful stderr is discarded by convenience APIs; detailed completions
retain it. Invalid UTF-8 diagnostics are omitted from exit-error messages.
Dropping an in-progress execution future drops its owned child handle and,
under the executor’s default kill-on-drop policy, requests termination.
The same applies to dropping a returned graph stream, including its upstream
input streams when programs are connected together.
Cancelling buffered execution retains its input in the wrapper; drop that
wrapper to also release any owned upstream streams. Termination applies to
each owned child, without guaranteeing termination of descendant processes.
Cancellation does not report success or roll back external side effects.
Pipeline composes graph producers and consumers with
direct OS pipes, checks every stage, and coordinates failure cleanup. Its
limited-lister source uses a bounded relay to preserve the local line cap.
Pipeline construction consumes configured wrappers; external stdin belongs
to the first stage and the final stage’s output policy selects the result.
Pipeline::with_batching overrides final graph batching; otherwise the final
program’s policy applies. Native pipe edges are not parsed into Rust batches.
Shared line views can retain larger backing allocations. Use
JsonlLine::into_compact or JsonlBatch::into_compact for sparse, long-lived
retention; stored byte counts do not measure the memory retained by sharing.
All subprocess I/O is awaited within execution or the returned stream; prompt writing does not use a detached task. Buffered captures, individual JSONL lines, and captured stderr have no configured size bound.
Structs§
- Adapter
- An external adapter that proxies an RDF dataset using SPARQL queries.
- Adapter
Options - Output-format selection and additional arguments for an
Adapter. - Compiler
- An external compiler that translates natural-language text into a SPARQL query.
- Compiler
Options - Additional arguments and an optional input file for a
Compiler. - Emitter
- An external emitter that generates values as RDF without reading stdin.
- Emitter
Options - Output-format selection and additional arguments for an
Emitter. - Fetcher
- An external fetcher that acts as a URL protocol client and produces RDF.
- Fetcher
Options - Output-format selection and additional arguments for a
Fetcher. - Indexer
- An external indexer that consumes RDF to maintain a persistent index.
- Indexer
Options - Input-format selection and additional arguments for an
Indexer. - Lister
- An external lister that iterates a directory URL and emits RDF for its entries.
- Lister
Capabilities - Declared native support for a lister program’s optional operations.
- Lister
Options - Output-format and pagination requests for a
Lister. - Matcher
- An external matcher that performs exact or approximate matching on RDF.
- Matcher
Options - Input/output formats and additional arguments for a
Matcher. - Prompt
- Prompt
Message - Prompter
- An external prompter that provides LLM inference for a
Prompt. - Prompter
Options - Prompt/response formats and inference-model selection for a
Prompter. - Reader
- An external reader that imports input data into an RDF dataset.
- Reader
Options - Source and RDF output formats for a
Reader, plus additional arguments. - Reasoner
- An external reasoner that consumes an RDF dataset and emits entailed RDF.
- Reasoner
Options - RDF input/output formats and additional arguments for a
Reasoner. - Resolver
- An external resolver that maps a URI (a URN or URL) to resolved URLs.
- Resolver
Options - Result-count selection and additional arguments for a
Resolver. - Runner
- An external runner that executes program text in a language runtime.
- Runner
Options - Runtime variable definitions and additional arguments for a
Runner. - Writer
- An external writer that exports an RDF dataset to another representation.
- Writer
Options - RDF input and export formats for a
Writer, plus additional arguments.
Enums§
Type Aliases§
- Adapter
Result - A live JSONL graph stream, or an error starting the adapter.
- Compiler
Result - Raw query bytes captured from a successful
Compiler, or an execution error. - Emitter
Result - A live JSONL graph stream, or an error starting the emitter.
- Fetcher
Result - A live JSONL graph stream, or an error starting the fetcher.
- Indexer
Result - Successful completion of an
Indexer, or an execution error. - Lister
Result - A listing stream, or a capability-validation or process-start error.
- Lister
Stream - A live stream of JSONL batches from a
Lister. - Matcher
Result - A live JSONL graph stream, or an error starting the matcher.
- Prompter
Result - The complete UTF-8 stdout of a successful
Prompter, or an execution error. - Reader
Result - A live JSONL graph stream, or an error starting the reader.
- Reasoner
Result - A live JSONL graph stream, or an error starting the reasoner.
- Resolver
Result - A list of resolved URLs, or an execution error.
- Runner
Result - Raw stdout bytes captured from a successful
Runner, or an execution error. - Writer
Result - Raw serialized bytes captured from a successful
Writer, or an execution error.