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))]
52#[cfg_attr(feature = "clap", derive(clap::Args))]
53pub struct WriterOptions {
54    /// Additional arguments, including optional RDF input and exported output files.
55    ///
56    /// The wrapper appends these after generated format options. Put extension
57    /// options before files; each string is one literal argument. See
58    /// [`crate::programs`] for operand ordering and standard-stream selection.
59    #[builder(field)]
60    pub other: Vec<String>,
61
62    /// RDF input serialization passed as `--input=FORMAT` (`-i` in the CLI).
63    ///
64    /// `None` omits the option; the specified program default is `jsonl`.
65    /// This is a format token, not an input filename.
66    pub input: Option<String>,
67
68    /// Export format passed as `--output=FORMAT` (`-o` in the CLI).
69    ///
70    /// `None` omits the option; the specified default is `auto`, requesting the
71    /// program's documented format-selection policy. `auto` is not itself a
72    /// serialization. This field selects neither an output file nor capture behavior.
73    pub output: Option<String>,
74}
75
76impl<S: writer_options_builder::State> WriterOptionsBuilder<S> {
77    /// Appends one literal argument to [`WriterOptions::other`], preserving order.
78    pub fn other(mut self, flag: impl Into<String>) -> Self {
79        self.other.push(flag.into());
80        self
81    }
82
83    /// Appends a present argument to [`WriterOptions::other`]; `None` adds nothing.
84    pub fn maybe_other(mut self, flag: Option<impl Into<String>>) -> Self {
85        if let Some(flag) = flag {
86            self.other.push(flag.into());
87        }
88        self
89    }
90}
asimov_patterns/programs/writer.rs

asimov_patterns/programs/
writer.rs
