refactor: add LoadOptions and Document::load_with_options

Introduce a LoadOptions struct (password, filter, strict) so loading
configuration is extensible without new method variants. Existing
load/load_from/load_mem methods delegate to new _with_options
counterparts; password-only and filter-only shorthands are deprecated.

The strict field is threaded to Reader but not yet acted on — a
follow-up will use it to reject non-conforming PDF headers.

Author: rth

CHANGELOG.md

@@ -1,4 +1,15 @@
 
+## [Unreleased]
+
+### Add
+
+* Add `LoadOptions` struct with `password`, `filter`, and `strict` fields for extensible loading configuration
+* Add `load_with_options`, `load_from_with_options`, and `load_mem_with_options` methods (sync + async)
+
+### Deprecate
+
+* Deprecate `load_filtered`, `load_from_with_password`, `load_mem_with_password` in favor of `_with_options` variants
+
 <a name="v0.38.0"></a>
 ## [v0.38.0](https://github.com/J-F-Liu/lopdf/compare/v0.37.0...v0.38.0) (2025-08-26)
 

examples/extract_text.rs

@@ -6,7 +6,7 @@ use std::path::{Path, PathBuf};
 use std::time::Instant;
 
 use clap::Parser;
-use lopdf::{Document, Object};
+use lopdf::{Document, LoadOptions, Object};
 use rayon::iter::{IntoParallelIterator, ParallelIterator};
 use serde::{Deserialize, Serialize};
 use serde_json;
@@ -98,13 +98,14 @@ fn filter_func(object_id: (u32, u16), object: &mut Object) -> Option<((u32, u16)
 
 #[cfg(not(feature = "async"))]
 fn load_pdf<P: AsRef<Path>>(path: P) -> Result<Document, Error> {
-    Document::load_filtered(path, filter_func).map_err(|e| Error::new(ErrorKind::Other, e.to_string()))
+    Document::load_with_options(path, LoadOptions::with_filter(filter_func))
+        .map_err(|e| Error::new(ErrorKind::Other, e.to_string()))
 }
 
 #[cfg(feature = "async")]
 fn load_pdf<P: AsRef<Path>>(path: P) -> Result<Document, Error> {
     Ok(Builder::new_current_thread().build().unwrap().block_on(async move {
-        Document::load_filtered(path, filter_func)
+        Document::load_with_options(path, LoadOptions::with_filter(filter_func))
             .await
             .map_err(|e| Error::new(ErrorKind::Other, e.to_string()))
     })?)

examples/extract_toc.rs

@@ -5,7 +5,7 @@ use std::path::{Path, PathBuf};
 use std::time::Instant;
 
 use clap::Parser;
-use lopdf::{Document, Object};
+use lopdf::{Document, LoadOptions, Object};
 use serde_json;
 use shellexpand;
 
@@ -89,13 +89,14 @@ fn filter_func(object_id: (u32, u16), object: &mut Object) -> Option<((u32, u16)
 
 #[cfg(not(feature = "async"))]
 fn load_pdf<P: AsRef<Path>>(path: P) -> Result<Document, Error> {
-    Document::load_filtered(path, filter_func).map_err(|e| Error::new(ErrorKind::Other, e.to_string()))
+    Document::load_with_options(path, LoadOptions::with_filter(filter_func))
+        .map_err(|e| Error::new(ErrorKind::Other, e.to_string()))
 }
 
 #[cfg(feature = "async")]
 fn load_pdf<P: AsRef<Path>>(path: P) -> Result<Document, Error> {
     Ok(Builder::new_current_thread().build().unwrap().block_on(async move {
-        Document::load_filtered(path, filter_func)
+        Document::load_with_options(path, LoadOptions::with_filter(filter_func))
             .await
             .map_err(|e| Error::new(ErrorKind::Other, e.to_string()))
     })?)

src/lib.rs

@@ -26,6 +26,7 @@ mod processor;
 mod toc;
 mod writer;
 
+mod load_options;
 mod object_stream;
 mod parser;
 mod parser_aux;
@@ -46,6 +47,7 @@ pub use error::{Error, Result};
 pub use incremental_document::IncrementalDocument;
 pub use object_stream::{ObjectStream, ObjectStreamBuilder, ObjectStreamConfig};
 pub use outlines::Outline;
+pub use load_options::{FilterFunc, LoadOptions};
 pub use reader::{Reader, PdfMetadata};
 pub use save_options::{SaveOptions, SaveOptionsBuilder};
 pub use toc::Toc;

src/load_options.rs

@@ -0,0 +1,68 @@
+use crate::Object;
+
+/// Type alias for the filter function used during PDF loading.
+///
+/// The function receives an object ID and a mutable reference to the object,
+/// and returns `Some((id, object))` to keep it or `None` to discard it.
+pub type FilterFunc = fn((u32, u16), &mut Object) -> Option<((u32, u16), Object)>;
+
+/// Options for loading PDF documents.
+///
+/// Use this struct to configure password, object filtering, and strictness
+/// when loading a PDF. The default is lenient parsing with no password or filter.
+///
+/// # Examples
+///
+/// ```no_run
+/// use lopdf::{Document, LoadOptions};
+///
+/// // Load with a password
+/// let doc = Document::load_with_options(
+///     "encrypted.pdf",
+///     LoadOptions::with_password("secret"),
+/// );
+///
+/// // Load with strict parsing
+/// let doc = Document::load_with_options(
+///     "document.pdf",
+///     LoadOptions { strict: true, ..Default::default() },
+/// );
+/// ```
+#[derive(Clone, Default)]
+pub struct LoadOptions {
+    /// Password for encrypted PDFs.
+    pub password: Option<String>,
+    /// Object filter applied during loading.
+    pub filter: Option<FilterFunc>,
+    /// When `true`, reject non-conforming PDFs instead of silently accepting them.
+    /// Defaults to `false` (lenient parsing).
+    pub strict: bool,
+}
+
+impl std::fmt::Debug for LoadOptions {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("LoadOptions")
+            .field("password", &self.password.as_ref().map(|_| "***"))
+            .field("filter", &self.filter.map(|_| "fn(..)"))
+            .field("strict", &self.strict)
+            .finish()
+    }
+}
+
+impl LoadOptions {
+    /// Create options with a password for encrypted PDFs.
+    pub fn with_password(password: &str) -> Self {
+        Self {
+            password: Some(password.to_string()),
+            ..Default::default()
+        }
+    }
+
+    /// Create options with an object filter.
+    pub fn with_filter(filter: FilterFunc) -> Self {
+        Self {
+            filter: Some(filter),
+            ..Default::default()
+        }
+    }
+}