Skip to main content

webpkit_cli/
error.rs

1//! The CLI error type and its process exit codes.
2//!
3//! [`CliError`] wraps the codec's [`webpkit::lossless::Error`] plus the I/O and
4//! usage failures that only exist at the command-line boundary, and maps each to
5//! a meaningful, stable process exit code (see [`CliError::exit_code`]).
6
7use std::{fmt, io, process::ExitCode};
8
9use webpkit::lossless::Error as CodecError;
10
11/// A command-line failure, carrying enough context for a helpful message and a
12/// meaningful process exit code.
13#[derive(Debug)]
14pub enum CliError {
15    /// The arguments were used incorrectly (exit code `2`, matching clap).
16    Usage(String),
17    /// The input could not be read (exit code `3`).
18    ReadInput {
19        /// The source label (a path, or `<stdin>`).
20        label: String,
21        /// The underlying I/O error kind.
22        kind: io::ErrorKind,
23    },
24    /// The output could not be written (exit code `4`).
25    WriteOutput {
26        /// The sink label (a path, or `<stdout>`).
27        label: String,
28        /// The underlying I/O error kind.
29        kind: io::ErrorKind,
30    },
31    /// The codec rejected the input or output (exit code `5`–`8`, by variant).
32    Codec(CodecError),
33    /// An input image format (PNG/PPM) could not be parsed (exit code `9`).
34    Format(String),
35    /// Raw-pixel input was misconfigured, e.g. missing dimensions (exit code `8`).
36    RawConfig(String),
37}
38
39impl CliError {
40    /// Build a [`CliError::ReadInput`] from a labeled I/O error.
41    #[must_use]
42    pub fn read_input(label: String, err: &io::Error) -> Self {
43        Self::ReadInput {
44            label,
45            kind: err.kind(),
46        }
47    }
48
49    /// Build a [`CliError::WriteOutput`] from a labeled I/O error.
50    #[must_use]
51    pub fn write_output(label: String, err: &io::Error) -> Self {
52        Self::WriteOutput {
53            label,
54            kind: err.kind(),
55        }
56    }
57
58    /// The process exit code for this failure.
59    ///
60    /// Codes are meaningful and stable: `2` usage, `3` input I/O, `4` output
61    /// I/O, `5` decode/bitstream, `6` unsupported feature, `7` limit exceeded,
62    /// `8` invalid image or raw config, `9` input-format parse.
63    #[must_use]
64    pub fn exit_code(&self) -> ExitCode {
65        ExitCode::from(self.code())
66    }
67
68    const fn code(&self) -> u8 {
69        match self {
70            Self::Usage(_) => 2,
71            Self::ReadInput { .. } => 3,
72            Self::WriteOutput { .. } => 4,
73            Self::Format(_) => 9,
74            Self::RawConfig(_) => 8,
75            Self::Codec(err) => match err {
76                CodecError::UnsupportedFeature => 6,
77                CodecError::LimitExceeded { .. } => 7,
78                CodecError::InvalidDimensions | CodecError::PixelBufferMismatch => 8,
79                _ => 5,
80            },
81        }
82    }
83}
84
85impl fmt::Display for CliError {
86    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
87        match self {
88            Self::Usage(msg) | Self::Format(msg) | Self::RawConfig(msg) => f.write_str(msg),
89            Self::ReadInput { label, kind } => write!(f, "reading {label}: {kind}"),
90            Self::WriteOutput { label, kind } => write!(f, "writing {label}: {kind}"),
91            Self::Codec(err) => write!(f, "{err}"),
92        }
93    }
94}
95
96impl std::error::Error for CliError {}
97
98impl From<CodecError> for CliError {
99    fn from(err: CodecError) -> Self {
100        Self::Codec(err)
101    }
102}