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}