Skip to main content

alux_cli/
outcome.rs

1use core::{convert::Infallible, num::NonZeroU8};
2
3/// Names the exit status of a command whose words did not make it: missing, repeated, or
4/// undecodable arguments. It follows the convention of POSIX utilities.
5pub const USAGE_STATUS: NonZeroU8 = NonZeroU8::new(2).unwrap();
6
7/// States what a command answers: its value, or a failure that ends with a nonzero status.
8///
9/// A successful command exits with status zero. How a value or failure is rendered, and on which
10/// stream, is the interpreter's choice.
11#[derive(Clone, Debug, PartialEq, Eq)]
12pub enum CliOutcome<Value, Error> {
13    /// The command succeeded with this value.
14    Success(Value),
15    /// The command failed with this error.
16    Failure(Error),
17}
18
19/// States what a domain failure denotes on the command line: the status the command exits with.
20///
21/// A domain says this once for its own error type. The status is nonzero by its type, because zero
22/// is success.
23pub trait CliFailureAlg {
24    /// The status a command failing with this error exits with.
25    fn cli_status(&self) -> NonZeroU8;
26
27    /// Whether the failure was already reported as it happened, so the exit carries only its
28    /// status: `cat` reports each missing file and still reads the rest, and `false` reports
29    /// nothing.
30    fn cli_reported(&self) -> bool {
31        false
32    }
33}
34
35/// An error that cannot be constructed has no status, so a command carrying one only succeeds.
36impl CliFailureAlg for Infallible {
37    fn cli_status(&self) -> NonZeroU8 {
38        match *self {}
39    }
40}
41
42impl<Value, Error> CliOutcome<Value, Error>
43where
44    Error: CliFailureAlg,
45{
46    /// Returns the status the command exits with: zero on success, the failure's own otherwise.
47    pub fn cli_status(&self) -> u8 {
48        match self {
49            Self::Success(_) => 0,
50            Self::Failure(error) => error.cli_status().get(),
51        }
52    }
53}
54
55/// Reads every output as a success: the command's default.
56#[derive(Debug, Default)]
57pub struct Total;
58
59/// Reads a `Result` output as success or failure: what `.fallible()` declares.
60#[derive(Debug, Default)]
61pub struct Fallible;
62
63/// Reads an operation's output as a command's outcome under a declared mode.
64#[diagnostic::on_unimplemented(
65    message = "`{Self}` cannot read the output `{Output}` as a command outcome",
66    note = "a `.fallible()` command applies an operation whose output is a `Result`"
67)]
68pub trait CliOutcomeOf<Output> {
69    /// The value a successful command answers with.
70    type Value;
71    /// The failure a command can end with.
72    type Error;
73
74    /// Reads `output` as the command's outcome.
75    fn cli_outcome(&self, output: Output) -> CliOutcome<Self::Value, Self::Error>;
76}
77
78impl<Output> CliOutcomeOf<Output> for Total {
79    type Value = Output;
80    type Error = Infallible;
81
82    fn cli_outcome(&self, output: Output) -> CliOutcome<Output, Infallible> {
83        CliOutcome::Success(output)
84    }
85}
86
87impl<Value, Error> CliOutcomeOf<Result<Value, Error>> for Fallible {
88    type Value = Value;
89    type Error = Error;
90
91    fn cli_outcome(&self, output: Result<Value, Error>) -> CliOutcome<Value, Error> {
92        match output {
93            Ok(value) => CliOutcome::Success(value),
94            Err(error) => CliOutcome::Failure(error),
95        }
96    }
97}