Skip to main content

alux_cli_direct/
command_line.rs

1//! Reads a command line's words once, as POSIX utilities do, for every interpretation of what they
2//! say.
3//!
4//! The reader decides what each word is: an option with or without its value, a switch, an
5//! operand, or the `--` that ends the options. It reports each through [`CommandLineAlg`], so
6//! assigning words to arguments, skipping global options before a command's path, and printing a
7//! canonical command line all read words by the same rules.
8
9use alux_cli::{ArgumentInfo, Arity, Conventions, Part, SourceInfo};
10use std::ffi::{OsStr, OsString};
11
12/// Places something read in the words: the word, by index, and the byte within it.
13#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
14pub struct Span {
15    /// The word's index among the words read.
16    pub word: usize,
17    /// The byte within the word.
18    pub byte: usize,
19}
20
21/// States why words do not read as a command's arguments, and where.
22#[derive(Clone, Debug, PartialEq, Eq)]
23pub struct ParseError {
24    /// Where the words stop reading as the command's arguments.
25    pub at: Span,
26    /// What is wrong there.
27    pub kind: ParseErrorKind,
28}
29
30/// States what is wrong where words stop reading as a command's arguments.
31#[derive(Clone, Debug, PartialEq, Eq)]
32pub enum ParseErrorKind {
33    /// An option no argument of the command is spelled as.
34    Unknown(String),
35    /// An option that takes a value was last, with no value after it.
36    MissingValue(String),
37    /// A switch was given a value.
38    SwitchValue(String),
39    /// A positional word no positional argument takes.
40    Unexpected(String),
41}
42
43/// Interprets what a command line's words say, in order.
44pub(crate) trait CommandLineAlg {
45    /// A switch was given, or an option whose value is optional was given none.
46    fn switch(&mut self, argument: &ArgumentInfo);
47    /// An option was given `value`.
48    fn value(&mut self, argument: &ArgumentInfo, value: OsString);
49    /// The word at index `at` is an operand.
50    fn operand(&mut self, word: &OsStr, at: usize);
51    /// `--` ended the options.
52    fn end_of_options(&mut self) {}
53}
54
55/// What one word was read as.
56#[derive(Clone, Copy, PartialEq, Eq)]
57pub(crate) enum Read {
58    Options,
59    Operand,
60    EndOfOptions,
61}
62
63/// The words being read, and the next to read.
64pub(crate) struct Cursor<'w> {
65    words: &'w [OsString],
66    at: usize,
67}
68
69impl<'w> Cursor<'w> {
70    pub(crate) fn new(words: &'w [OsString]) -> Self {
71        Self { words, at: 0 }
72    }
73
74    /// The index of the next word.
75    pub(crate) fn at(&self) -> usize {
76        self.at
77    }
78
79    /// Consumes the next word.
80    pub(crate) fn bump(&mut self) -> Option<&'w OsString> {
81        let word = self.words.get(self.at)?;
82        self.at += 1;
83        Some(word)
84    }
85}
86
87/// Reads every word under `conventions` into `syntax`.
88///
89/// Accepts `--long value`, `--long=value`, `-s value`, `-svalue`, clustered switches `-abc`, and
90/// `--`, after which every word is an operand, each as the conventions allow.
91pub(crate) fn read(
92    arguments: &[ArgumentInfo],
93    words: &[OsString],
94    conventions: Conventions,
95    syntax: &mut impl CommandLineAlg,
96) -> Result<(), ParseError> {
97    if conventions.verbatim {
98        words.iter().enumerate().for_each(|(at, word)| syntax.operand(word, at));
99        return Ok(());
100    }
101    let mut cursor = Cursor::new(words);
102    let mut options = true;
103    while options {
104        match read_word(arguments, conventions, &mut cursor, syntax)? {
105            None => return Ok(()),
106            Some(Read::EndOfOptions) => options = false,
107            Some(Read::Operand) => options = !conventions.options_first,
108            Some(Read::Options) => {}
109        }
110    }
111    loop {
112        let at = cursor.at();
113        let Some(word) = cursor.bump() else { break };
114        // An operand assigning an argument still assigns it after `--`: `dd -- if=x`.
115        if !assign(arguments, word, syntax) {
116            syntax.operand(word, at);
117        }
118    }
119
120    Ok(())
121}
122
123/// Reads `word` as the operand `name=value` of an argument assigned `name`, answering whether it is
124/// one. The value is everything after the first `=`, and may be empty.
125fn assign(arguments: &[ArgumentInfo], word: &OsStr, syntax: &mut impl CommandLineAlg) -> bool {
126    let bytes = word.as_encoded_bytes();
127    let Some(at) = bytes.iter().position(|byte| *byte == b'=').filter(|at| *at > 0) else { return false };
128    let assigned = arguments
129        .iter()
130        .find(|argument| matches!(&argument.source, SourceInfo::Assigned { name } if name.as_bytes() == &bytes[..at]));
131    match assigned {
132        Some(argument) => {
133            syntax.value(argument, os_string(&bytes[at + 1..]));
134            true
135        }
136        None => false,
137    }
138}
139
140/// Reads the next word, with the value word an option takes after it, answering what it was, or
141/// nothing at the end of the words.
142pub(crate) fn read_word(
143    arguments: &[ArgumentInfo],
144    conventions: Conventions,
145    cursor: &mut Cursor<'_>,
146    syntax: &mut impl CommandLineAlg,
147) -> Result<Option<Read>, ParseError> {
148    let word_at = cursor.at();
149    let Some(word) = cursor.bump() else { return Ok(None) };
150    let bytes = word.as_encoded_bytes();
151    if bytes == b"--" && conventions.double_dash_ends_options {
152        syntax.end_of_options();
153        return Ok(Some(Read::EndOfOptions));
154    }
155    if bytes.len() < 2 || bytes[0] != b'-' || bytes == b"--" {
156        // An assigning operand takes no positional place, and so ends no options.
157        if assign(arguments, word, syntax) {
158            return Ok(Some(Read::Options));
159        }
160        syntax.operand(word, word_at);
161        return Ok(Some(Read::Operand));
162    }
163    let mut options = Vec::new();
164    let read = if bytes.starts_with(b"--") {
165        long(arguments, bytes, &mut options)
166    } else if let Some(numeric) = conventions.numeric_option.filter(|_| bytes[1..].iter().all(u8::is_ascii_digit)) {
167        // `-5` is the numeric option given `5`, as `head -5` is `head -n 5`.
168        let argument = arguments
169            .iter()
170            .find(|argument| matches!(&argument.source, SourceInfo::Named { long, .. } if long == numeric));
171        match argument {
172            Some(argument) => {
173                options.push((argument, Given::Attached(os_string(&bytes[1..]))));
174                Ok(())
175            }
176            None => Err(Unread { byte: 0, kind: ParseErrorKind::Unknown(word.to_string_lossy().into_owned()) }),
177        }
178    } else {
179        short(arguments, bytes, &mut options)
180    };
181    match read {
182        Err(Unread { kind: ParseErrorKind::Unknown(_), .. }) if conventions.unknown_options_are_operands => {
183            // A word spelling no option of the command is its operand.
184            syntax.operand(word, word_at);
185            return Ok(Some(Read::Operand));
186        }
187        Err(Unread { byte, kind }) => return Err(ParseError { at: Span { word: word_at, byte }, kind }),
188        Ok(()) => {}
189    }
190    for (argument, value) in options {
191        match value {
192            Given::Switch => syntax.switch(argument),
193            Given::Attached(value) => syntax.value(argument, value),
194            Given::Next(spelling) => {
195                let at = Span { word: cursor.at(), byte: 0 };
196                let value = cursor.bump().ok_or(ParseError { at, kind: ParseErrorKind::MissingValue(spelling) })?;
197                syntax.value(argument, value.clone());
198            }
199        }
200    }
201
202    Ok(Some(Read::Options))
203}
204
205/// How an option in a word is given.
206enum Given {
207    /// By its spelling alone: a switch, or an option whose value is optional, given none.
208    Switch,
209    Attached(OsString),
210    /// Its value is the next word; the option is named by its spelling, should there be none.
211    Next(String),
212}
213
214/// What is wrong at a byte of the word being read.
215struct Unread {
216    byte: usize,
217    kind: ParseErrorKind,
218}
219
220/// Reads `--long` or `--long=value`.
221fn long<'a>(
222    arguments: &'a [ArgumentInfo],
223    bytes: &[u8],
224    options: &mut Vec<(&'a ArgumentInfo, Given)>,
225) -> Result<(), Unread> {
226    let (spelling, value) = match bytes.iter().position(|byte| *byte == b'=') {
227        Some(at) => (&bytes[2..at], Some(os_string(&bytes[at + 1..]))),
228        None => (&bytes[2..], None),
229    };
230    // Spellings are ASCII, so only the value can be any operating system string.
231    let spelled = format!("--{}", String::from_utf8_lossy(spelling));
232    let argument = arguments
233        .iter()
234        .find(|argument| matches!(&argument.source, SourceInfo::Named { long, .. } if long.as_bytes() == spelling))
235        .ok_or_else(|| Unread { byte: 0, kind: ParseErrorKind::Unknown(spelled.clone()) })?;
236    let given = match (argument.arity, value) {
237        (Arity::Presence | Arity::OptionalValue, None) => Given::Switch,
238        // An alternative of a sum is chosen by its spelling; any other switch may state a truth.
239        (Arity::Presence, Some(_)) if matches!(argument.part_of, Some(Part::Sum(_))) => {
240            return Err(Unread { byte: 0, kind: ParseErrorKind::SwitchValue(spelled) });
241        }
242        (_, Some(value)) => Given::Attached(value),
243        (_, None) => Given::Next(spelled),
244    };
245    options.push((argument, given));
246
247    Ok(())
248}
249
250/// Reads a cluster of short options as POSIX `getopt` does: `-s`, switches clustered as `-abc`,
251/// and a letter that takes a value, which takes the rest of the word (`-d:`, `-n5`, `-sd:`) or,
252/// when nothing follows it, the next word. `=` is no separator here, so `-d=:` gives `=:`.
253fn short<'a>(
254    arguments: &'a [ArgumentInfo],
255    bytes: &[u8],
256    options: &mut Vec<(&'a ArgumentInfo, Given)>,
257) -> Result<(), Unread> {
258    for (byte, letter) in bytes.iter().enumerate().skip(1) {
259        // Spellings are ASCII, so a letter is one byte; the value after it can be any bytes.
260        let letter = char::from(*letter);
261        let argument = arguments
262            .iter()
263            .find(|argument| matches!(&argument.source, SourceInfo::Named { short, short_aliases, .. } if *short == Some(letter) || short_aliases.contains(&letter)))
264            .ok_or_else(|| Unread { byte, kind: ParseErrorKind::Unknown(format!("-{letter}")) })?;
265        if argument.arity == Arity::Presence {
266            options.push((argument, Given::Switch));
267            continue;
268        }
269        let rest = &bytes[byte + 1..];
270        let given = match (rest.is_empty(), argument.arity) {
271            // An optional value is only ever written in the option's own word: `-i` or `-i.bak`.
272            (true, Arity::OptionalValue) => Given::Switch,
273            (true, _) => Given::Next(format!("-{letter}")),
274            (false, _) => Given::Attached(os_string(rest)),
275        };
276        options.push((argument, given));
277        break;
278    }
279
280    Ok(())
281}
282
283/// Prints what words say as a canonical command line: options by their long spelling, each value
284/// its own word, and the operands after `--` where it ends the options.
285///
286/// It witnesses the reading law in tests; no command line needs printing at run time.
287#[cfg(test)]
288pub(crate) struct Printed {
289    conventions: Conventions,
290    options: Vec<OsString>,
291    operands: Vec<OsString>,
292}
293
294#[cfg(test)]
295impl Printed {
296    pub(crate) fn new(conventions: Conventions) -> Self {
297        Self { conventions, options: Vec::new(), operands: Vec::new() }
298    }
299
300    /// The canonical words.
301    pub(crate) fn words(mut self) -> Vec<OsString> {
302        let protect =
303            !self.operands.is_empty() && self.conventions.double_dash_ends_options && !self.conventions.verbatim;
304        if protect {
305            self.options.push("--".into());
306        }
307        self.options.extend(self.operands);
308        self.options
309    }
310
311    fn spelling(argument: &ArgumentInfo) -> OsString {
312        match &argument.source {
313            SourceInfo::Named { long, .. } => format!("--{long}").into(),
314            SourceInfo::Positional { .. } | SourceInfo::Assigned { .. } => OsString::new(),
315        }
316    }
317}
318
319#[cfg(test)]
320impl CommandLineAlg for Printed {
321    fn switch(&mut self, argument: &ArgumentInfo) {
322        self.options.push(Self::spelling(argument));
323    }
324
325    fn value(&mut self, argument: &ArgumentInfo, value: OsString) {
326        if let SourceInfo::Assigned { name } = &argument.source {
327            let mut assigned = OsString::from(format!("{name}="));
328            assigned.push(value);
329            self.options.push(assigned);
330            return;
331        }
332        let mut spelling = Self::spelling(argument);
333        // An optional value, and a switch's truth, is only read from the option's own word.
334        if matches!(argument.arity, Arity::OptionalValue | Arity::Presence) {
335            spelling.push("=");
336            spelling.push(value);
337            self.options.push(spelling);
338            return;
339        }
340        self.options.push(spelling);
341        self.options.push(value);
342    }
343
344    fn operand(&mut self, word: &OsStr, _: usize) {
345        self.operands.push(word.to_os_string());
346    }
347}
348
349/// Ignores what words say, for a reader that needs only how many words an option takes.
350pub(crate) struct Skipped;
351
352impl CommandLineAlg for Skipped {
353    fn switch(&mut self, _: &ArgumentInfo) {}
354
355    fn value(&mut self, _: &ArgumentInfo, _: OsString) {}
356
357    fn operand(&mut self, _: &OsStr, _: usize) {}
358}
359
360/// Rebuilds the operating system string an option value's bytes came from.
361#[cfg(unix)]
362pub(crate) fn os_string(bytes: &[u8]) -> OsString {
363    use std::os::unix::ffi::OsStrExt;
364    OsStr::from_bytes(bytes).to_os_string()
365}
366
367/// Rebuilds an option value; off Unix only its text is kept.
368#[cfg(not(unix))]
369pub(crate) fn os_string(bytes: &[u8]) -> OsString {
370    OsString::from(String::from_utf8_lossy(bytes).into_owned())
371}
372
373#[cfg(test)]
374mod tests {
375    use super::*;
376    use crate::Parsed;
377    use alux_cli::Fallback;
378
379    fn argument(source: SourceInfo, arity: Arity) -> ArgumentInfo {
380        ArgumentInfo {
381            name: "argument",
382            source,
383            fallback: Fallback::default(),
384            arity,
385            doc: "",
386            part_of: None,
387            delimiter: None,
388        }
389    }
390
391    fn named(long: &str, short: char, arity: Arity) -> ArgumentInfo {
392        argument(SourceInfo::Named { long: long.into(), short: Some(short), short_aliases: &[] }, arity)
393    }
394
395    fn words(line: &str) -> Vec<OsString> {
396        line.split_whitespace().map(OsString::from).collect()
397    }
398
399    /// How many words the first option takes, or nothing when the first word is no option.
400    fn taken(arguments: &[ArgumentInfo], line: &str) -> Option<usize> {
401        let words = words(line);
402        let mut cursor = Cursor::new(&words);
403        let read = read_word(arguments, Conventions::default(), &mut cursor, &mut Skipped).ok()??;
404        (read == Read::Options).then(|| cursor.at())
405    }
406
407    #[test]
408    fn takes_the_next_word_only_for_an_option_with_no_value_in_its_word() {
409        let context = [named("verbose", 'v', Arity::Presence), named("store", 's', Arity::One)];
410        assert_eq!(taken(&context, "--verbose x"), Some(1));
411        assert_eq!(taken(&context, "--store work"), Some(2));
412        assert_eq!(taken(&context, "--store=work x"), Some(1));
413        assert_eq!(taken(&context, "-s work"), Some(2));
414        assert_eq!(taken(&context, "-vs work"), Some(2));
415        assert_eq!(taken(&context, "-vv x"), Some(1));
416        // The first letter that takes a value takes the rest of the word, as in `getopt`.
417        assert_eq!(taken(&context, "-sv x"), Some(1));
418        assert_eq!(taken(&context, "-vswork x"), Some(1));
419        assert_eq!(taken(&context, "-vx"), None);
420        assert_eq!(taken(&context, "--nope"), None);
421        assert_eq!(taken(&context, "list"), None);
422    }
423
424    #[test]
425    fn reads_an_optional_value_only_from_the_option_s_own_word() {
426        let arguments =
427            [named("in-place", 'i', Arity::OptionalValue), argument(SourceInfo::Positional { index: 0 }, Arity::Many)];
428        let parsed = |line: &str| Parsed::new(&arguments, &words(line), Conventions::default()).unwrap();
429        let expected = |given: &[&str], operands: &str| {
430            let mut printed =
431                given.iter().map(|given| OsString::from(format!("--in-place={given}"))).collect::<Vec<_>>();
432            printed.push("--".into());
433            printed.extend(words(operands));
434            Parsed::new(&arguments, &printed, Conventions::default()).unwrap()
435        };
436        assert_eq!(parsed("-i a"), expected(&[""], "a"));
437        assert_eq!(parsed("-i.bak a"), expected(&[".bak"], "a"));
438        assert_eq!(parsed("--in-place a"), expected(&[""], "a"));
439        assert_eq!(parsed("--in-place=.bak a"), expected(&[".bak"], "a"));
440    }
441
442    #[test]
443    fn reads_a_dash_and_digits_as_the_numeric_option() {
444        let arguments = [named("lines", 'n', Arity::One), named("verbose", 'v', Arity::Presence)];
445        let numeric = Conventions { numeric_option: Some("lines"), ..Conventions::default() };
446        let parsed = |line: &str, conventions| Parsed::new(&arguments, &words(line), conventions);
447        assert_eq!(parsed("-5", numeric), parsed("-n 5", numeric));
448        assert_eq!(parsed("-v -20", numeric), parsed("-v --lines=20", numeric));
449        // Without the convention, `-5` names no option.
450        assert_eq!(parsed("-5", Conventions::default()).unwrap_err().kind, ParseErrorKind::Unknown("-5".into()));
451    }
452
453    #[test]
454    fn places_an_error_at_its_word_and_byte() {
455        let context = [named("verbose", 'v', Arity::Presence), named("store", 's', Arity::One)];
456        let error = |line: &str| Parsed::new(&context, &words(line), Conventions::default()).unwrap_err();
457        assert_eq!(error("-v -vx").at, Span { word: 1, byte: 2 });
458        assert_eq!(error("-v -s").at, Span { word: 2, byte: 0 });
459        assert_eq!(error("-v a").at, Span { word: 1, byte: 0 });
460    }
461
462    /// Reading the canonical printing of what words say says the same.
463    #[test]
464    fn reads_its_own_printing_as_what_was_read() {
465        let arguments = [
466            named("verbose", 'v', Arity::Presence),
467            named("delimiter", 'd', Arity::One),
468            named("tag", 't', Arity::Many),
469            named("in-place", 'i', Arity::OptionalValue),
470            named("lines", 'n', Arity::One),
471            argument(SourceInfo::Assigned { name: "if".into() }, Arity::Many),
472            argument(SourceInfo::Positional { index: 0 }, Arity::Many),
473        ];
474        let lines = [
475            "-d: a b",
476            "-d : -- -a",
477            "-d=: -vt x -ty a",
478            "--delimiter=, --tag t -- --verbose",
479            "-vd -x -- -- b",
480            "a -v b --tag=-c",
481            "-i a -i.bak -vi.x --in-place --in-place=y",
482            "-5 a -n 3 -12",
483            "if=x a k=v if= -v -- if=a=b -i",
484        ];
485        for conventions in [
486            Conventions::default(),
487            Conventions { options_first: true, ..Conventions::default() },
488            Conventions { unknown_options_are_operands: true, ..Conventions::default() },
489            Conventions { double_dash_ends_options: false, ..Conventions::default() },
490            Conventions { numeric_option: Some("lines"), ..Conventions::default() },
491        ] {
492            for line in lines {
493                let Ok(parsed) = Parsed::new(&arguments, &words(line), conventions) else { continue };
494                let mut printed = Printed::new(conventions);
495                read(&arguments, &words(line), conventions, &mut printed).unwrap();
496                let printed = printed.words();
497                assert_eq!(Parsed::new(&arguments, &printed, conventions), Ok(parsed), "{line} printed as {printed:?}");
498            }
499        }
500    }
501}