acroform 0.0.12

High-level PDF form manipulation library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

# acroform - Minimal PDF Form Manipulation

A minimal, auditable PDF form manipulation library focusing on:
- Reading PDF forms
- Listing form fields
- Updating field values
- Saving modified PDFs

## Design Principles

- **Minimal**: Only form filling, no rendering or appearance generation
- **Auditable**: Small codebase, easy to review
- **Standards-compliant**: Relies on PDF viewers for appearance generation via NeedAppearances flag
- **Non-incremental**: Always writes complete PDF, not incremental updates
- **Separation of Concerns**: Built as a separate crate on top of the forked `pdf` crate

## Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
acroform = { path = "acroform" }
```

## Usage

### Three-Step API

```rust
use acroform::{AcroFormDocument, FieldValue};
use std::collections::HashMap;

// Step 1: Load a PDF
let mut doc = AcroFormDocument::from_pdf("form.pdf")?;

// Step 2: List fields
for field in doc.fields()? {
    println!("Field: {} = {:?}", field.name, field.current_value);
}

// Step 3: Fill and save
let mut values = HashMap::new();
values.insert("firstName".to_string(), FieldValue::Text("John".to_string()));
values.insert("lastName".to_string(), FieldValue::Text("Doe".to_string()));

doc.fill_and_save(values, "filled_form.pdf")?;
```

### Field Types

The library supports the following field value types:

- `FieldValue::Text(String)` - Text fields
- `FieldValue::Boolean(bool)` - Checkboxes
- `FieldValue::Choice(String)` - Radio buttons and dropdowns
- `FieldValue::Integer(i32)` - Integer fields

### Field Names

Field names are automatically resolved with full hierarchical names (e.g., `parent.child.field`).
The library handles nested field structures internally and presents a flat list of terminal fields.

## Example

See `acroform/examples/simple_fill.rs` for a complete working example:

```bash
cargo run --example simple_fill -p acroform
```

## Architecture

The `acroform` crate is built as a separate layer on top of the forked `pdf` crate:

- **pdf/**: Forked PDF parsing and manipulation library (NOT MODIFIED)
- **acroform/**: Form-specific functionality (NEW)
  - `field.rs`: Extension traits for field traversal
  - `api.rs`: High-level form filling API
  - `lib.rs`: Public exports and documentation

This design allows the underlying `pdf` crate to remain unmodified, making it easy to merge upstream updates.

## Testing

Run the test suite:

```bash
cargo test -p acroform
```

Test files are located in `acroform_files/`:
- `af8.pdf` - Test PDF with a single text field

## Implementation Status

✅ Load PDF with AcroForm  
✅ List all fillable fields with names and types  
✅ Update text field values  
✅ Update checkbox/radio button states  
✅ Save modified PDF  
✅ Generated PDFs show updated values when opened  

## Non-Goals

The library explicitly does NOT support:
- PDF rendering or visual preview
- Incremental updates (linearized PDFs)
- Appearance stream generation
- Digital signature creation/validation
- XFA form support
- Interactive JavaScript evaluation
- PDF creation from scratch
- Form field creation/deletion

## License

MIT