# How to Use the `PdfOptions` Builder to Configure ProcessMode, Page Filters, and Passwords in pdf-inspector

> Configure ProcessMode, page filters, and passwords in pdf-inspector using the PdfOptions builder. Easily set processing pipelines, page subsets, and decryption passwords for efficient PDF handling.

- Repository: [Firecrawl/pdf-inspector](https://github.com/firecrawl/pdf-inspector)
- Tags: how-to-guide
- Published: 2026-08-06

---

**The `PdfOptions` builder in pdf-inspector provides a fluent, chainable interface for configuring processing pipelines, page subsets, and decryption passwords through methods like `mode()`, `pages()`, and `password()`.**

The `PdfOptions` struct in `firecrawl/pdf-inspector` serves as the central configuration object for all high-level PDF processing operations. Following the classic builder pattern, each method consumes `self`, updates an internal field, and returns the modified struct—enabling method chaining for concise, readable configuration.

## Understanding the `PdfOptions` Builder Pattern

The builder's fields and default values are defined in [`src/lib.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/lib.rs) at lines 176–187. The concrete implementation methods follow immediately after the `impl Default` block, providing type-safe configuration for three core dimensions: processing depth, page scope, and document encryption.

| Builder method | Configures | Default |
|---------------|-----------|---------|
| `mode(ProcessMode)` | Pipeline stage (`Full`, `DetectOnly`, `Analyze`) | `ProcessMode::Full` |
| `pages(iter)` | 1-indexed page subset as `HashSet<u32>` | `None` (all pages) |
| `password(pw)` | User password for encrypted PDFs | `None` (empty password) |

The `password` field is intentionally obscured in debug output—displayed as `"[REDACTED]"`—protecting sensitive credentials in logs.

## Configuring `ProcessMode` with `mode()`

The `mode()` method sets how far the processing pipeline runs. As implemented in [`src/lib.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/lib.rs) lines 30–34, it accepts any variant of the `ProcessMode` enum (defined in [`src/process_mode.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/process_mode.rs)):

```rust
use pdf_inspector::{PdfOptions, ProcessMode};

// Run complete extraction pipeline
let opts = PdfOptions::new().mode(ProcessMode::Full);

// Stop early after metadata detection only
let opts = PdfOptions::new().mode(ProcessMode::DetectOnly);

```

**`ProcessMode::Full`** executes the complete pipeline including content extraction. **`ProcessMode::DetectOnly`** halts after document type identification, useful for quick classification without parsing overhead.

## Filtering Pages with `pages()`

The `pages()` method restricts processing to specific 1-indexed pages. Implemented at lines 48–52 in [`src/lib.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/lib.rs), it accepts any iterator yielding `u32` values—arrays, vectors, or ranges—and converts them to an internal `HashSet<u32>` for deduplication:

```rust
use pdf_inspector::PdfOptions;

// Process specific pages only
let opts = PdfOptions::new().pages([2, 5, 10]);

// Process first 10 pages using range syntax
let opts = PdfOptions::new().pages(1..=10);

// Process from a Vec
let subset: Vec<u32> = vec![1, 3, 7];
let opts = PdfOptions::new().pages(subset);

```

The page filter is passed to `load_document_from_path_with_password()` in [`src/detector.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/detector.rs), limiting which pages the core loader examines.

## Decrypting PDFs with `password()`

For password-protected PDFs, the `password()` method supplies decryption credentials. As shown in lines 54–57 of [`src/lib.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/lib.rs):

```rust
use pdf_inspector::PdfOptions;

let opts = PdfOptions::new().password("my-secret");

```

When `process_pdf_with_options()` executes, the password becomes:

```rust
let (doc, page_count) = load_document_from_path_with_password(
    &path,
    options.password.as_deref(),
)?;

```

The `as_deref()` call converts `Option<String>` to `Option<&str>`, matching the loader's signature.

## Complete Configuration Examples

### Example 1: Full Extraction on Select Pages of Encrypted PDF

```rust
use pdf_inspector::{PdfOptions, ProcessMode};

let opts = PdfOptions::new()
    .mode(ProcessMode::Full)          // Complete pipeline
    .pages([2, 5])                    // Pages 2 and 5 only
    .password("my-secret");           // Decrypt first

let result = pdf_inspector::process_pdf_with_options("protected.pdf", opts)?;
println!("{:?}", result);

```

### Example 2: Detection-Only with Page Limit

```rust
use pdf_inspector::{PdfOptions, ProcessMode};

let opts = PdfOptions::new()
    .mode(ProcessMode::DetectOnly)   // Metadata detection only
    .pages(1..=10);                   // Optional: limit scan scope

let detection = pdf_inspector::process_pdf_with_options("big.pdf", opts)?;
println!("Detected type: {:?}", detection.pdf_type);

```

## Key Source Files Reference

| File | Purpose |
|------|---------|
| [`src/lib.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/lib.rs) | Defines `PdfOptions` struct, defaults, and builder methods (`mode`, `pages`, `password`) at lines 176–187 and surrounding implementation blocks |
| [`src/process_mode.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/process_mode.rs) | `ProcessMode` enum definition with pipeline stage variants |
| [`src/detector.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/detector.rs) | Consumes `PdfOptions` in `load_document_from_path_with_password()` |
| [`src/bin/pdf2md.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/pdf2md.rs) | CLI demonstrating real-world builder usage from command-line arguments |

## Summary

- **Method chaining**: Each `PdfOptions` method returns `self`, enabling fluent `.mode().pages().password()` sequences
- **Flexible page input**: `pages()` accepts any `IntoIterator<Item = u32>`—arrays, ranges, vectors
- **Security-conscious**: Passwords are redacted in `Debug` output to prevent credential leakage
- **Pipeline control**: `ProcessMode` determines whether detection, analysis, or full extraction runs
- **Direct integration**: Builder values flow directly into `load_document_from_path_with_password()` for document loading

## Frequently Asked Questions

### What happens if I don't call `mode()` on `PdfOptions`?

The builder defaults to `ProcessMode::Full` through its `Default` implementation. Without explicit configuration, the complete extraction pipeline runs—equivalent to calling `.mode(ProcessMode::Full)`.

### Can I use `pages()` with overlapping or out-of-order values?

Yes. The implementation converts any iterator to a `HashSet<u32>`, automatically deduplicating duplicates and ignoring order. Pages 5, 2, 5 become {2, 5}; processing occurs in PDF-native page order regardless of input sequence.

### Does `password()` accept empty strings for owner-only encryption?

Yes. Passing `.password("")` or omitting the call entirely both result in `None` for the internal `Option<String>`, triggering the empty password path in the PDF loader. For protected PDFs with non-empty user passwords, the correct value must be supplied.

### Is `PdfOptions` reusable across multiple PDFs?

No—each builder method consumes `self`. To process multiple files with identical settings, call `PdfOptions::new()` and re-chain the configuration for each operation, or clone a configured instance with `.clone()` before passing to processing functions.