jedarden/pdftract
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
pdftract/notes/pdftract-2bsfc.md
jedarden b535638104 feat(pdftract-2bsfc): implement document catalog parser with PageLabels number tree 
Implement the document catalog parser (/Root traversal) for PDF documents.
The catalog parser extracts all key entries from the document catalog
including Pages, Outlines, MarkInfo, StructTreeRoot, AcroForm, Names,
Metadata, PageLabels, OCProperties, OpenAction, AA, and Version.

Key structures:
- MarkInfo: parses /MarkInfo dictionary with is_tagged, user_properties, suspects
- PageLabelStyle: enum for all label styles (D, R, r, A, a)
- PageLabel: single page label with style, prefix, and start value
- PageLabelsTree: number tree parser for /PageLabels with /Nums and /Kids support
- OcProperties: stub for OCG implementation (delegated to dedicated bead)
- Catalog: main catalog struct with all required and optional fields

Number tree implementation:
- Parses /Nums arrays (leaf nodes with alternating key-value pairs)
- Supports /Kids arrays (internal nodes for recursive tree traversal)
- Provides get_label_with_start() and get_label() methods for lookup
- Correctly formats roman numerals (uppercase/lowercase) and letter sequences

All 27 tests pass including proptests for fuzzing robustness (INV-8).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-17 23:45:45 -04:00

4.6 KiB
Raw Blame History

pdftract-2bsfc: Document Catalog Parser Implementation

Summary

Implemented the document catalog parser (/Root traversal) for PDF documents. The catalog parser extracts all key entries from the document catalog including Pages, Outlines, MarkInfo, StructTreeRoot, AcroForm, Names, Metadata, PageLabels, OCProperties, OpenAction, AA, and Version.

Implementation Details

Files Modified

  • crates/pdftract-core/src/parser/catalog.rs - Full implementation with comprehensive tests

Key Structures Implemented

  1. MarkInfo - Parses /MarkInfo dictionary with is_tagged, user_properties, suspects fields
  2. PageLabelStyle - Enum for all label styles (D, R, r, A, a)
  3. PageLabel - Single page label with style, prefix, and start value
  4. PageLabelsTree - Number tree parser for /PageLabels with /Nums and /Kids support
  5. OcProperties - Stub for OCG implementation (delegated to dedicated bead)
  6. Catalog - Main catalog struct with all required and optional fields

Number Tree Implementation

  • Parses /Nums arrays (leaf nodes with alternating key-value pairs)
  • Supports /Kids arrays (internal nodes for recursive tree traversal)
  • Provides get_label_with_start() and get_label() methods for lookup
  • Correctly formats roman numerals (uppercase/lowercase) and letter sequences

Page Label Formatting

  • Decimal arabic numerals: 1, 2, 3, ...
  • Roman uppercase: I, II, III, IV, ...
  • Roman lowercase: i, ii, iii, iv, ...
  • Letters uppercase: A, B, C, ..., Z, AA, AB, ...
  • Letters lowercase: a, b, c, ..., z, aa, bb, ...
  • Supports prefixes (e.g., "front-i", "Appendix-ii")

Acceptance Criteria Status

Criterion Status Notes
PageLabels number tree with mixed styles ✅ PASS Test test_page_labels_tree_get_label passes
Tagged PDF sets is_tagged = true ✅ PASS Test test_parse_catalog_tagged_pdf passes
No /Outlines returns None (not error) ✅ PASS Test test_parse_catalog_optional_fields_missing passes
/Version 2.0 parsed correctly ✅ PASS Test test_parse_catalog_with_version passes
No /Root emits STRUCT_MISSING_KEY ✅ PASS Test test_parse_catalog_missing_pages returns Error
proptest: random PdfObject never panics ✅ PASS All 6 proptests pass
INV-8 maintained (no panics) ✅ PASS All errors return Result with diagnostics

Test Results

running 27 tests
test parser::catalog::tests::test_catalog_new ... ok
test parser::catalog::tests::test_letters_edge_cases ... ok
test parser::catalog::tests::test_mark_info_default ... ok
test parser::catalog::tests::test_mark_info_parse ... ok
test parser::catalog::tests::test_page_label_format ... ok
test parser::catalog::tests::test_page_label_format_with_prefix ... ok
test parser::catalog::tests::test_page_label_style_format ... ok
test parser::catalog::tests::test_page_labels_tree_empty ... ok
test parser::catalog::tests::test_page_label_parse ... ok
test parser::catalog::tests::test_page_labels_tree_get_label ... ok
test parser::catalog::tests::test_page_labels_tree_with_prefix ... ok
test parser::catalog::tests::test_parse_catalog_not_a_dict ... ok
test parser::catalog::tests::test_parse_catalog_missing_pages ... ok
test parser::catalog::tests::test_page_label_style_from_name ... ok
test parser::catalog::tests::test_parse_catalog_optional_fields_missing ... ok
test parser::catalog::tests::test_page_labels_tree_parse_nums ... ok
test parser::catalog::tests::test_parse_catalog_resolve_error ... ok
test parser::catalog::tests::test_parse_catalog_tagged_pdf ... ok
test parser::catalog::tests::test_parse_catalog_with_version ... ok
test parser::catalog::tests::test_parse_catalog_success ... ok
test parser::catalog::tests::test_roman_numerals_edge_cases ... ok
test parser::catalog::proptests::fuzz_letters_no_panics ... ok
test parser::catalog::proptests::fuzz_roman_numerals_no_panics ... ok
test parser::catalog::proptests::fuzz_mark_info_parse_no_panics ... ok
test parser::catalog::proptests::fuzz_page_labels_tree_parse_no_panics ... ok
test parser::catalog::proptests::fuzz_page_label_parse_no_panics ... ok
test parser::catalog::proptests::fuzz_parse_catalog_no_panics ... ok

test result: ok. 27 passed; 0 failed; 0 ignored; 0 measured

Additional Fixes

Fixed compilation errors in crates/pdftract-core/src/parser/stream.rs:

  • Replaced PdfObject::Int with PdfObject::Integer
  • Wrapped filter arrays in PdfObject::Array(...)

References

  • Plan section: Phase 1.4 line 1111 (document catalog from /Root); line 1129 (PageLabels)
  • PDF spec 7.7.2 (Document Catalog)
  • PDF spec 7.9.7 (Number Trees)
  • INV-8 (Never panic on malformed input)