asimov-patterns 25.6.0

ASIMOV Software Development Kit (SDK) for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

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

//! URL-to-RDF retrieval: the fetcher marker trait and options.

#![allow(unused)]

use crate::Execute;
use alloc::{string::String, vec::Vec};
use bon::Builder;

const HELP_OUTPUT: &str = r#"The output format."#;
const HELP_JQ: &str = r#"Filter JSON output using a jq expression.

For example, "select(.name)"."#;

/// A URL protocol client that retrieves one resource and represents it as RDF.
///
/// The program defines supported URL schemes and the mapping from retrieved
/// content to RDF. A single resource may produce many RDF statements. Returning
/// arbitrary response bytes alone does not fulfill the RDF output contract.
///
/// # Command-line contract
///
/// `PROGRAM [OPTIONS] INPUT-URL`
///
/// One absolute URL is required as a single argument; it is not a stdin
/// payload or an implicitly converted local pathname. RDF is written to stdout
/// using [`FetcherOptions::output`] (`jsonl` by default). The program validates
/// the URL and rejects unsupported schemes.
///
/// `T` is the implementation's result representation. Retrieval, redirects,
/// authentication, caching, and resource-to-RDF mapping belong to the program.
/// See [`crate::programs`] for links to concrete execution behavior and the
/// [fetcher specification][spec].
///
/// [spec]: https://asimov-specs.github.io/program-patterns/#fetcher
pub trait Fetcher<T>: Execute<T> {}

/// Output-format selection, filtering, and additional arguments for a [`Fetcher`].
///
/// The URL is supplied separately by the implementation's invocation API.
/// `Default` leaves optional fields unset and `other` empty; format support and
/// URL validity are not checked by this configuration type. A host can flatten
/// [`crate::CachingOptions`] and [`crate::TimingOptions`] alongside this type
/// for shared caching and execution timing arguments.
///
/// # Examples
///
/// ```rust
/// use asimov_patterns::FetcherOptions;
///
/// let options = FetcherOptions::builder()
///     .output("jsonl")
///     .build();
/// ```
#[derive(Clone, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd, Builder)]
#[builder(derive(Debug), on(String, into))]
#[cfg_attr(feature = "clap", derive(clap::Args))]
#[cfg_attr(feature = "clap", command(about = None, long_about = None))]
pub struct FetcherOptions {
    /// Additional arguments placed after generated options and before the URL.
    ///
    /// Each string is one literal argument, without shell expansion. The runner
    /// supplies the URL separately; do not duplicate it here. See [`crate::programs`].
    #[builder(field)]
    #[cfg_attr(feature = "clap", clap(skip))]
    pub other: Vec<String>,

    /// The output format.
    ///
    /// RDF serialization passed as `--output=FORMAT` (`-o` in the CLI).
    ///
    /// `None` omits the option; the specified program default is `jsonl`.
    /// This names a serialization, not a file or a raw-response retrieval mode.
    #[cfg_attr(
        feature = "clap",
        clap(
            value_name = "FORMAT",
            short = 'o',
            long,
            help = HELP_OUTPUT,
            long_help = HELP_OUTPUT
        )
    )]
    pub output: Option<String>,

    /// Filter JSON output using a jq expression.
    ///
    /// Applied by the host to retrieved output, not forwarded to the external
    /// fetcher by `asimov-runner`. This type stores the expression without
    /// compiling or evaluating it.
    #[cfg_attr(
        feature = "clap",
        clap(
            long,
            value_name = "EXPR",
            help = "Filter JSON output using a jq expression",
            long_help = HELP_JQ
        )
    )]
    pub jq: Option<String>,
}

impl<S: fetcher_options_builder::State> FetcherOptionsBuilder<S> {
    /// Appends one literal argument to [`FetcherOptions::other`], preserving order.
    pub fn other(mut self, flag: impl Into<String>) -> Self {
        self.other.push(flag.into());
        self
    }

    /// Appends a present argument to [`FetcherOptions::other`]; `None` adds nothing.
    pub fn maybe_other(mut self, flag: Option<impl Into<String>>) -> Self {
        if let Some(flag) = flag {
            self.other.push(flag.into());
        }
        self
    }
}