asimov_patterns/programs/
writer.rs

1// This is free and unencumbered software released into the public domain.
2
3//! RDF export: the writer marker trait and input/destination format options.
4
5use crate::Execute;
6use alloc::{string::String, vec::Vec};
7use bon::Builder;
8
9/// An exporter that converts an RDF graph or dataset into a supported representation.
10///
11/// Output may be another RDF serialization or a non-RDF document or byte stream.
12/// The program defines supported formats, mappings, and any information loss,
13/// such as omission of named graphs or datatype information. This role describes
14/// a data-export operation, not an implementation of Rust's byte-writing traits.
15///
16/// # Command-line contract
17///
18/// `PROGRAM [OPTIONS] [INPUT-FILE [OUTPUT-FILE]]`
19///
20/// Input and output default to stdin and stdout. A single operand selects
21/// input; two select input then output, with `-` denoting a standard stream.
22/// [`WriterOptions`] defaults to `jsonl` input and automatic output-format
23/// selection. The program must define automatic selection even when stdout
24/// has no filename from which to infer a format.
25///
26/// `T` is the implementation's exported-result representation. See
27/// [`crate::programs`] for links to concrete execution behavior and the
28/// [writer specification][spec].
29///
30/// [spec]: https://asimov-specs.github.io/program-patterns/#writer
31pub trait Writer<T>: Execute<T> {}
32
33/// RDF input and export formats for a [`Writer`], plus additional arguments.
34///
35/// `Default` leaves formats unset and `other` empty, delegating defaults to
36/// the program. Select an explicit output format when the consumer requires
37/// a particular representation. Format selection itself does not convert data
38/// or establish that the selected program supports that format.
39///
40/// # Examples
41///
42/// ```rust
43/// use asimov_patterns::WriterOptions;
44///
45/// let options = WriterOptions::builder()
46///     .input("jsonl")
47///     .output("auto")
48///     .build();
49/// ```
50#[derive(Clone, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd, Builder)]
51#[builder(derive(Debug), on(String, into))]
52pub struct WriterOptions {
53    /// Additional arguments, including optional RDF input and exported output files.
54    ///
55    /// The wrapper appends these after generated format options. Put extension
56    /// options before files; each string is one literal argument. See
57    /// [`crate::programs`] for operand ordering and standard-stream selection.
58    #[builder(field)]
59    pub other: Vec<String>,
60
61    /// RDF input serialization passed as `--input=FORMAT` (`-i` in the CLI).
62    ///
63    /// `None` omits the option; the specified program default is `jsonl`.
64    /// This is a format token, not an input filename.
65    pub input: Option<String>,
66
67    /// Export format passed as `--output=FORMAT` (`-o` in the CLI).
68    ///
69    /// `None` omits the option; the specified default is `auto`, requesting the
70    /// program's documented format-selection policy. `auto` is not itself a
71    /// serialization. This field selects neither an output file nor capture behavior.
72    pub output: Option<String>,
73}
74
75impl<S: writer_options_builder::State> WriterOptionsBuilder<S> {
76    /// Appends one literal argument to [`WriterOptions::other`], preserving order.
77    pub fn other(mut self, flag: impl Into<String>) -> Self {
78        self.other.push(flag.into());
79        self
80    }
81
82    /// Appends a present argument to [`WriterOptions::other`]; `None` adds nothing.
83    pub fn maybe_other(mut self, flag: Option<impl Into<String>>) -> Self {
84        if let Some(flag) = flag {
85            self.other.push(flag.into());
86        }
87        self
88    }
89}
asimov_patterns/programs/writer.rs

asimov_patterns/programs/
writer.rs
