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, 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        (Arity::Presence, Some(_)) => return Err(Unread { byte: 0, kind: ParseErrorKind::SwitchValue(spelled) }),
239        (_, Some(value)) => Given::Attached(value),
240        (_, None) => Given::Next(spelled),
241    };
242    options.push((argument, given));
243
244    Ok(())
245}
246
247/// Reads a cluster of short options as POSIX `getopt` does: `-s`, switches clustered as `-abc`,
248/// and a letter that takes a value, which takes the rest of the word (`-d:`, `-n5`, `-sd:`) or,
249/// when nothing follows it, the next word. `=` is no separator here, so `-d=:` gives `=:`.
250fn short<'a>(
251    arguments: &'a [ArgumentInfo],
252    bytes: &[u8],
253    options: &mut Vec<(&'a ArgumentInfo, Given)>,
254) -> Result<(), Unread> {
255    for (byte, letter) in bytes.iter().enumerate().skip(1) {
256        // Spellings are ASCII, so a letter is one byte; the value after it can be any bytes.
257        let letter = char::from(*letter);
258        let argument = arguments
259            .iter()
260            .find(|argument| matches!(&argument.source, SourceInfo::Named { short, short_aliases, .. } if *short == Some(letter) || short_aliases.contains(&letter)))
261            .ok_or_else(|| Unread { byte, kind: ParseErrorKind::Unknown(format!("-{letter}")) })?;
262        if argument.arity == Arity::Presence {
263            options.push((argument, Given::Switch));
264            continue;
265        }
266        let rest = &bytes[byte + 1..];
267        let given = match (rest.is_empty(), argument.arity) {
268            // An optional value is only ever written in the option's own word: `-i` or `-i.bak`.
269            (true, Arity::OptionalValue) => Given::Switch,
270            (true, _) => Given::Next(format!("-{letter}")),
271            (false, _) => Given::Attached(os_string(rest)),
272        };
273        options.push((argument, given));
274        break;
275    }
276
277    Ok(())
278}
279
280/// Prints what words say as a canonical command line: options by their long spelling, each value
281/// its own word, and the operands after `--` where it ends the options.
282///
283/// It witnesses the reading law in tests; no command line needs printing at run time.
284#[cfg(test)]
285pub(crate) struct Printed {
286    conventions: Conventions,
287    options: Vec<OsString>,
288    operands: Vec<OsString>,
289}
290
291#[cfg(test)]
292impl Printed {
293    pub(crate) fn new(conventions: Conventions) -> Self {
294        Self { conventions, options: Vec::new(), operands: Vec::new() }
295    }
296
297    /// The canonical words.
298    pub(crate) fn words(mut self) -> Vec<OsString> {
299        let protect =
300            !self.operands.is_empty() && self.conventions.double_dash_ends_options && !self.conventions.verbatim;
301        if protect {
302            self.options.push("--".into());
303        }
304        self.options.extend(self.operands);
305        self.options
306    }
307
308    fn spelling(argument: &ArgumentInfo) -> OsString {
309        match &argument.source {
310            SourceInfo::Named { long, .. } => format!("--{long}").into(),
311            SourceInfo::Positional { .. } | SourceInfo::Assigned { .. } => OsString::new(),
312        }
313    }
314}
315
316#[cfg(test)]
317impl CommandLineAlg for Printed {
318    fn switch(&mut self, argument: &ArgumentInfo) {
319        self.options.push(Self::spelling(argument));
320    }
321
322    fn value(&mut self, argument: &ArgumentInfo, value: OsString) {
323        if let SourceInfo::Assigned { name } = &argument.source {
324            let mut assigned = OsString::from(format!("{name}="));
325            assigned.push(value);
326            self.options.push(assigned);
327            return;
328        }
329        let mut spelling = Self::spelling(argument);
330        // An optional value is only read from the option's own word.
331        if argument.arity == Arity::OptionalValue {
332            spelling.push("=");
333            spelling.push(value);
334            self.options.push(spelling);
335            return;
336        }
337        self.options.push(spelling);
338        self.options.push(value);
339    }
340
341    fn operand(&mut self, word: &OsStr, _: usize) {
342        self.operands.push(word.to_os_string());
343    }
344}
345
346/// Ignores what words say, for a reader that needs only how many words an option takes.
347pub(crate) struct Skipped;
348
349impl CommandLineAlg for Skipped {
350    fn switch(&mut self, _: &ArgumentInfo) {}
351
352    fn value(&mut self, _: &ArgumentInfo, _: OsString) {}
353
354    fn operand(&mut self, _: &OsStr, _: usize) {}
355}
356
357/// Rebuilds the operating system string an option value's bytes came from.
358#[cfg(unix)]
359pub(crate) fn os_string(bytes: &[u8]) -> OsString {
360    use std::os::unix::ffi::OsStrExt;
361    OsStr::from_bytes(bytes).to_os_string()
362}
363
364/// Rebuilds an option value; off Unix only its text is kept.
365#[cfg(not(unix))]
366pub(crate) fn os_string(bytes: &[u8]) -> OsString {
367    OsString::from(String::from_utf8_lossy(bytes).into_owned())
368}
369
370#[cfg(test)]
371mod tests {
372    use super::*;
373    use crate::Parsed;
374    use alux_cli::Fallback;
375
376    fn argument(source: SourceInfo, arity: Arity) -> ArgumentInfo {
377        ArgumentInfo {
378            name: "argument",
379            source,
380            fallback: Fallback::default(),
381            arity,
382            doc: "",
383            part_of: None,
384            delimiter: None,
385        }
386    }
387
388    fn named(long: &str, short: char, arity: Arity) -> ArgumentInfo {
389        argument(SourceInfo::Named { long: long.into(), short: Some(short), short_aliases: &[] }, arity)
390    }
391
392    fn words(line: &str) -> Vec<OsString> {
393        line.split_whitespace().map(OsString::from).collect()
394    }
395
396    /// How many words the first option takes, or nothing when the first word is no option.
397    fn taken(arguments: &[ArgumentInfo], line: &str) -> Option<usize> {
398        let words = words(line);
399        let mut cursor = Cursor::new(&words);
400        let read = read_word(arguments, Conventions::default(), &mut cursor, &mut Skipped).ok()??;
401        (read == Read::Options).then(|| cursor.at())
402    }
403
404    #[test]
405    fn takes_the_next_word_only_for_an_option_with_no_value_in_its_word() {
406        let context = [named("verbose", 'v', Arity::Presence), named("store", 's', Arity::One)];
407        assert_eq!(taken(&context, "--verbose x"), Some(1));
408        assert_eq!(taken(&context, "--store work"), Some(2));
409        assert_eq!(taken(&context, "--store=work x"), Some(1));
410        assert_eq!(taken(&context, "-s work"), Some(2));
411        assert_eq!(taken(&context, "-vs work"), Some(2));
412        assert_eq!(taken(&context, "-vv x"), Some(1));
413        // The first letter that takes a value takes the rest of the word, as in `getopt`.
414        assert_eq!(taken(&context, "-sv x"), Some(1));
415        assert_eq!(taken(&context, "-vswork x"), Some(1));
416        assert_eq!(taken(&context, "-vx"), None);
417        assert_eq!(taken(&context, "--nope"), None);
418        assert_eq!(taken(&context, "list"), None);
419    }
420
421    #[test]
422    fn reads_an_optional_value_only_from_the_option_s_own_word() {
423        let arguments =
424            [named("in-place", 'i', Arity::OptionalValue), argument(SourceInfo::Positional { index: 0 }, Arity::Many)];
425        let parsed = |line: &str| Parsed::new(&arguments, &words(line), Conventions::default()).unwrap();
426        let expected = |given: &[&str], operands: &str| {
427            let mut printed =
428                given.iter().map(|given| OsString::from(format!("--in-place={given}"))).collect::<Vec<_>>();
429            printed.push("--".into());
430            printed.extend(words(operands));
431            Parsed::new(&arguments, &printed, Conventions::default()).unwrap()
432        };
433        assert_eq!(parsed("-i a"), expected(&[""], "a"));
434        assert_eq!(parsed("-i.bak a"), expected(&[".bak"], "a"));
435        assert_eq!(parsed("--in-place a"), expected(&[""], "a"));
436        assert_eq!(parsed("--in-place=.bak a"), expected(&[".bak"], "a"));
437    }
438
439    #[test]
440    fn reads_a_dash_and_digits_as_the_numeric_option() {
441        let arguments = [named("lines", 'n', Arity::One), named("verbose", 'v', Arity::Presence)];
442        let numeric = Conventions { numeric_option: Some("lines"), ..Conventions::default() };
443        let parsed = |line: &str, conventions| Parsed::new(&arguments, &words(line), conventions);
444        assert_eq!(parsed("-5", numeric), parsed("-n 5", numeric));
445        assert_eq!(parsed("-v -20", numeric), parsed("-v --lines=20", numeric));
446        // Without the convention, `-5` names no option.
447        assert_eq!(parsed("-5", Conventions::default()).unwrap_err().kind, ParseErrorKind::Unknown("-5".into()));
448    }
449
450    #[test]
451    fn places_an_error_at_its_word_and_byte() {
452        let context = [named("verbose", 'v', Arity::Presence), named("store", 's', Arity::One)];
453        let error = |line: &str| Parsed::new(&context, &words(line), Conventions::default()).unwrap_err();
454        assert_eq!(error("-v -vx").at, Span { word: 1, byte: 2 });
455        assert_eq!(error("-v -s").at, Span { word: 2, byte: 0 });
456        assert_eq!(error("-v a").at, Span { word: 1, byte: 0 });
457    }
458
459    /// Reading the canonical printing of what words say says the same.
460    #[test]
461    fn reads_its_own_printing_as_what_was_read() {
462        let arguments = [
463            named("verbose", 'v', Arity::Presence),
464            named("delimiter", 'd', Arity::One),
465            named("tag", 't', Arity::Many),
466            named("in-place", 'i', Arity::OptionalValue),
467            named("lines", 'n', Arity::One),
468            argument(SourceInfo::Assigned { name: "if".into() }, Arity::Many),
469            argument(SourceInfo::Positional { index: 0 }, Arity::Many),
470        ];
471        let lines = [
472            "-d: a b",
473            "-d : -- -a",
474            "-d=: -vt x -ty a",
475            "--delimiter=, --tag t -- --verbose",
476            "-vd -x -- -- b",
477            "a -v b --tag=-c",
478            "-i a -i.bak -vi.x --in-place --in-place=y",
479            "-5 a -n 3 -12",
480            "if=x a k=v if= -v -- if=a=b -i",
481        ];
482        for conventions in [
483            Conventions::default(),
484            Conventions { options_first: true, ..Conventions::default() },
485            Conventions { unknown_options_are_operands: true, ..Conventions::default() },
486            Conventions { double_dash_ends_options: false, ..Conventions::default() },
487            Conventions { numeric_option: Some("lines"), ..Conventions::default() },
488        ] {
489            for line in lines {
490                let Ok(parsed) = Parsed::new(&arguments, &words(line), conventions) else { continue };
491                let mut printed = Printed::new(conventions);
492                read(&arguments, &words(line), conventions, &mut printed).unwrap();
493                let printed = printed.words();
494                assert_eq!(Parsed::new(&arguments, &printed, conventions), Ok(parsed), "{line} printed as {printed:?}");
495            }
496        }
497    }
498}