Skip to main content

sylva_rs/
error.rs

1// Sylva: LiDAR processing for forest ecology and remote sensing research.
2// Copyright (C) 2026 Tim Devereux, The University of Queensland.
3// Free software under the GNU General Public License v3.0 or later;
4// see the LICENSE file. There is no warranty, to the extent permitted by law.
5//! What can go wrong, and the message it carries.
6//!
7//! Every fallible function in the core returns [`Result<T>`], which is "a `T`
8//! or an [`Error`]". Callers either handle it or pass it on with `?`; nothing
9//! is thrown, and a failure cannot be ignored by accident. The bindings turn
10//! these into Python exceptions, so the text below is what the person running
11//! the command finally reads — which is why it names the file and says what
12//! would make it work, rather than describing the internals.
13
14use std::path::PathBuf;
15
16/// A failure, in one of the handful of kinds the core distinguishes.
17///
18/// The `#[error(...)]` lines are the messages; `#[from]` means an error of
19/// that foreign type converts into this one on its own, which is what lets a
20/// function working with files write `?` after a standard library call. A
21/// variant added here is handled everywhere at once, because the compiler
22/// refuses any `match` that forgets it.
23#[derive(Debug, thiserror::Error)]
24pub enum Error {
25    #[error("{0}")]
26    /// A bad argument or inconsistent input (lengths that disagree, an unknown mode,
27    /// too few points); the message is the whole text.
28    Invalid(String),
29    #[error("unsupported format: {0:?}")]
30    /// A file extension or format name no reader or writer handles, e.g. a point
31    /// file that is not LAS/LAZ or a polygon file that is not .shp/.geojson.
32    UnsupportedFormat(String),
33    #[error("{path}: {msg}")]
34    /// Something wrong with one file, named by `path`, with `msg` saying what
35    /// (cannot be read, too few values, not a project directory).
36    File {
37        /// The file (or directory) the error is about.
38        path: PathBuf,
39        /// What was wrong with it, in plain words.
40        msg: String,
41    },
42    #[error(transparent)]
43    /// An operating-system I/O failure such as a missing file or denied permission,
44    /// converted from `std::io::Error`.
45    Io(#[from] std::io::Error),
46    #[error("LAS: {0}")]
47    /// A LAS/LAZ read or write failure reported by the `las` crate (bad header,
48    /// unsupported point format, truncated file).
49    Las(#[from] las::Error),
50    #[error("RIEGL RiVLib: {0}")]
51    /// A RIEGL RiVLib failure: the RXP library could not be loaded or reported an
52    /// error while reading a scan, or an MTA model file is malformed.
53    Riegl(String),
54    #[error("RIEGL RDB: {0}")]
55    /// A RIEGL RDB failure: librdb could not be loaded, or an .rdbx file could not
56    /// be read or lacks a needed point attribute.
57    Rdb(String),
58}
59
60/// The crate's own `Result`: `Result<T>` here means `Result<T, Error>`.
61pub type Result<T> = std::result::Result<T, Error>;
62
63impl Error {
64    /// An [`Error::Invalid`] carrying `msg`: the usual way to reject a bad argument.
65    pub fn invalid(msg: impl Into<String>) -> Self {
66        Error::Invalid(msg.into())
67    }
68
69    /// An [`Error::File`] naming `path` and saying what was wrong with it.
70    pub fn file(path: impl Into<PathBuf>, msg: impl Into<String>) -> Self {
71        Error::File { path: path.into(), msg: msg.into() }
72    }
73}