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
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
//! High-level outline (`/Outlines`) document helper.
//!
//! [`OutlineDocumentHelper`] wraps a `&mut Pdf<R>` and exposes a cycle-safe,
//! iterable handle over the document outline (bookmark) tree, mirroring qpdf's
//! `QPDFOutlineDocumentHelper`. It materializes the tree into owned
//! [`OutlineNode`]s; navigation (`children`, `parent`, `count`, `dest`) lives on
//! each node, mirroring `QPDFOutlineObjectHelper`.
//!
//! # Example
//!
//! ```no_run
//! use flpdf::Pdf;
//! use std::io::Cursor;
//!
//! # fn f(bytes: Vec<u8>) -> flpdf::Result<()> {
//! let mut pdf = Pdf::open(Cursor::new(bytes))?;
//! if pdf.outline().has_outlines()? {
//! pdf.outline().walk(|node, depth| {
//! println!("{:indent$}{}", "", node.title, indent = depth * 2);
//! })?;
//! }
//! # Ok(())
//! # }
//! ```
use crate::name_number_tree::read_name_tree;
use crate::{Object, ObjectRef, Pdf, Result};
use std::collections::BTreeSet;
use std::io::{Read, Seek};
/// Default recursion limit for outline materialization. Matches
/// [`crate::outline::DEFAULT_MAX_OUTLINE_DEPTH`]. True unbounded/iterative deep
/// walking (1000+ levels, cycle diagnostics) is not currently supported.
pub const DEFAULT_MAX_OUTLINE_DEPTH: usize = crate::outline::DEFAULT_MAX_OUTLINE_DEPTH;
/// Indirection/`/D` nesting bound when resolving a destination. Mirrors the
/// constant in `outline_dest_remap`. Only exists to make malformed/cyclic
/// `/D` structures terminate instead of overflowing the stack.
const MAX_DEST_RESOLVE_DEPTH: usize = 64;
/// One materialized node of the outline tree (a bookmark).
///
/// Mirrors qpdf's `QPDFOutlineObjectHelper`. `children` are the resolved
/// `/First`->`/Next` chain; `parent` is the owning item's ref (`None` for
/// top-level items). `count` is the raw `/Count` value
/// (0 when absent), whose sign indicates open/closed per ISO 32000-1 section
/// 12.3.3.
#[derive(Debug, Clone, PartialEq)]
pub struct OutlineNode {
/// Object ref of this outline item dictionary.
pub object_ref: ObjectRef,
/// Zero for top-level items, increasing per nesting level.
pub depth: usize,
/// `/Title` decoded with `from_utf8_lossy`; empty string when absent.
/// Resolves one level of indirection (an indirect `/Title` ref).
pub title: String,
/// Raw `/Count` value; `0` when absent.
pub count: i64,
/// Parent item ref; `None` for top-level items.
pub parent: Option<ObjectRef>,
/// Resolved explicit destination (`/Dest`, or a `/A` GoTo action's `/D`),
/// or `None` when absent or a still-unresolved named destination.
pub dest: Option<Dest>,
/// Child nodes in `/First`->`/Next` order.
pub children: Vec<OutlineNode>,
}
/// A resolved explicit destination, e.g. `[pageRef /Fit ...]`. Mirrors the
/// array form qpdf `getDest` yields after resolving `/Dest`, `/A /GoTo /D`, and
/// named destinations.
#[derive(Debug, Clone, PartialEq)]
pub struct Dest {
/// The explicit destination array. Element 0 is normally the page ref.
pub array: Vec<Object>,
}
impl Dest {
/// The destination page ref (array element 0), if it is an indirect ref.
/// Mirrors qpdf `getDestPage`.
pub fn page(&self) -> Option<ObjectRef> {
self.array.first().and_then(Object::as_ref_id)
}
}
/// High-level outline helper for a document. See module docs.
pub struct OutlineDocumentHelper<'a, R: Read + Seek> {
pdf: &'a mut Pdf<R>,
}
impl<'a, R: Read + Seek> OutlineDocumentHelper<'a, R> {
/// Wrap a document for outline access. Prefer [`Pdf::outline`].
pub fn new(pdf: &'a mut Pdf<R>) -> Self {
Self { pdf }
}
/// Return `true` if the catalog has an `/Outlines` dictionary with at least
/// one top-level item (a resolvable `/First`). Mirrors qpdf `hasOutlines`.
///
/// # Errors
///
/// Propagates any error from resolving the catalog and `/Outlines`
/// objects (for example I/O or parse failures surfaced by [`Pdf::resolve_borrowed`]).
pub fn has_outlines(&mut self) -> Result<bool> {
Ok(self.outline_root_first()?.is_some())
}
/// Resolve the catalog `/Outlines` dict's `/First` child ref, if any.
fn outline_root_first(&mut self) -> Result<Option<ObjectRef>> {
let Some(catalog_ref) = self.pdf.root_ref() else {
return Ok(None);
};
let Object::Dictionary(catalog) = self.pdf.resolve_borrowed(catalog_ref)? else {
return Ok(None);
};
let Some(outlines_ref) = catalog.get_ref("Outlines") else {
return Ok(None);
};
let Object::Dictionary(root) = self.pdf.resolve_borrowed(outlines_ref)? else {
return Ok(None);
};
Ok(root.get_ref("First"))
}
/// Materialize and return the top-level outline nodes (qpdf
/// `getTopLevelOutlines`). "root" is this top-level vector; the `/Outlines`
/// dict itself is not a navigable item and is not wrapped.
///
/// # Errors
///
/// Returns [`crate::Error::Unsupported`] if the outline nesting depth exceeds
/// [`DEFAULT_MAX_OUTLINE_DEPTH`]. Propagates any error from resolving outline
/// objects (for example I/O or parse failures surfaced by [`Pdf::resolve`]).
pub fn get_root(&mut self) -> Result<Vec<OutlineNode>> {
self.get_root_with_max_depth(DEFAULT_MAX_OUTLINE_DEPTH)
}
/// Like [`get_root`](Self::get_root) with a caller-supplied recursion limit.
///
/// # Errors
///
/// Returns [`crate::Error::Unsupported`] if the outline nesting depth exceeds
/// `max_depth`. Propagates any error from resolving outline objects (for
/// example I/O or parse failures surfaced by [`Pdf::resolve`]).
pub fn get_root_with_max_depth(&mut self, max_depth: usize) -> Result<Vec<OutlineNode>> {
let Some(first) = self.outline_root_first()? else {
return Ok(Vec::new());
};
let mut visited = BTreeSet::new();
self.build_siblings(first, 0, None, &mut visited, max_depth)
}
/// Build a `/First`->`/Next` sibling chain into owned nodes.
fn build_siblings(
&mut self,
start: ObjectRef,
depth: usize,
parent: Option<ObjectRef>,
visited: &mut BTreeSet<ObjectRef>,
max_depth: usize,
) -> Result<Vec<OutlineNode>> {
if depth >= max_depth {
return Err(crate::Error::Unsupported(format!(
"outline depth exceeds maximum of {max_depth} at {start}"
)));
}
let mut nodes = Vec::new();
let mut current = Some(start);
while let Some(current_ref) = current {
if !visited.insert(current_ref) {
break; // cycle - stop this chain
}
let Object::Dictionary(dict) = self.pdf.resolve_borrowed(current_ref)? else {
break;
};
// IMPORTANT (borrow order): `dict` borrows `self.pdf` (it is a
// `resolve_borrowed` reference). Extract EVERY value we need into
// owned locals here, ending the `dict` borrow, BEFORE any
// `self.pdf.resolve(...)` call below - otherwise the borrow checker
// rejects it. A later task adds `dest_src`/`action_src` here.
let first = dict.get_ref("First");
let next = dict.get_ref("Next");
let title_src = dict.get("Title").cloned();
let count_src = dict.get("Count").cloned();
let dest_src = dict.get("Dest").cloned();
let action_src = dict.get("A").cloned();
// `dict` (and thus the &mut self.pdf borrow) is no longer used past
// this point - owned values only from here on.
let title = resolve_title(self.pdf, title_src)?;
let count = resolve_int(self.pdf, count_src)?.unwrap_or(0);
let dest = self.resolve_node_dest(dest_src, action_src)?;
let children = match first {
Some(first) => {
self.build_siblings(first, depth + 1, Some(current_ref), visited, max_depth)?
}
None => Vec::new(),
};
nodes.push(OutlineNode {
object_ref: current_ref,
depth,
title,
count,
parent,
dest,
children,
});
current = next;
}
Ok(nodes)
}
/// Resolve a node's destination from `/Dest`, else a `/A` GoTo action's `/D`.
/// Named/string destinations are resolved in a later task (return `None` here).
fn resolve_node_dest(
&mut self,
dest: Option<Object>,
action: Option<Object>,
) -> Result<Option<Dest>> {
if let Some(d) = dest {
if let Some(found) = self.dest_from_value(&d, MAX_DEST_RESOLVE_DEPTH)? {
return Ok(Some(found));
}
}
if let Some(a) = action {
let action_obj = match a {
Object::Reference(r) => self.pdf.resolve(r)?,
other => other,
};
if let Some(adict) = action_obj.as_dict() {
let is_goto = matches!(adict.get("S"), Some(Object::Name(n)) if n == b"GoTo");
if is_goto {
if let Some(d) = adict.get("D").cloned() {
if let Some(found) = self.dest_from_value(&d, MAX_DEST_RESOLVE_DEPTH)? {
return Ok(Some(found));
}
}
}
}
}
Ok(None)
}
/// Resolve a destination value (array / indirect / dict `/D`) to a [`Dest`].
/// Named (`Name`/`String`) destinations are resolved against the catalog name
/// tree / legacy `/Dests` dict via [`Self::resolve_named_dest`].
fn dest_from_value(&mut self, value: &Object, depth: usize) -> Result<Option<Dest>> {
if depth == 0 {
return Ok(None);
}
match value {
Object::Array(arr) => Ok(Some(Dest { array: arr.clone() })),
Object::Reference(r) => {
let concrete = self.pdf.resolve(*r)?;
self.dest_from_value(&concrete, depth - 1)
}
Object::Dictionary(d) => match d.get("D").cloned() {
Some(inner) => self.dest_from_value(&inner, depth - 1),
None => Ok(None),
},
Object::Name(name) => self.resolve_named_dest(name, depth),
Object::String(name) => self.resolve_named_dest(name, depth),
_ => Ok(None),
}
}
/// Resolve a named destination `name` to an explicit [`Dest`].
///
/// Tries the modern catalog `/Names`->`/Dests` name tree first (PDF 1.2),
/// then the legacy catalog `/Dests` dictionary (PDF 1.1). A name-tree or
/// `/Dests` value may be the dest array directly or a `<< /D array >>` dict.
///
/// `depth` is the remaining indirection/`/D` budget threaded from
/// [`Self::dest_from_value`]; the post-lookup value is resolved with
/// `depth - 1` so a cyclic named mapping (e.g. legacy `/Dests` `/a -> /b`,
/// `/b -> /a`) strictly decreases the budget and terminates at the bound
/// instead of overflowing the stack.
fn resolve_named_dest(&mut self, name: &[u8], depth: usize) -> Result<Option<Dest>> {
// 1. Modern: catalog /Names /Dests name tree (PDF 1.2+). /Names may be
// inline or an indirect ref; catalog_value handles both.
if let Some(Object::Dictionary(mut names)) = self.catalog_value("Names")? {
if let Some(dests_root) = names.remove("Dests") {
let entries = read_name_tree(
self.pdf,
dests_root,
|_pdf, value| Ok(Some(value)),
DEFAULT_MAX_OUTLINE_DEPTH,
)?;
// Re-reads the whole name tree per named hop; acceptable because
// each hop strictly decreases `depth` (no visited set needed).
for (key, value) in entries {
if key.as_slice() == name {
return self.dest_from_value(&value, depth - 1);
}
}
}
}
// 2. Legacy: catalog /Dests dict (PDF 1.1).
if let Some(Object::Dictionary(mut dests)) = self.catalog_value("Dests")? {
if let Some(value) = dests.remove(name) {
return self.dest_from_value(&value, depth - 1);
}
}
Ok(None)
}
/// Resolve a catalog key's value to an owned object, following one level of
/// indirection. Returns the value whether the catalog stores it as an
/// indirect reference or as a direct (inline) object — so an inline
/// `/Names`/`/Dests` dictionary is handled as well as the reference form.
fn catalog_value(&mut self, key: &str) -> Result<Option<Object>> {
let Some(catalog_ref) = self.pdf.root_ref() else {
return Ok(None);
};
let Object::Dictionary(catalog) = self.pdf.resolve_borrowed(catalog_ref)? else {
return Ok(None);
};
let Some(value) = catalog.get(key).cloned() else {
return Ok(None);
};
match value {
Object::Reference(r) => Ok(Some(self.pdf.resolve(r)?)),
other => Ok(Some(other)),
}
}
/// Pre-order iterator over every materialized node (owned). Each yielded
/// node has its `children` cleared — the flattened view is linear and
/// `depth` conveys structure; use [`get_root`](Self::get_root) or
/// [`walk`](Self::walk) when you need populated `children`.
///
/// # Errors
///
/// Returns [`crate::Error::Unsupported`] if the outline nesting depth exceeds
/// [`DEFAULT_MAX_OUTLINE_DEPTH`]. Propagates any error from resolving outline
/// objects (for example I/O or parse failures surfaced by [`Pdf::resolve`]).
pub fn iter(&mut self) -> Result<impl Iterator<Item = OutlineNode>> {
let roots = self.get_root()?;
let mut flat = Vec::new();
for node in roots {
flatten_preorder(node, &mut flat);
}
Ok(flat.into_iter())
}
/// Visit every node pre-order, passing `(node, depth)` to `visitor`. The
/// visited nodes have populated `children`. Mirrors a qpdf outline walk.
///
/// For a runnable walkthrough see `examples/walk_outline.rs`.
///
/// # Errors
///
/// Returns [`crate::Error::Unsupported`] if the outline nesting depth exceeds
/// [`DEFAULT_MAX_OUTLINE_DEPTH`]. Propagates any error from resolving outline
/// objects (for example I/O or parse failures surfaced by [`Pdf::resolve`]).
pub fn walk<F: FnMut(&OutlineNode, usize)>(&mut self, mut visitor: F) -> Result<()> {
let roots = self.get_root()?;
for node in &roots {
walk_node(node, &mut visitor);
}
Ok(())
}
}
impl<R: Read + Seek> Pdf<R> {
/// Return a high-level outline helper for this document.
pub fn outline(&mut self) -> OutlineDocumentHelper<'_, R> {
OutlineDocumentHelper::new(self)
}
}
/// Decode an outline `/Title`, resolving one level of indirection (review rule 2).
/// qpdf yields an empty string when absent or not a (resolved) string.
fn resolve_title<R: Read + Seek>(pdf: &mut Pdf<R>, value: Option<Object>) -> Result<String> {
let resolved = match value {
Some(Object::Reference(r)) => Some(pdf.resolve(r)?),
other => other,
};
Ok(match resolved {
Some(Object::String(bytes)) => String::from_utf8_lossy(&bytes).into_owned(),
_ => String::new(),
})
}
/// Push `node` (with `children` taken/emptied) then its descendants, pre-order.
fn flatten_preorder(mut node: OutlineNode, out: &mut Vec<OutlineNode>) {
let children = std::mem::take(&mut node.children);
out.push(node);
for child in children {
flatten_preorder(child, out);
}
}
/// Invoke `visitor(node, node.depth)` then recurse into children, pre-order.
fn walk_node<F: FnMut(&OutlineNode, usize)>(node: &OutlineNode, visitor: &mut F) {
visitor(node, node.depth);
for child in &node.children {
walk_node(child, visitor);
}
}
/// Resolve one level of indirection and read an integer (review rule 2/3).
fn resolve_int<R: Read + Seek>(pdf: &mut Pdf<R>, value: Option<Object>) -> Result<Option<i64>> {
match value {
Some(Object::Reference(r)) => Ok(pdf.resolve(r)?.as_integer()),
Some(other) => Ok(other.as_integer()),
None => Ok(None),
}
}