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}