1#![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
29pub const VERSION: &str = env!("CARGO_PKG_VERSION");
31
32pub const EXIT_OK: i32 = 0;
34pub const EXIT_REJECTED: i32 = 1;
36pub const EXIT_USAGE: i32 = 2;
38
39pub trait CliIo: Sync {
41 fn read_text(&self, source: &str) -> Result<String, String>;
47 fn write_stdout(&mut self, text: &str);
49 fn write_stderr(&mut self, text: &str);
51 fn version(&self) -> &str;
53}
54
55#[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 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
81pub 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 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
148fn 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#[derive(Clone, Debug, Default, PartialEq, Eq)]
198pub struct Outcome {
199 pub status: i32,
201 pub stdout: String,
203 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#[derive(Clone, Debug)]
227pub struct Invocation {
228 command: Command,
229 operands: Vec<String>,
230}
231
232impl Invocation {
233 pub fn operands(&self) -> &[String] {
236 &self.operands
237 }
238}
239
240pub 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
278pub 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
305fn 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
316pub fn run(args: &[String], io: &mut dyn CliIo) -> i32 {
318 let outcome = match plan(args, io.version()) {
319 Ok(invocation) => {
320 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}