pdfluent_extract/error.rs
1//! Error types for `pdf-extract` operations.
2
3use thiserror::Error;
4
5/// Errors returned by the `pdf-extract` crate while reading text or images
6/// from a PDF.
7///
8/// Customers usually see these wrapped inside `pdfluent::Error` after they
9/// bubble up through the facade. The inner variant tells the caller what
10/// kind of input prevented extraction.
11#[derive(Debug, Error)]
12pub enum ExtractError {
13 /// The underlying PDF byte stream could not be parsed.
14 ///
15 /// Typically a malformed cross-reference table, a truncated stream, or
16 /// an unsupported PDF construct. The wrapped `lopdf::Error` has the
17 /// detail; surface it to the user when reporting the problem.
18 #[error("PDF error: {0}")]
19 Pdf(#[from] lopdf::Error),
20
21 /// An I/O error occurred while reading the document or writing extracted
22 /// output (for image extraction targets).
23 #[error("IO error: {0}")]
24 Io(#[from] std::io::Error),
25
26 /// The caller asked for a page index that does not exist in the
27 /// document.
28 ///
29 /// Fields: `(requested_page, total_pages)`. Page numbers are 1-based at
30 /// the public API; this variant carries the same convention.
31 #[error("page {0} out of range (document has {1} pages)")]
32 PageOutOfRange(u32, u32),
33
34 /// The image embedded on the page uses a PDF stream filter that this
35 /// crate cannot decode (for example uncommon JPX profiles or unknown
36 /// custom filters). The wrapped string identifies the filter by its
37 /// PDF name.
38 #[error("unsupported image filter: {0}")]
39 UnsupportedFilter(String),
40
41 /// Image bytes were extracted but could not be decoded by the image
42 /// backend (corrupt JPEG/PNG/JPX payload, invalid colorspace, etc.).
43 #[error("image decode error: {0}")]
44 ImageDecode(String),
45
46 /// A non-categorised extraction failure. Reserved for cases the more
47 /// specific variants do not cover; the message describes the situation.
48 #[error("{0}")]
49 Other(String),
50}
51
52/// Convenience `Result` alias for fallible `pdf-extract` operations.
53pub type Result<T> = std::result::Result<T, ExtractError>;