pdfluent_forms/lib.rs
1//! AcroForm engine for PDF interactive forms.
2//!
3//! Parses AcroForm field dictionaries from a [`pdf_syntax::Pdf`] into an
4//! in-memory [`FieldTree`] — an arena-based tree that mirrors the AcroForm
5//! parent/child hierarchy. Supports field value read/write, appearance
6//! generation, and form flattening.
7//!
8//! # Quick Start
9//!
10//! ```no_run
11//! use std::sync::Arc;
12//! use pdf_syntax::Pdf;
13//! use pdf_forms::{parse_acroform, FieldType, FieldValue};
14//!
15//! let data = Arc::new(std::fs::read("form.pdf").unwrap());
16//! let pdf = Pdf::new(data).unwrap();
17//!
18//! let tree = parse_acroform(&pdf).expect("no AcroForm found");
19//!
20//! for id in tree.terminal_fields() {
21//! let name = tree.fully_qualified_name(id);
22//! let ftype = tree.effective_field_type(id);
23//! let value = tree.effective_value(id);
24//! println!("[{ftype:?}] {name} = {value:?}");
25//! }
26//!
27//! // Find a field by name and inspect its properties.
28//! if let Some(id) = tree.find_by_name("Address.Street") {
29//! let node = tree.get(id);
30//! println!("max_len = {:?}", node.max_len);
31//! }
32//! ```
33//!
34//! # Key Types
35//!
36//! | Type | Description |
37//! |---|---|
38//! | [`FieldTree`] | Arena of all AcroForm field nodes |
39//! | [`FieldNode`] | A single field or group (partial name, type, value, …) |
40//! | [`FieldId`] | Opaque index into the arena |
41//! | [`FieldType`] | `Text`, `Button`, `Choice`, `Signature` |
42//! | [`FieldValue`] | Text string or array of selected strings (choice fields) |
43//! | [`FieldFlags`] | Bit-field from PDF `/Ff` — read-only, required, multiline, … |
44//! | [`FormAccess`] | Trait used by language bindings for unified AcroForm / XFA access |
45//!
46//! # Entry Point
47//!
48//! [`parse_acroform`] is the single parser entry point. It returns `None` when
49//! the document has no `/AcroForm` dictionary.
50
51pub mod actions;
52pub mod appearance;
53pub mod button;
54pub mod choice;
55pub mod facade;
56pub mod flags;
57pub mod flatten;
58pub mod parse;
59pub mod text;
60pub mod tree;
61
62pub use facade::{DocumentOps, FormAccess, FormError, FormKind};
63pub use flags::FieldFlags;
64pub use parse::parse_acroform;
65pub use tree::{FieldId, FieldNode, FieldTree, FieldType, FieldValue, Quadding};