rtemis_a3/
error.rs

1//! Error types for the rtemis-a3 library.
2//!
3//! All fallible operations return `Result<T, A3Error>`. The two variants
4//! map onto the two failure modes described in the A3 spec:
5//!
6//! - [`A3Error::Parse`]     — the input was not valid JSON
7//! - [`A3Error::Serialize`] — a valid A3 value could not be serialized to JSON
8//! - [`A3Error::Validate`]  — the JSON parsed but violated A3 rules
9
10// `thiserror::Error` is a derive macro that generates the boilerplate needed
11// to make our enum implement the standard `std::error::Error` trait.
12use thiserror::Error;
13
14/// The single error type returned by every fallible function in this crate.
15///
16/// In Rust, errors are values — there are no exceptions. Every function that
17/// can fail returns `Result<T, A3Error>`, which is either `Ok(value)` or
18/// `Err(A3Error::...)`. The caller decides how to handle it.
19///
20/// `#[derive(Debug)]` lets you print the error with `{:?}` formatting.
21/// `#[derive(Error)]` (from thiserror) implements `std::error::Error` for us.
22#[derive(Debug, Error)]
23pub enum A3Error {
24    /// Returned when the input string is not valid JSON.
25    ///
26    /// `#[error("...")]` defines the human-readable message produced by
27    /// `.to_string()` or the `{}` format specifier.
28    ///
29    /// `{0}` refers to the first (and only) field of this variant by position.
30    /// `serde_json::Error` is the underlying parse error from the JSON library.
31    ///
32    /// `#[from]` implements `From<serde_json::Error> for A3Error` automatically,
33    /// enabling the `?` operator to convert deserialization errors into this
34    /// variant without an explicit `.map_err(...)` call.
35    #[error("Failed to parse JSON: {0}")]
36    Parse(#[from] serde_json::Error),
37
38    /// Returned when a validated [`crate::A3`] cannot be serialized to JSON.
39    ///
40    /// In practice this variant is unreachable for well-typed A3 values, but
41    /// it is kept distinct from [`A3Error::Parse`] so that error messages
42    /// accurately reflect the failure mode — serialization, not parsing.
43    #[error("Failed to serialize to JSON: {0}")]
44    Serialize(serde_json::Error),
45
46    /// Returned when input is structurally valid JSON but violates A3 rules.
47    ///
48    /// We collect *all* validation errors into a `Vec<String>` so that a
49    /// caller sees every problem at once, not just the first one encountered.
50    ///
51    /// `{0:#?}` uses the "alternate" debug formatter, which prints each
52    /// element on its own line — readable for a list of error messages.
53    #[error("A3 validation failed:\n{0:#?}")]
54    Validate(Vec<String>),
55}
rtemis_a3/error.rs

rtemis_a3/
error.rs
