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