A fast, helpful, and open-source document parser
feat(pdfium): facts a faithful annotation/form/struct-tree consumer needs
Logan Markewich1fd6136cfda5
diff --git a/crates/liteparse/src/extract.rs b/crates/liteparse/src/extract.rsindex b314184..d2bed4a 100644--- a/crates/liteparse/src/extract.rs+++ b/crates/liteparse/src/extract.rs@@ -460,13 +460,19 @@ pub struct ExtractionOutputOptions {pub emit_word_boxes: bool,}+fn non_empty(value: &Option<String>) -> Option<String> {+ value.as_ref().filter(|v| !v.is_empty()).cloned()+}+fn document_annotation(annotation: &pdfium::PdfAnnotation) -> DocumentAnnotation {DocumentAnnotation {subtype: annotation.subtype.clone(),- contents: annotation.contents.clone(),- created: annotation.created.clone(),- modified: annotation.modified.clone(),- title: annotation.title.clone(),+ // The pdfium layer keeps present-but-empty strings as `Some("")`; this+ // output has always omitted them.+ contents: non_empty(&annotation.contents),+ created: non_empty(&annotation.created),+ modified: non_empty(&annotation.modified),+ title: non_empty(&annotation.title),rect: annotation.rect.map(rect_from_pdfium),quadpoint_rects: annotation.quadpoint_rectsdiff --git a/crates/pdfium-sys/src/dynamic.rs b/crates/pdfium-sys/src/dynamic.rsindex 0de202a..35d4900 100644--- a/crates/pdfium-sys/src/dynamic.rs+++ b/crates/pdfium-sys/src/dynamic.rs@@ -53,6 +53,7 @@ pub struct PdfiumBindings {pub FPDF_CloseDocument: unsafe extern "C" fn(FPDF_DOCUMENT),pub FPDF_GetPageCount: unsafe extern "C" fn(FPDF_DOCUMENT) -> std::os::raw::c_int,pub FPDF_GetFormType: unsafe extern "C" fn(FPDF_DOCUMENT) -> std::os::raw::c_int,+ pub FPDFCatalog_IsTagged: unsafe extern "C" fn(FPDF_DOCUMENT) -> FPDF_BOOL,pub FPDFDOC_InitFormFillEnvironment:unsafe extern "C" fn(FPDF_DOCUMENT, *mut FPDF_FORMFILLINFO) -> FPDF_FORMHANDLE,pub FPDFDOC_ExitFormFillEnvironment: unsafe extern "C" fn(FPDF_FORMHANDLE),@@ -401,6 +402,7 @@ pub struct PdfiumBindings {*mut FPDF_WCHAR,std::os::raw::c_ulong,) -> std::os::raw::c_ulong,+ pub FPDFAnnot_HasKey: unsafe extern "C" fn(FPDF_ANNOTATION, FPDF_BYTESTRING) -> FPDF_BOOL,pub FPDFAnnot_GetRect: unsafe extern "C" fn(FPDF_ANNOTATION, *mut FS_RECTF) -> FPDF_BOOL,pub FPDFAnnot_HasAttachmentPoints: unsafe extern "C" fn(FPDF_ANNOTATION) -> FPDF_BOOL,pub FPDFAnnot_CountAttachmentPoints: unsafe extern "C" fn(FPDF_ANNOTATION) -> usize,@@ -566,6 +568,7 @@ impl PdfiumBindings {FPDF_GetPageCount: load_fn!(lib, "FPDF_GetPageCount"),FPDF_GetPageSizeByIndexF: load_fn!(lib, "FPDF_GetPageSizeByIndexF"),FPDF_GetFormType: load_fn!(lib, "FPDF_GetFormType"),+ FPDFCatalog_IsTagged: load_fn!(lib, "FPDFCatalog_IsTagged"),FPDFDOC_InitFormFillEnvironment: load_fn!(lib, "FPDFDOC_InitFormFillEnvironment"),FPDFDOC_ExitFormFillEnvironment: load_fn!(lib, "FPDFDOC_ExitFormFillEnvironment"),FORM_OnAfterLoadPage: load_fn!(lib, "FORM_OnAfterLoadPage"),@@ -682,6 +685,7 @@ impl PdfiumBindings {FPDFPage_CloseAnnot: load_fn!(lib, "FPDFPage_CloseAnnot"),FPDFAnnot_GetSubtype: load_fn!(lib, "FPDFAnnot_GetSubtype"),FPDFAnnot_GetStringValue: load_fn!(lib, "FPDFAnnot_GetStringValue"),+ FPDFAnnot_HasKey: load_fn!(lib, "FPDFAnnot_HasKey"),FPDFAnnot_GetRect: load_fn!(lib, "FPDFAnnot_GetRect"),FPDFAnnot_HasAttachmentPoints: load_fn!(lib, "FPDFAnnot_HasAttachmentPoints"),FPDFAnnot_CountAttachmentPoints: load_fn!(lib, "FPDFAnnot_CountAttachmentPoints"),diff --git a/crates/pdfium-sys/wrapper.h b/crates/pdfium-sys/wrapper.hindex 10cbd3f..202f146 100644--- a/crates/pdfium-sys/wrapper.h+++ b/crates/pdfium-sys/wrapper.h@@ -3,6 +3,7 @@#include "fpdf_edit.h"#include "fpdf_doc.h"#include "fpdf_annot.h"+#include "fpdf_catalog.h"#include "fpdf_structtree.h"#include "fpdf_transformpage.h"#include "fpdf_signature.h"diff --git a/crates/pdfium/src/document.rs b/crates/pdfium/src/document.rsindex 6a4eaa2..285be6f 100644--- a/crates/pdfium/src/document.rs+++ b/crates/pdfium/src/document.rs@@ -110,6 +110,13 @@ impl<'lib> Document<'lib> {unsafe { ffi!(FPDF_GetFormType(self.handle)) }}+ /// Whether the catalog declares the document tagged (`/MarkInfo /Marked true`).+ /// A structure tree can be present without this flag — residual or stale+ /// tagging — so callers that treat the tree as authoritative gate on it.+ pub fn is_tagged(&self) -> bool {+ (unsafe { ffi!(FPDFCatalog_IsTagged(self.handle)) }) != 0+ }+/// Initialize read-only AcroForm access. Returns `None` for documents with/// no form catalog or when PDFium rejects the form-fill environment.pub fn form_environment(&self) -> Option<FormEnvironment<'_, 'lib>> {diff --git a/crates/pdfium/src/lib.rs b/crates/pdfium/src/lib.rsindex d923be6..3c0765f 100644--- a/crates/pdfium/src/lib.rs+++ b/crates/pdfium/src/lib.rs@@ -15,10 +15,10 @@ pub use error::PdfiumError;pub use font::{Font, FontType};pub use library::Library;pub use page::{- ImageBounds, ImageObjectInfo, ImageObjects, Page, PathObject, PathSegment, PdfAnnotation,- PdfFormField, PdfLink, SegmentKind, ViewportTransform,+ FormPageGuard, ImageBounds, ImageObjectInfo, ImageObjects, Page, PathObject, PathSegment,+ PdfAnnotation, PdfFormField, PdfLink, SegmentKind, ViewportTransform,};-pub use struct_tree::{StructNode, StructureAttributeValue, StructureElement};+pub use struct_tree::{StructNode, StructureAttributeValue, StructureElement, StructureTree};pub use text_page::{TextChar, TextCharIter, TextPage};pub use types::*;diff --git a/crates/pdfium/src/page.rs b/crates/pdfium/src/page.rsindex d848160..c195ce8 100644--- a/crates/pdfium/src/page.rs+++ b/crates/pdfium/src/page.rs@@ -182,7 +182,9 @@ pub struct PdfLink {}/// One PDF annotation with geometry normalized to viewport space (top-left-/// origin, 72 DPI). String fields mirror the standard annotation dictionary.+/// origin, 72 DPI). String fields mirror the standard annotation dictionary:+/// `None` when the key is absent, `Some("")` when it is present but empty, so+/// callers can tell the two apart.#[derive(Debug, Clone)]pub struct PdfAnnotation {pub object_number: Option<i32>,@@ -192,8 +194,19 @@ pub struct PdfAnnotation {pub modified: Option<String>,pub title: Option<String>,pub rect: Option<RectF>,+ /// Whether pdfium reports attachment points for this annotation+ /// (`FPDFAnnot_HasAttachmentPoints`: a subtype test — links and the+ /// text-markup subtypes). Tells "declares no quads" from "subtype never has+ /// them" when `quadpoint_rects` is empty.+ pub has_attachment_points: bool,+ /// Bounding boxes of the `/QuadPoints` quads, when `has_attachment_points`.pub quadpoint_rects: Vec<RectF>,+ /// The link's URI, decoded lossily and only when non-empty.pub uri: Option<String>,+ /// The link's URI action bytes exactly as stored (no trailing NUL), present+ /// whenever the link annotation carries a URI action — including an empty+ /// URI or one that is not valid UTF-8, which `uri` cannot represent.+ pub uri_raw: Option<Vec<u8>>,}/// One AcroForm widget with its resolved field metadata. A logical radio or@@ -365,28 +378,35 @@ impl<'doc, 'lib: 'doc> Page<'doc, 'lib> {dpi: f32,form: Option<&FormEnvironment>,) -> Result<Bitmap<'lib>, PdfiumError> {- if let Some(form) = form {- unsafe {- ffi!(FORM_OnAfterLoadPage(self.handle, form.handle));- ffi!(FORM_DoPageAAction(- self.handle,- form.handle,- pdfium_sys::FPDFPAGE_AACTION_OPEN as i32,- ));- }+ let _form_page = form.map(|form| self.notify_form_page_loaded(form));+ self.render_bitmap(dpi, form)+ }++ /// Tell the form-fill environment this page is open: `FORM_OnAfterLoadPage`+ /// then the page's `/AA` open action. The returned guard runs the close+ /// action and `FORM_OnBeforeClosePage` when dropped, so drop it before the+ /// page itself goes away.+ ///+ /// This is not only for rendering. Loading the page into the environment is+ /// when pdfium builds its widget objects and regenerates appearance streams+ /// that are missing or stale (`NeedAppearances` forms), and a checkbox's+ /// export value is read off that appearance dictionary — so form-field+ /// extraction that skips the notification sees fewer values than a viewer+ /// would.+ pub fn notify_form_page_loaded<'a>(&'a self, form: &'a FormEnvironment) -> FormPageGuard<'a> {+ unsafe {+ ffi!(FORM_OnAfterLoadPage(self.handle, form.handle));+ ffi!(FORM_DoPageAAction(+ self.handle,+ form.handle,+ pdfium_sys::FPDFPAGE_AACTION_OPEN as i32,+ ));}- let result = self.render_bitmap(dpi, form);- if let Some(form) = form {- unsafe {- ffi!(FORM_DoPageAAction(- self.handle,- form.handle,- pdfium_sys::FPDFPAGE_AACTION_CLOSE as i32,- ));- ffi!(FORM_OnBeforeClosePage(self.handle, form.handle));- }+ FormPageGuard {+ page: self.handle,+ form: form.handle,+ _lifetime: std::marker::PhantomData,}- result}fn render_bitmap(@@ -862,7 +882,8 @@ impl<'doc, 'lib: 'doc> Page<'doc, 'lib> {};let mut quadpoint_rects = Vec::new();- if unsafe { ffi!(FPDFAnnot_HasAttachmentPoints(annot)) } != 0 {+ let has_attachment_points = unsafe { ffi!(FPDFAnnot_HasAttachmentPoints(annot)) } != 0;+ if has_attachment_points {let quad_count = unsafe { ffi!(FPDFAnnot_CountAttachmentPoints(annot)) };quadpoint_rects.reserve(quad_count);for quad_index in 0..quad_count {@@ -882,7 +903,7 @@ impl<'doc, 'lib: 'doc> Page<'doc, 'lib> {}}- let uri = if subtype == pdfium_sys::FPDF_ANNOT_LINK as i32 {+ let uri_raw = if subtype == pdfium_sys::FPDF_ANNOT_LINK as i32 {let link = unsafe { ffi!(FPDFAnnot_GetLink(annot)) };if link.is_null() {None@@ -891,12 +912,13 @@ impl<'doc, 'lib: 'doc> Page<'doc, 'lib> {if action.is_null() {None} else {- read_uri_path(self.doc_handle, action)+ read_uri_path_bytes(self.doc_handle, action)}}} else {None};+ let uri = uri_raw.as_deref().and_then(decode_uri_path);out.push(PdfAnnotation {object_number: match unsafe { ffi!(FPDFAnnot_GetObjNum(annot)) } {@@ -904,13 +926,15 @@ impl<'doc, 'lib: 'doc> Page<'doc, 'lib> {_ => None,},subtype: annotation_subtype_name(subtype).to_string(),- contents: read_annotation_string(annot, b"Contents\0"),- created: read_annotation_string(annot, b"CreationDate\0"),- modified: read_annotation_string(annot, b"M\0"),- title: read_annotation_string(annot, b"T\0"),+ contents: read_annotation_string_if_present(annot, b"Contents\0"),+ created: read_annotation_string_if_present(annot, b"CreationDate\0"),+ modified: read_annotation_string_if_present(annot, b"M\0"),+ title: read_annotation_string_if_present(annot, b"T\0"),rect,+ has_attachment_points,quadpoint_rects,uri,+ uri_raw,});unsafe { ffi!(FPDFPage_CloseAnnot(annot)) };}@@ -1244,6 +1268,27 @@ impl<'doc, 'lib: 'doc> Page<'doc, 'lib> {}}+/// A page's open session in a form-fill environment; see+/// [`Page::notify_form_page_loaded`]. Closing notifications run on drop.+pub struct FormPageGuard<'a> {+ page: pdfium_sys::FPDF_PAGE,+ form: pdfium_sys::FPDF_FORMHANDLE,+ _lifetime: std::marker::PhantomData<&'a ()>,+}++impl Drop for FormPageGuard<'_> {+ fn drop(&mut self) {+ unsafe {+ ffi!(FORM_DoPageAAction(+ self.page,+ self.form,+ pdfium_sys::FPDFPAGE_AACTION_CLOSE as i32,+ ));+ ffi!(FORM_OnBeforeClosePage(self.page, self.form));+ }+ }+}+/// The optional page-flatten API, resolved together so a build missing either/// half degrades to "no flattening" rather than failing the whole pdfium load.struct FlattenApi {@@ -1400,16 +1445,34 @@ fn read_form_string((!value.is_empty()).then_some(value)}+/// One choice-field option label. An empty label is a real option (the blank+/// first entry of many combo boxes) and is kept as `Some("")`; `None` only+/// when pdfium has no label at all for the index.fn read_form_option_label(form: pdfium_sys::FPDF_FORMHANDLE,annot: pdfium_sys::FPDF_ANNOTATION,index: i32,) -> Option<String> {- read_form_string(form, annot, |handle, annotation, buffer, len| unsafe {+ let needed = unsafe {ffi!(FPDFAnnot_GetOptionLabel(- handle, annotation, index, buffer, len+ form,+ annot,+ index,+ std::ptr::null_mut(),+ 0))- })+ } as usize;+ if needed == 0 {+ return None;+ }+ Some(+ read_form_string(form, annot, |handle, annotation, buffer, len| unsafe {+ ffi!(FPDFAnnot_GetOptionLabel(+ handle, annotation, index, buffer, len+ ))+ })+ .unwrap_or_default(),+ )}fn annotation_rect(@@ -1470,6 +1533,19 @@ fn annotation_subtype_name(subtype: pdfium_sys::FPDF_ANNOTATION_SUBTYPE) -> &'st.unwrap_or("unknown")}+/// An annotation dictionary string by key: `None` when the key is absent,+/// `Some("")` when present but empty. (`FPDFAnnot_GetStringValue` alone+/// reports both as an empty string, so presence is checked first.)+fn read_annotation_string_if_present(+ annot: pdfium_sys::FPDF_ANNOTATION,+ key: &'static [u8],+) -> Option<String> {+ if unsafe { ffi!(FPDFAnnot_HasKey(annot, key.as_ptr().cast())) } == 0 {+ return None;+ }+ Some(read_annotation_string(annot, key).unwrap_or_default())+}+fn read_annotation_string(annot: pdfium_sys::FPDF_ANNOTATION,key: &'static [u8],@@ -1511,13 +1587,16 @@ fn read_annotation_string(/// Read a link action's URI path. PDFium returns the URI as a NUL-terminated/// 7-bit-ASCII byte string; the two-call protocol queries the length first./// Returns `None` for non-URI actions (length 0) or empty URIs.-fn read_uri_path(+/// The URI action's path bytes as stored, without the trailing NUL. `None`+/// when `action` is not a URI action.+fn read_uri_path_bytes(doc: pdfium_sys::FPDF_DOCUMENT,action: pdfium_sys::FPDF_ACTION,-) -> Option<String> {+) -> Option<Vec<u8>> {let needed =unsafe { ffi!(FPDFAction_GetURIPath(doc, action, std::ptr::null_mut(), 0)) } as usize;- if needed < 2 {+ // pdfium reports `len + 1` for a URI action (the NUL), 0 for anything else.+ if needed < 1 {return None;}let mut buf: Vec<u8> = vec![0; needed];@@ -1529,17 +1608,31 @@ fn read_uri_path(needed as std::os::raw::c_ulong,))} as usize;- if written < 2 {+ if written < 1 {return None;}- // `written` includes the trailing NUL.- let end = written.saturating_sub(1).min(buf.len());- let uri = String::from_utf8_lossy(&buf[..end])+ buf.truncate(written.saturating_sub(1).min(buf.len()));+ Some(buf)+}++/// The lossy, NUL-trimmed, non-empty form of a URI path for callers that want+/// a string to show or match on.+fn decode_uri_path(bytes: &[u8]) -> Option<String> {+ let uri = String::from_utf8_lossy(bytes).trim_matches(char::from(0)).to_string();if uri.is_empty() { None } else { Some(uri) }}+fn read_uri_path(+ doc: pdfium_sys::FPDF_DOCUMENT,+ action: pdfium_sys::FPDF_ACTION,+) -> Option<String> {+ read_uri_path_bytes(doc, action)+ .as_deref()+ .and_then(decode_uri_path)+}+const FS_IDENTITY: pdfium_sys::FS_MATRIX = pdfium_sys::FS_MATRIX {a: 1.0,b: 0.0,diff --git a/crates/pdfium/src/struct_tree.rs b/crates/pdfium/src/struct_tree.rsindex bcde073..224c2c0 100644--- a/crates/pdfium/src/struct_tree.rs+++ b/crates/pdfium/src/struct_tree.rs@@ -40,6 +40,18 @@ pub struct StructureElement {pub annotation_object_numbers: Vec<i32>,}+/// The page-scoped structure tree with the root count pdfium reported.+///+/// `root_count` can exceed `roots.len()`: pdfium returns a null element for a+/// root that does not belong to the page, and those are skipped. Callers that+/// shape output on "one root vs several" need the declared count, not the+/// number that resolved.+#[derive(Debug, Clone, Default)]+pub struct StructureTree {+ pub root_count: usize,+ pub roots: Vec<StructureElement>,+}+/// One node in the structure tree, flattened for downstream use.#[derive(Debug, Clone)]pub struct StructNode {@@ -59,9 +71,15 @@ impl Page<'_, '_> {/// Extract the complete tagged-PDF structure tree for public output./// Returns an empty vector for untagged pages and preserves multiple roots.pub fn structure_tree(&self) -> Vec<StructureElement> {+ self.structure_tree_with_root_count().roots+ }++ /// [`Page::structure_tree`] plus the number of roots pdfium declared for+ /// the page, including the ones it could not resolve.+ pub fn structure_tree_with_root_count(&self) -> StructureTree {let tree = unsafe { ffi!(FPDF_StructTree_GetForPage(self.handle)) };if tree.is_null() {- return Vec::new();+ return StructureTree::default();}let count = unsafe { ffi!(FPDF_StructTree_CountChildren(tree)) };let mut roots = Vec::with_capacity(count.max(0) as usize);@@ -72,7 +90,10 @@ impl Page<'_, '_> {}}unsafe { ffi!(FPDF_StructTree_Close(tree)) };- roots+ StructureTree {+ root_count: count.max(0) as usize,+ roots,+ }}/// Walk this page's structure tree (tagged-PDF tree). Returns an empty