asimov_patterns/

lib.rs

// This is free and unencumbered software released into the public domain.

//! Execution traits and configuration values for ASIMOV program patterns.
//!
//! A *pattern* describes a program's role and logical input/output contract:
//! for example, a [`Reader`] imports a document into RDF, an [`Adapter`] queries
//! a dataset with SPARQL, and a [`Writer`] exports RDF to another representation.
//! The [Program Patterns Specification][pps] defines their command-line
//! interfaces and the requirements for hosts that invoke them.
//!
//! This crate provides two building blocks:
//!
//! - [`Execute<T>`] is the asynchronous operation shared by all pattern traits,
//!   with an implementation-specific associated [`Error`](Execute::Error) type.
//! - [`programs`] contains role-specific marker traits and owned option values
//!   such as [`ReaderOptions`], with builders for configuring invocations.
//! Optional native support is described separately by capability metadata such
//! as [`ListerCapabilities`], using [`OptionSupport`] to distinguish unknown
//! support from an explicit declaration. Callers supply this metadata; this
//! crate does not discover capabilities or read module manifests.
//!
//! Executable lookup, process management, stream transport, and result decoding
//! belong to implementations. The companion [`asimov-runner`][runner] crate
//! supplies Tokio-backed process wrappers and re-exports these option types.
//! [`asimov-remote`][remote] supplies HTTP-backed fetch/list operations using the
//! same traits. Shared raw JSONL payloads live in [`asimov-flow`][flow]; each
//! executor chooses its own error type. These role traits are the execution
//! boundary for reusable components, while explicit typed port schemas and
//! generalized graph scheduling are still evolving.
//! Consult its documentation for supported output modes and current limitations;
//! implementing a marker trait does not by itself establish PPS conformance.
//!
//! # Configuring an operation
//!
//! ```
//! use asimov_patterns::{ListerOptions, OutputFormat};
//!
//! let options: ListerOptions = ListerOptions::builder()
//!     .limit(25)
//!     .output("jsonl")
//!     .build();
//!
//! assert_eq!(options.limit, Some(25));
//! assert_eq!(options.output, Some(OutputFormat::Jsonl));
//! assert!(options.other.is_empty());
//! ```
//!
//! Building options neither executes a program nor validates its capabilities.
//! Unset fields remain `None`: `asimov-runner` omits the corresponding flags and
//! lets the program apply its specified defaults. In particular, `input` and
//! `output` fields name **formats**, not files or stream endpoints.
//!
//! # Payloads and representations
//!
//! Pattern traits describe semantics without fixing a Rust representation for
//! the result. Their type parameter `T` can represent serialized bytes, parsed
//! data, a fallible stream, or another documented result representation; it is
//! not the number of RDF statements or logical results. [`Indexer`] fixes its result to `()`
//! because indexing has no payload output.
//! A streaming implementation can return successful startup before execution
//! finishes; its result must expose subsequent failures. See [`programs`] for
//! links to concrete transport, completion, and result semantics.
//!
//! The options do not parse, validate, or transcode RDF. The spec's default
//! `jsonl` token requires a shared [RDF mapping profile][rdf-mapping]; it does
//! not imply JSON-LD or a particular JSON object shape. Composing two graph
//! patterns requires agreement on both serialization and profile.
//!
//! # Features
//!
//! The crate declares `no_std` and uses `alloc` for strings, collections, and
//! boxed futures. Cache and timing argument formatting requires `std` or `clap`
//! and uses `humantime`, which requires the standard library. The `clap` feature
//! also requires the standard library and enables shared argument parsing,
//! including human-readable cache ages and execution deadlines.
//! The `serde` feature serializes fetch/list and shared options for the remote
//! HTTP protocol: durations are human-readable strings, sort keys and formats
//! use CLI spellings, and unset fields are omitted. Duration parsing uses
//! `humantime` and requires the standard library.
//! The default features are `all` and `std`; `std` enables standard-library
//! support in dependencies. `all`, `tracing`, and `unstable` currently enable no
//! additional behavior in this crate. Disabling `std` here does not guarantee
//! that the dependency graph is usable on a target without a standard library.
//!
//! [pps]: https://asimov-specs.github.io/program-patterns/
//! [runner]: https://docs.rs/asimov-runner
//! [remote]: https://docs.rs/asimov-remote
//! [flow]: https://docs.rs/asimov-flow
//! [rdf-mapping]: https://asimov-specs.github.io/program-patterns/#rdf-mapping

#![no_std]
#![forbid(unsafe_code)]
#![cfg_attr(docsrs, feature(doc_cfg))]

extern crate alloc;

#[cfg(any(feature = "std", feature = "clap"))]
extern crate std;

pub mod execute;
pub use execute::*;

pub mod capabilities;
pub use capabilities::*;

pub mod options;
pub use options::*;

pub mod output_format;
pub use output_format::*;

pub mod programs;
pub use programs::*;

#[cfg(feature = "serde")]
mod serialization;