Skip to main content

pimalaya_cli/
repl.rs

1//! A read-eval-print loop over stdin, running a binary's own commands
2//! against what a session keeps open.
3//!
4//! A session keeps one process alive for one account, so what the
5//! account needs (a client connection, a token read off a keyring) is
6//! built once rather than once per command. [`Repl::run`] reads stdin one
7//! line at a time, splits it as a shell does, parses it with the binary's
8//! command grammar plus `--json`, and hands the command to the binary
9//! with a printer of its own.
10//!
11//! Every answer goes to stdout, failures included, so a piped session
12//! answers each line once and an application can keep one open. stderr holds
13//! the prompt, clap's rendering of a mistyped line on a terminal, and the
14//! help in a JSON session, where stdout keeps one JSON value per line.
15//! The session claims stdin ([`claim_stdin`]), so a command reading its
16//! input there is refused.
17//!
18//! [`claim_stdin`]: crate::session::claim_stdin
19
20use std::{
21    io::{self, BufRead, IsTerminal, Write},
22    str,
23};
24
25use anyhow::{Context, Error, Result, anyhow};
26use clap::{Command, CommandFactory, FromArgMatches, Parser, Subcommand};
27
28use crate::{
29    clap::args::JsonFlag,
30    error::{ErrorCode, ErrorReport, partial_outcome_of},
31    printer::{Printer, StdoutPrinter},
32    session::claim_stdin,
33};
34
35/// The flags every session fixes when it starts: the shared account,
36/// configuration and log flags.
37const FIXED: &[&str] = &[
38    "-a",
39    "--account",
40    "-c",
41    "--config",
42    "--log-level",
43    "--log",
44    "--log-file",
45];
46
47/// The text hint of a failure while debug logs are off: `--log-level` is
48/// fixed when the session starts.
49const LOG_LEVEL_HINT: &str = "Restart the session with --log-level to enable more verbose logs";
50
51/// A read-eval-print loop over stdin for one binary.
52#[derive(Clone, Debug)]
53pub struct Repl {
54    /// The binary name, which the prompt and the help carry.
55    pub bin: &'static str,
56    /// Whether the session prints JSON, as its `--json` says.
57    pub json: bool,
58    /// The flags the session fixes when it starts, spelled as a line
59    /// would (`-a`, `--account`): a line setting one is refused naming
60    /// it. A binary adds its own, as in `--backend`.
61    pub fixed: Vec<&'static str>,
62}
63
64impl Repl {
65    /// Builds the loop of the binary `bin`, printing JSON when `json` is
66    /// set, as the session's printer does, and fixing the shared account,
67    /// configuration and log flags.
68    pub fn new(bin: &'static str, json: bool) -> Self {
69        Self {
70            bin,
71            json,
72            fixed: FIXED.to_vec(),
73        }
74    }
75
76    /// Runs the loop over stdin until EOF, `quit` or `exit`.
77    ///
78    /// `T` is the binary's command tree, parsed from each line without
79    /// the binary name, and `C` its failure codes. `execute` runs one
80    /// parsed command with the printer of its line, JSON when the session
81    /// or the line asks for it. The loop claims stdin first, and fails
82    /// only when stdin or stdout does.
83    pub fn run<T: Subcommand, C: ErrorCode>(
84        &self,
85        mut execute: impl FnMut(&mut StdoutPrinter, T) -> Result<()>,
86    ) -> Result<()> {
87        claim_stdin();
88
89        let stdin = io::stdin();
90
91        let mut streams = Streams {
92            interactive: stdin.is_terminal(),
93            input: stdin.lock(),
94            stdout: io::stdout(),
95            stderr: io::stderr(),
96        };
97
98        let mut printer = |json| StdoutPrinter::new(&JsonFlag { enabled: json });
99        self.run_on::<T, C, _>(&mut streams, &mut printer, &mut execute)
100    }
101
102    /// Runs the loop over `streams`, each line printing through the
103    /// printer `printer` builds for its JSON flag.
104    fn run_on<T: Subcommand, C: ErrorCode, P: Printer>(
105        &self,
106        streams: &mut Streams<impl BufRead, impl Write, impl Write>,
107        printer: &mut impl FnMut(bool) -> P,
108        execute: &mut impl FnMut(&mut P, T) -> Result<()>,
109    ) -> Result<()> {
110        // NOTE: the flattened `--json` would lend its doc as the about.
111        let mut grammar = Line::<T>::command()
112            .name(self.bin)
113            .bin_name(self.bin)
114            .about(None)
115            .long_about(None);
116
117        let mut line = Vec::new();
118
119        loop {
120            if streams.interactive {
121                write!(streams.stderr, "{}> ", self.bin)?;
122                streams.stderr.flush()?;
123            }
124
125            line.clear();
126
127            let read = streams.input.read_until(b'\n', &mut line);
128            if read.context("Cannot read a line from stdin")? == 0 {
129                return Ok(());
130            }
131
132            match self.step::<T>(&mut grammar, &line) {
133                Step::Quit => return Ok(()),
134                Step::Skip => continue,
135                Step::Run { cmd, json } => {
136                    let mut printer = printer(json);
137                    let result = execute(&mut printer, cmd);
138                    answer::<C>(&mut printer, result)?;
139                }
140                Step::Fail { err, json } => answer::<C>(&mut printer(json), Err(err))?,
141                // Help and version are no failures, on stderr in a JSON
142                // session so stdout stays JSON.
143                Step::Clap { err, json: true } if !err.use_stderr() => {
144                    write!(streams.stderr, "{}", err.render())?
145                }
146                Step::Clap { err, json: false } if !err.use_stderr() => {
147                    write!(streams.stdout, "{}", err.render())?
148                }
149                Step::Clap { err, .. } if streams.interactive => {
150                    write!(streams.stderr, "{}", err.render())?
151                }
152                Step::Clap { err, json } => answer::<C>(&mut printer(json), Err(err.into()))?,
153            }
154
155            streams.stdout.flush()?;
156        }
157    }
158
159    /// Sorts one line read off stdin.
160    fn step<T: Subcommand>(&self, grammar: &mut Command, line: &[u8]) -> Step<T> {
161        let Ok(line) = str::from_utf8(line) else {
162            let err = anyhow!("Cannot read the line: it is not valid UTF-8");
163            return Step::Fail {
164                err,
165                json: self.json,
166            };
167        };
168
169        let Some(words) = shlex::split(line) else {
170            let err = anyhow!("Cannot split the line: a quote is not closed");
171            return Step::Fail {
172                err,
173                json: self.json,
174            };
175        };
176
177        match words.as_slice() {
178            [] => return Step::Skip,
179            [word] if word == "quit" || word == "exit" => return Step::Quit,
180            _ => (),
181        }
182
183        // The words before any `--` are flags: clap stops at help or at an
184        // error before telling whether `--json` is set.
185        let flags = words.iter().take_while(|word| *word != "--");
186        let json = self.json || flags.clone().any(|word| word == "--json");
187
188        let parsed = grammar
189            .try_get_matches_from_mut(&words)
190            .and_then(|matches| {
191                Line::<T>::from_arg_matches(&matches).map_err(|err| err.format(grammar))
192            });
193
194        let err = match parsed {
195            Ok(line) => {
196                let json = self.json || line.json.enabled;
197                return Step::Run {
198                    cmd: line.cmd,
199                    json,
200                };
201            }
202            Err(err) => err,
203        };
204
205        if !err.use_stderr() {
206            return Step::Clap { err, json };
207        }
208
209        let fixed = flags.into_iter().find_map(|word| {
210            self.fixed.iter().copied().find(|flag| {
211                if flag.starts_with("--") {
212                    let value = word.strip_prefix(flag);
213                    value.is_some_and(|value| value.is_empty() || value.starts_with('='))
214                } else {
215                    // A short flag, its value attached or not.
216                    !word.starts_with("--") && word.starts_with(flag)
217                }
218            })
219        });
220
221        match fixed {
222            Some(flag) => {
223                let err = anyhow!(
224                    "Cannot set `{flag}` inside a session, start a new session with it instead"
225                );
226                Step::Fail { err, json }
227            }
228            None => Step::Clap { err, json },
229        }
230    }
231}
232
233/// The words of one line: the binary's command tree and the line's own
234/// `--json`.
235#[derive(Debug, Parser)]
236#[command(no_binary_name = true, infer_subcommands = true)]
237struct Line<T: Subcommand> {
238    #[command(subcommand)]
239    cmd: T,
240    #[command(flatten)]
241    json: JsonFlag,
242}
243
244/// Where the loop reads its lines and writes what no printer does.
245struct Streams<I, O, E> {
246    input: I,
247    stdout: O,
248    stderr: E,
249    /// Whether a person types the lines: the prompt renders, and a
250    /// mistyped line gets clap's rendering on stderr.
251    interactive: bool,
252}
253
254/// What one line asks of the loop.
255enum Step<T> {
256    /// End the session.
257    Quit,
258    /// Read the next line: a blank or comment line.
259    Skip,
260    /// Run the command, printing JSON or not.
261    Run { cmd: T, json: bool },
262    /// Print the failure object, as JSON or not.
263    Fail { err: Error, json: bool },
264    /// Answer clap's verdict, help or version or a parse error, in a JSON
265    /// session or not.
266    Clap { err: clap::Error, json: bool },
267}
268
269/// Prints how a command ended: nothing more after its result or a
270/// partial outcome, the failure object after a failure.
271fn answer<C: ErrorCode>(printer: &mut impl Printer, result: Result<()>) -> Result<()> {
272    match result {
273        Err(err) if partial_outcome_of(&err).is_none() => {
274            let mut report = ErrorReport::<C>::from(err);
275            report.log_level_hint = LOG_LEVEL_HINT;
276            printer.out(report)
277        }
278        _ => Ok(()),
279    }
280}
281
282#[cfg(test)]
283mod tests {
284    use std::{
285        cell::RefCell,
286        fmt,
287        io::{self, Write},
288        rc::Rc,
289    };
290
291    use anyhow::{Result, bail};
292    use clap::Subcommand;
293    use serde::Serialize;
294    use serde_json::{Value, json};
295
296    use crate::{
297        error::{NoErrorCode, PartialOutcome},
298        output::Bytes,
299        printer::Printer,
300        repl::{Repl, Streams},
301    };
302
303    /// A stream shared between the loop and the printers.
304    #[derive(Clone, Default)]
305    struct Sink(Rc<RefCell<Vec<u8>>>);
306
307    impl Sink {
308        fn text(&self) -> String {
309            String::from_utf8(self.0.borrow().clone()).unwrap()
310        }
311    }
312
313    impl Write for Sink {
314        fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
315            self.0.borrow_mut().extend_from_slice(buf);
316            Ok(buf.len())
317        }
318
319        fn flush(&mut self) -> io::Result<()> {
320            Ok(())
321        }
322    }
323
324    /// A printer writing to a [`Sink`] the way the stdout one writes to
325    /// a pipe.
326    struct SinkPrinter {
327        sink: Sink,
328        json: bool,
329    }
330
331    impl Printer for SinkPrinter {
332        fn out<T: fmt::Display + Serialize>(&mut self, data: T) -> Result<()> {
333            if self.json {
334                serde_json::to_writer(&mut self.sink, &data)?;
335                writeln!(self.sink)?;
336            } else {
337                write!(self.sink, "{data}")?;
338            }
339
340            Ok(())
341        }
342
343        fn event<T: fmt::Display + Serialize>(&mut self, event: T) -> Result<()> {
344            self.out(event)
345        }
346
347        fn out_bytes(&mut self, bytes: Bytes) -> Result<()> {
348            self.out(bytes)
349        }
350
351        fn is_json(&self) -> bool {
352            self.json
353        }
354    }
355
356    #[derive(Debug, Subcommand)]
357    enum TestCommand {
358        /// Print a word.
359        Echo { word: String },
360        /// Fail.
361        Fail,
362        /// Print a word, then end with a partial outcome.
363        Partial,
364    }
365
366    #[derive(Serialize)]
367    struct Word {
368        word: String,
369    }
370
371    impl fmt::Display for Word {
372        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
373            writeln!(f, "{}", self.word)
374        }
375    }
376
377    fn word(printer: &mut SinkPrinter, word: &str) -> Result<()> {
378        printer.out(Word {
379            word: word.to_owned(),
380        })
381    }
382
383    /// Runs a session over `input`, answering its stdout and stderr.
384    fn session(json: bool, interactive: bool, input: &[u8]) -> (String, String) {
385        let mut repl = Repl::new("app", json);
386        repl.fixed.extend(["-b", "--backend"]);
387        let stdout = Sink::default();
388        let stderr = Sink::default();
389
390        let mut streams = Streams {
391            input,
392            stdout: stdout.clone(),
393            stderr: stderr.clone(),
394            interactive,
395        };
396
397        let mut printer = |json| SinkPrinter {
398            sink: stdout.clone(),
399            json,
400        };
401
402        let mut execute = |printer: &mut SinkPrinter, cmd| match cmd {
403            TestCommand::Echo { word: w } => word(printer, &w),
404            TestCommand::Fail => bail!("Boom"),
405            TestCommand::Partial => {
406                word(printer, "half")?;
407                Err(PartialOutcome::default().into())
408            }
409        };
410
411        repl.run_on::<TestCommand, NoErrorCode, _>(&mut streams, &mut printer, &mut execute)
412            .unwrap();
413
414        (stdout.text(), stderr.text())
415    }
416
417    /// The JSON values of a piped JSON session's stdout.
418    fn values(stdout: &str) -> Vec<Value> {
419        stdout
420            .lines()
421            .map(|line| serde_json::from_str(line).unwrap_or_else(|err| panic!("{err}: {line}")))
422            .collect()
423    }
424
425    fn error(value: &Value) -> &str {
426        value["error"].as_str().unwrap_or_default()
427    }
428
429    #[test]
430    fn lines_are_split_as_a_shell_splits_them() {
431        let input = b"echo \"a b\"\necho 'c\nec d\\ e\n";
432        let (stdout, stderr) = session(true, false, input);
433        let values = values(&stdout);
434
435        assert_eq!(values.len(), 3, "{stdout}");
436        assert_eq!(values[0], json!({ "word": "a b" }));
437        assert_eq!(
438            error(&values[1]),
439            "Cannot split the line: a quote is not closed"
440        );
441        assert_eq!(values[2], json!({ "word": "d e" }));
442        assert_eq!(stderr, "");
443    }
444
445    #[test]
446    fn blank_and_comment_lines_are_skipped() {
447        let input = b"\n   \n# echo a\necho b # c\n";
448        let (stdout, _) = session(true, false, input);
449
450        assert_eq!(values(&stdout), [json!({ "word": "b" })]);
451    }
452
453    #[test]
454    fn quit_exit_and_eof_end_the_session() {
455        for input in [&b"echo a\nquit\necho b\n"[..], b"echo a\n exit \necho b\n"] {
456            let (stdout, _) = session(false, false, input);
457            assert_eq!(stdout, "a\n");
458        }
459
460        let (stdout, _) = session(false, false, b"echo a\necho b");
461        assert_eq!(stdout, "a\nb\n");
462    }
463
464    #[test]
465    fn a_line_that_is_not_utf8_fails_alone() {
466        let (stdout, _) = session(true, false, b"echo \xff\necho a\n");
467        let values = values(&stdout);
468
469        assert_eq!(values.len(), 2, "{stdout}");
470        assert_eq!(
471            error(&values[0]),
472            "Cannot read the line: it is not valid UTF-8"
473        );
474        assert_eq!(values[1], json!({ "word": "a" }));
475    }
476
477    #[test]
478    fn a_session_flag_is_refused_by_name() {
479        let input =
480            b"echo a -a work\necho a --config=x.toml\necho -bimap a\necho -- -a\necho a --nope\n";
481        let (stdout, _) = session(true, false, input);
482        let values = values(&stdout);
483
484        assert_eq!(values.len(), 5, "{stdout}");
485
486        for (value, flag) in values.iter().zip(["-a", "--config", "-b"]) {
487            let message = format!(
488                "Cannot set `{flag}` inside a session, start a new session with it instead"
489            );
490            assert_eq!(error(value), message);
491        }
492
493        assert_eq!(values[3], json!({ "word": "-a" }));
494        assert!(!error(&values[4]).contains("Cannot set"), "{stdout}");
495    }
496
497    #[test]
498    fn help_goes_to_stderr_in_a_json_session() {
499        let (stdout, stderr) = session(true, false, b"help\necho --json --help\n");
500        assert_eq!(stdout, "");
501        assert!(stderr.starts_with("Usage:"), "{stderr}");
502        assert!(stderr.contains("  echo     Print a word\n"), "{stderr}");
503        assert!(stderr.contains("\nPrint a word\n"), "{stderr}");
504
505        let (stdout, stderr) = session(false, false, b"help\n");
506        assert!(stdout.contains("  echo     Print a word\n"), "{stdout}");
507        assert_eq!(stderr, "");
508    }
509
510    #[test]
511    fn a_line_json_flag_applies_to_that_line_and_nothing_is_added() {
512        let (stdout, _) = session(false, false, b"echo a --json\necho b\nfail --json\n");
513        let mut lines = stdout.lines();
514
515        assert_eq!(lines.next(), Some(r#"{"word":"a"}"#));
516        assert_eq!(lines.next(), Some("b"));
517        assert_eq!(
518            error(&serde_json::from_str(lines.next().unwrap()).unwrap()),
519            "Boom"
520        );
521        assert_eq!(lines.next(), None);
522        assert!(stdout.starts_with("{\"word\":\"a\"}\nb\n{"), "{stdout}");
523    }
524
525    #[test]
526    fn a_partial_outcome_prints_its_result_alone() {
527        let (stdout, _) = session(true, false, b"partial\necho a\n");
528        assert_eq!(
529            values(&stdout),
530            [json!({ "word": "half" }), json!({ "word": "a" })]
531        );
532    }
533
534    #[test]
535    fn a_failure_prints_on_stdout_even_on_a_terminal() {
536        let (stdout, stderr) = session(false, true, b"fail\n");
537
538        assert!(stdout.starts_with("Error: Boom\n"), "{stdout}");
539        assert_eq!(stderr, "app> app> ");
540    }
541
542    #[test]
543    fn a_failure_hints_at_restarting_the_session_for_logs() {
544        let (stdout, _) = session(false, false, b"fail\n");
545        let hint = "\n - Restart the session with --log-level to enable more verbose logs\n";
546        assert!(stdout.ends_with(hint), "{stdout}");
547    }
548
549    #[test]
550    fn a_command_help_names_the_binary_in_its_usage() {
551        let (stdout, _) = session(false, false, b"help echo\necho --help\n");
552        let usage: Vec<&str> = stdout
553            .lines()
554            .filter(|line| line.starts_with("Usage:"))
555            .collect();
556
557        assert_eq!(usage, ["Usage: app echo [OPTIONS] <WORD>"; 2], "{stdout}");
558    }
559
560    #[test]
561    fn a_parse_error_goes_to_clap_on_a_terminal_and_to_stdout_when_piped() {
562        let (stdout, stderr) = session(true, true, b"frobnicate\n");
563        assert_eq!(stdout, "");
564        assert!(
565            stderr.contains("error: unrecognized subcommand"),
566            "{stderr}"
567        );
568
569        let (stdout, stderr) = session(true, false, b"frobnicate\n");
570        let values = values(&stdout);
571        assert_eq!(values.len(), 1, "{stdout}");
572        assert!(
573            error(&values[0]).contains("unrecognized subcommand"),
574            "{stdout}"
575        );
576        assert_eq!(stderr, "");
577    }
578}