asimov_patterns/programs/
matcher.rs

1// This is free and unencumbered software released into the public domain.
2
3//! RDF matching: the matcher marker trait and serialization options.
4
5use crate::Execute;
6use alloc::{string::String, vec::Vec};
7use bon::Builder;
8
9/// An exact or approximate matcher that consumes RDF and describes matches as RDF.
10///
11/// The output need not be a subset of the input: it can introduce statements
12/// describing correspondences or scores. The program defines the matching
13/// relation, compared entities or reference data, output vocabulary, and score
14/// interpretation. The pattern imposes no universal algorithm or score scale.
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/// [`MatcherOptions`] selects serializations, both defaulting to `jsonl`.
23///
24/// `T` represents the result in the implementation's chosen form. The
25/// concrete execution and transport behavior is documented through
26/// [`crate::programs`]. See also the [matcher specification][spec].
27///
28/// [spec]: https://asimov-specs.github.io/program-patterns/#matcher
29pub trait Matcher<T>: Execute<T> {}
30
31/// Input/output formats and additional arguments for a [`Matcher`].
32///
33/// `Default` leaves formats unset and `other` empty. The process wrapper omits
34/// unset flags and lets the program apply its defaults. This type selects no
35/// matching algorithm and does not validate or transform RDF.
36///
37/// # Examples
38///
39/// ```rust
40/// use asimov_patterns::MatcherOptions;
41///
42/// let options = MatcherOptions::builder()
43///     .input("jsonl")
44///     .output("jsonl")
45///     .build();
46/// ```
47#[derive(Clone, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd, Builder)]
48#[builder(derive(Debug), on(String, into))]
49pub struct MatcherOptions {
50    /// Additional arguments, including optional input and output file operands.
51    ///
52    /// The wrapper appends these after generated format options. Put extension
53    /// options before files; each string is one literal argument. See
54    /// [`crate::programs`] for operand ordering and standard-stream selection.
55    #[builder(field)]
56    pub other: Vec<String>,
57
58    /// RDF input serialization passed as `--input=FORMAT` (`-i` in the CLI).
59    ///
60    /// `None` omits the option; the specified program default is `jsonl`.
61    /// This is a format token, not an input filename.
62    pub input: Option<String>,
63
64    /// RDF match-result serialization passed as `--output=FORMAT` (`-o` in the CLI).
65    ///
66    /// `None` omits the option; the specified program default is `jsonl`.
67    /// This selects neither an output file nor the vocabulary describing matches.
68    pub output: Option<String>,
69}
70
71impl<S: matcher_options_builder::State> MatcherOptionsBuilder<S> {
72    /// Appends one literal argument to [`MatcherOptions::other`], preserving order.
73    pub fn other(mut self, flag: impl Into<String>) -> Self {
74        self.other.push(flag.into());
75        self
76    }
77
78    /// Appends a present argument to [`MatcherOptions::other`]; `None` adds nothing.
79    pub fn maybe_other(mut self, flag: Option<impl Into<String>>) -> Self {
80        if let Some(flag) = flag {
81            self.other.push(flag.into());
82        }
83        self
84    }
85}
asimov_patterns/programs/matcher.rs

asimov_patterns/programs/
matcher.rs
