Skip to main content

crossmap_cli/
lib.rs

1//! The `crossmap` command, with everything it touches outside its arguments injected so it runs the same under test
2//! as from a terminal.
3//!
4//! The command is two pure steps around the reading of its arguments: [`plan`] reads the command line and either
5//! names the sources to read or settles the outcome (help, version, bad usage), and [`complete`] takes the texts read
6//! (or why each could not be) and produces the outcome. [`run`] joins them with a [`CliIo`]. A host that reads in its
7//! own way (the npm package's Node shim, which reads through Node's file system and `fetch`) calls the two steps and
8//! does the reading between them, and so prints exactly what this command prints. The native reader, [`read_source`],
9//! is behind the `read` feature, so the steps compile without it to `wasm32-unknown-unknown`.
10
11#![forbid(unsafe_code)]
12
13mod argument;
14#[cfg(feature = "read")]
15pub mod read_source;
16
17#[cfg(feature = "read")]
18use std::io::Write as _;
19
20use crossmap::{
21    CrossmapError, Value, assert_round_trip, decode, encode, parse_crosswalk, stringify_pretty,
22    validate_crosswalk,
23};
24
25pub use argument::{STDIN, SUPPORTED_SCHEMES, is_url, scheme_of};
26#[cfg(feature = "read")]
27pub use read_source::{ReadLimits, read_source};
28
29/// The version the command reports.
30pub const VERSION: &str = env!("CARGO_PKG_VERSION");
31
32/// The command did what was asked.
33pub const EXIT_OK: i32 = 0;
34/// The inputs were readable but the library rejected them; the reason is on standard error.
35pub const EXIT_REJECTED: i32 = 1;
36/// The command could not run: bad usage, or an argument that is unreadable or not JSON.
37pub const EXIT_USAGE: i32 = 2;
38
39/// Everything the command touches outside its arguments.
40pub trait CliIo: Sync {
41    /// The text an argument names: a file, standard input for `-`, or a URL.
42    ///
43    /// # Errors
44    ///
45    /// Why the source cannot be read; the command names the argument.
46    fn read_text(&self, source: &str) -> Result<String, String>;
47    /// Writes to standard output.
48    fn write_stdout(&mut self, text: &str);
49    /// Writes to standard error.
50    fn write_stderr(&mut self, text: &str);
51    /// The version to report.
52    fn version(&self) -> &str;
53}
54
55/// The process's own standard streams and the real readers: what the `crossmap` executable runs with, and what any other
56/// host of the command (the Python package's console script) runs with.
57#[cfg(feature = "read")]
58pub struct StandardStreams;
59
60#[cfg(feature = "read")]
61impl CliIo for StandardStreams {
62    fn read_text(&self, source: &str) -> Result<String, String> {
63        read_source(source, ReadLimits::default())
64    }
65
66    fn write_stdout(&mut self, text: &str) {
67        // A reader that closes early (`| head -c 0`) makes the write fail with a broken pipe. The result was computed
68        // either way, so that failure is dropped and the exit status the command settled on stands.
69        let _ = std::io::stdout().lock().write_all(text.as_bytes());
70    }
71
72    fn write_stderr(&mut self, text: &str) {
73        let _ = std::io::stderr().lock().write_all(text.as_bytes());
74    }
75
76    fn version(&self) -> &str {
77        VERSION
78    }
79}
80
81/// The usage text.
82pub const USAGE: &str = "Usage: crossmap encode     <crosswalk.json> <document.json>
83       crossmap decode     <crosswalk.json> <document.json>
84       crossmap validate   <crosswalk.json>
85       crossmap round-trip <crosswalk.json> <samples.json>
86
87Applies a crossmap crosswalk to JSON documents.
88
89  encode      prints the document translated from the crosswalk's source shape
90              to its target shape
91  decode      prints the document translated back, from target shape to source
92  validate    checks the crosswalk's schema and structure, printing nothing
93              when it is sound
94  round-trip  checks that decoding the encoding of every sample reproduces it
95              on the paths the crosswalk preserves; <samples.json> is a JSON
96              array of source-shape documents. Prints nothing on success
97
98  <crosswalk.json>  the crosswalk: a path, a URL, or - to read it from standard
99                    input
100  <document.json>   the document: a path, a URL, or - to read it from standard
101                    input
102  -h, --help        show this text
103  -v, --version     show the version
104
105A URL is an http:, https:, data: or file: address; any other scheme is
106unsupported. Only one argument may be -. Output is JSON on standard output.
107
108Exit status: 0 on success, 1 when the library rejected the crosswalk or the
109document (the reason is on standard error), 2 for bad usage or an argument that
110cannot be read (a missing file, a failed fetch, an unsupported scheme) or is
111not JSON.
112";
113
114#[derive(Clone, Copy, Debug)]
115enum Command {
116    Encode,
117    Decode,
118    Validate,
119    RoundTrip,
120}
121
122impl Command {
123    fn named(name: &str) -> Option<Command> {
124        match name {
125            "encode" => Some(Command::Encode),
126            "decode" => Some(Command::Decode),
127            "validate" => Some(Command::Validate),
128            "round-trip" => Some(Command::RoundTrip),
129            _ => None,
130        }
131    }
132
133    /// The arguments the command takes after its name: the crosswalk, then a document where it has one.
134    fn operand_count(self) -> usize {
135        match self {
136            Command::Validate => 1,
137            Command::Encode | Command::Decode | Command::RoundTrip => 2,
138        }
139    }
140}
141
142struct CommandLine {
143    help: bool,
144    version: bool,
145    positionals: Vec<String>,
146}
147
148/// Reads the options and positionals as Node's `parseArgs` reads them with `help` (`-h`) and `version` (`-v`).
149fn parse_command_line(args: &[String]) -> Result<CommandLine, String> {
150    let mut line = CommandLine {
151        help: false,
152        version: false,
153        positionals: Vec::new(),
154    };
155    let unknown = |option: &str| {
156        format!(
157            "Unknown option '{option}'. To specify a positional argument starting with a '-', place it at the end of the command after '--', as in '-- \"{option}\"'"
158        )
159    };
160    let mut arguments = args.iter();
161    while let Some(argument) = arguments.next() {
162        if argument == "--" {
163            line.positionals.extend(arguments.by_ref().cloned());
164            break;
165        }
166        if let Some(long) = argument.strip_prefix("--") {
167            let (name, value) = long
168                .split_once('=')
169                .map_or((long, None), |(name, value)| (name, Some(value)));
170            let flag = match name {
171                "help" => &mut line.help,
172                "version" => &mut line.version,
173                _ => return Err(unknown(argument)),
174            };
175            if value.is_some() {
176                return Err(format!("Option '--{name}' does not take an argument"));
177            }
178            *flag = true;
179            continue;
180        }
181        if argument.len() > 1 && argument.starts_with('-') {
182            for short in argument.chars().skip(1) {
183                match short {
184                    'h' => line.help = true,
185                    'v' => line.version = true,
186                    other => return Err(unknown(&format!("-{other}"))),
187                }
188            }
189            continue;
190        }
191        line.positionals.push(argument.clone());
192    }
193    Ok(line)
194}
195
196/// What the command settled on: its exit status and everything it writes to each stream.
197#[derive(Clone, Debug, Default, PartialEq, Eq)]
198pub struct Outcome {
199    /// The exit status: [`EXIT_OK`], [`EXIT_REJECTED`] or [`EXIT_USAGE`].
200    pub status: i32,
201    /// Everything written to standard output.
202    pub stdout: String,
203    /// Everything written to standard error.
204    pub stderr: String,
205}
206
207impl Outcome {
208    fn failure(status: i32, lines: &[&str]) -> Outcome {
209        Outcome {
210            status,
211            stdout: String::new(),
212            stderr: format!("{}\n", lines.join("\n").trim_end()),
213        }
214    }
215
216    fn printed(stdout: String) -> Outcome {
217        Outcome {
218            status: EXIT_OK,
219            stdout,
220            stderr: String::new(),
221        }
222    }
223}
224
225/// A command line that names a command and its sources, ready for them to be read.
226#[derive(Clone, Debug)]
227pub struct Invocation {
228    command: Command,
229    operands: Vec<String>,
230}
231
232impl Invocation {
233    /// The sources to read, in argument order: the crosswalk, then the document where the command has one. Each is
234    /// [`STDIN`], a URL (see [`is_url`]) or a path; at most one is [`STDIN`].
235    pub fn operands(&self) -> &[String] {
236        &self.operands
237    }
238}
239
240/// Reads the command line. `Ok` names the sources to read before [`complete`]; `Err` is the whole outcome when there
241/// is nothing to read: the version or the usage text asked for, or bad usage. `version` is what `--version` prints.
242///
243/// # Errors
244///
245/// The outcome, when the command ends without reading anything.
246pub fn plan(args: &[String], version: &str) -> Result<Invocation, Outcome> {
247    let usage = || Outcome::failure(EXIT_USAGE, &["expected a command and its files", "", USAGE]);
248    let line = match parse_command_line(args) {
249        Ok(line) => line,
250        Err(message) => return Err(Outcome::failure(EXIT_USAGE, &[&message, "", USAGE])),
251    };
252    if line.version {
253        return Err(Outcome::printed(format!("{version}\n")));
254    }
255    if line.help {
256        return Err(Outcome::printed(USAGE.to_owned()));
257    }
258    let Some((name, operands)) = line.positionals.split_first() else {
259        return Err(usage());
260    };
261    let Some(command) =
262        Command::named(name).filter(|command| command.operand_count() == operands.len())
263    else {
264        return Err(usage());
265    };
266    if operands.iter().filter(|operand| *operand == STDIN).count() > 1 {
267        return Err(Outcome::failure(
268            EXIT_USAGE,
269            &["only one argument can be read from standard input"],
270        ));
271    }
272    Ok(Invocation {
273        command,
274        operands: operands.to_vec(),
275    })
276}
277
278/// Finishes the command from what reading its sources gave: `reads` holds, for each of
279/// [`Invocation::operands`] in order, the text read or the reason it could not be (which the message names the
280/// argument in front of). The first failure in argument order is the one reported.
281pub fn complete(invocation: &Invocation, reads: Vec<Result<String, String>>) -> Outcome {
282    if reads.len() != invocation.operands.len() {
283        return Outcome::failure(EXIT_USAGE, &["expected a command and its files", "", USAGE]);
284    }
285    let mut documents = Vec::with_capacity(reads.len());
286    for (source, read) in invocation.operands.iter().zip(reads) {
287        match parse_json(source, read) {
288            Ok(value) => documents.push(value),
289            Err(message) => return Outcome::failure(EXIT_USAGE, &[&message]),
290        }
291    }
292    let (crosswalk_document, document) = match documents.as_slice() {
293        [crosswalk] => (crosswalk, None),
294        [crosswalk, document] => (crosswalk, Some(document)),
295        _ => {
296            return Outcome::failure(EXIT_USAGE, &["expected a command and its files", "", USAGE]);
297        }
298    };
299    match execute(invocation.command, crosswalk_document, document) {
300        Ok(outcome) => outcome,
301        Err(error) => Outcome::failure(EXIT_REJECTED, &[&error.to_string()]),
302    }
303}
304
305/// One source's text as JSON, or the message saying why it cannot be.
306fn parse_json(source: &str, read: Result<String, String>) -> Result<Value, String> {
307    let name = if source == STDIN {
308        "standard input"
309    } else {
310        source
311    };
312    let text = read.map_err(|error| format!("cannot read {name}: {error}"))?;
313    serde_json::from_str(&text).map_err(|error| format!("{name} is not valid JSON: {error}"))
314}
315
316/// Runs the command and returns its exit status.
317pub fn run(args: &[String], io: &mut dyn CliIo) -> i32 {
318    let outcome = match plan(args, io.version()) {
319        Ok(invocation) => {
320            // Read together so two remote arguments are fetched concurrently; `complete` reports the first failure in
321            // argument order.
322            let reader: &dyn CliIo = io;
323            let reads: Vec<Result<String, String>> = std::thread::scope(|scope| {
324                let handles: Vec<_> = invocation
325                    .operands()
326                    .iter()
327                    .map(|operand| scope.spawn(move || reader.read_text(operand)))
328                    .collect();
329                handles
330                    .into_iter()
331                    .map(|handle| {
332                        handle
333                            .join()
334                            .unwrap_or_else(|_| Err("the read failed".to_owned()))
335                    })
336                    .collect()
337            });
338            complete(&invocation, reads)
339        }
340        Err(outcome) => outcome,
341    };
342    if !outcome.stdout.is_empty() {
343        io.write_stdout(&outcome.stdout);
344    }
345    if !outcome.stderr.is_empty() {
346        io.write_stderr(&outcome.stderr);
347    }
348    outcome.status
349}
350
351fn execute(
352    command: Command,
353    crosswalk_document: &Value,
354    document: Option<&Value>,
355) -> Result<Outcome, CrossmapError> {
356    let crosswalk = parse_crosswalk(crosswalk_document)?;
357    let null = Value::Null;
358    let document = document.unwrap_or(&null);
359    match command {
360        Command::Encode => Ok(print(&encode(&crosswalk, document)?)),
361        Command::Decode => Ok(print(&decode(&crosswalk, document)?)),
362        Command::Validate => {
363            let issues = validate_crosswalk(&crosswalk);
364            if issues.is_empty() {
365                Ok(Outcome::default())
366            } else {
367                Err(CrossmapError::Structure { issues })
368            }
369        }
370        Command::RoundTrip => {
371            let Value::Array(samples) = document else {
372                return Ok(Outcome::failure(
373                    EXIT_USAGE,
374                    &["the samples file must hold a JSON array of documents"],
375                ));
376            };
377            assert_round_trip(&crosswalk, samples)?;
378            Ok(Outcome::default())
379        }
380    }
381}
382
383fn print(value: &Value) -> Outcome {
384    Outcome::printed(format!("{}\n", stringify_pretty(value)))
385}