pdfrum_page/
resources.rs

1//! Named-resource lookup (ISO 32000-1 §7.8.3).
2//!
3//! # A whole-dictionary choice, then a one-level category fallback
4//!
5//! Two separate rules stack here, and conflating them gets real files wrong.
6//!
7//! First, the *dictionary* a form uses is the **first non-null** of its own
8//! `/Resources`, its parent's, and the page's — a whole-dictionary choice,
9//! not a per-category merge. A form with a `/Resources` containing only
10//! `/Font` therefore cannot see the page's `/XObject` through this rule.
11//!
12//! Second, at lookup time a *category* missing from the chosen dictionary
13//! falls back to the page's — but **only one level, and only to the page**. A
14//! category that is present but lacks the name does **not** fall back: the
15//! first dictionary holding the category wins, name or no name.
16
17use crate::names;
18use pdfrum_object::{Dict, Name, Object, Resolve};
19
20/// The resource dictionaries a lookup consults.
21#[derive(Debug, Clone, PartialEq, Default)]
22pub struct Resources {
23    /// The dictionary chosen by the whole-dictionary rule.
24    pub chosen: Option<Dict>,
25    /// The page's, for the one-level category fallback.
26    pub page: Option<Dict>,
27}
28
29impl Resources {
30    /// Choose the dictionary a form will use.
31    ///
32    /// The **first non-null** of the three, which is why a form with any
33    /// `/Resources` at all stops seeing its parent's.
34    #[must_use]
35    pub fn choose(own: Option<Dict>, parent: Option<Dict>, page: Option<Dict>) -> Self {
36        let chosen = own.or(parent).or_else(|| page.clone());
37        Self { chosen, page }
38    }
39
40    /// A page's own resources, where the chosen dictionary and the page's are
41    /// the same.
42    #[must_use]
43    pub fn for_page(page: Option<Dict>) -> Self {
44        Self {
45            chosen: page.clone(),
46            page,
47        }
48    }
49
50    /// The dictionary holding `category`, applying the one-level fallback.
51    #[must_use]
52    pub fn holder<R: Resolve>(&self, category: &Name, r: &R) -> Option<Dict> {
53        if let Some(chosen) = &self.chosen
54            && let Some(found) = chosen.dict(category, r)
55        {
56            // The first dictionary holding the category wins outright, even
57            // when it lacks the name the caller wants.
58            return Some(found);
59        }
60        // Only when the category is *absent* does the page get a turn — and
61        // only when it is a different dictionary.
62        let page = self.page.as_ref()?;
63        if self.chosen.as_ref() == Some(page) {
64            return None;
65        }
66        page.dict(category, r)
67    }
68
69    /// The resolved object a named resource denotes.
70    #[must_use]
71    pub fn find<R: Resolve>(&self, category: &Name, name: &Name, r: &R) -> Option<Object> {
72        let holder = self.holder(category, r)?;
73        Some(holder.get(name, r)?.into_owned())
74    }
75
76    /// The reference a named resource is reached through, when it is
77    /// indirect.
78    ///
79    /// The identity a cache keys on. A resource written inline in the
80    /// resource dictionary has no reference and therefore no identity to
81    /// share, which is exactly right: two inline copies of the same
82    /// dictionary really are two resources.
83    #[must_use]
84    pub fn find_ref<R: Resolve>(
85        &self,
86        category: &Name,
87        name: &Name,
88        r: &R,
89    ) -> Option<pdfrum_object::ObjRef> {
90        match self.holder(category, r)?.raw(name)? {
91            Object::Ref(reference) => Some(*reference),
92            _ => None,
93        }
94    }
95
96    /// The `/ColorSpace` dictionary, which colorspace loading needs by
97    /// itself rather than by name.
98    #[must_use]
99    pub fn color_spaces<R: Resolve>(&self, r: &R) -> Option<Dict> {
100        self.holder(names::COLOR_SPACE, r)
101    }
102}
103
104#[cfg(test)]
105mod tests {
106    // Test fixtures quote the oracle's own vectors, compare floats exactly
107    // where the behaviour being pinned is exact, and index arrays whose
108    // length the fixture itself fixes.
109    #![allow(
110        clippy::unreadable_literal,
111        clippy::float_cmp,
112        clippy::indexing_slicing,
113        clippy::cast_precision_loss,
114        clippy::cast_possible_truncation,
115        reason = "test fixtures quote oracle vectors verbatim and compare exactly"
116    )]
117
118    use super::Resources;
119    use crate::names;
120    use pdfrum_object::{Dict, Name, NoResolve, Object};
121
122    fn category(key: &str, entry: &str) -> Dict {
123        Dict::from_pairs([(
124            Name::from(key),
125            Object::Dict(Dict::from_pairs([(
126                Name::from(entry),
127                Object::Name(Name::from(entry)),
128            )])),
129        )])
130    }
131
132    #[test]
133    fn the_first_non_null_dictionary_wins_whole() {
134        let own = category("Font", "F1");
135        let page = category("XObject", "X1");
136        let res = Resources::choose(Some(own), None, Some(page));
137        // The form's own `/Font` is visible.
138        assert!(
139            res.find(names::FONT, &Name::from("F1"), &NoResolve)
140                .is_some()
141        );
142        // The page's `/XObject` is too, because the category is *absent*
143        // from the chosen dictionary.
144        assert!(
145            res.find(names::XOBJECT, &Name::from("X1"), &NoResolve)
146                .is_some()
147        );
148    }
149
150    #[test]
151    fn a_present_category_lacking_the_name_does_not_fall_back() {
152        let mut own = category("Font", "F1");
153        // The form has an `/XObject` category, but not the name wanted.
154        own.push(
155            Name::from("XObject"),
156            Object::Dict(Dict::from_pairs([(
157                Name::from("Other"),
158                Object::Name(Name::from("Other")),
159            )])),
160        );
161        let page = category("XObject", "X1");
162        let res = Resources::choose(Some(own), None, Some(page));
163        assert!(
164            res.find(names::XOBJECT, &Name::from("X1"), &NoResolve)
165                .is_none(),
166            "a present-but-incomplete category must not fall back"
167        );
168    }
169
170    #[test]
171    fn the_parent_is_consulted_before_the_page() {
172        let parent = category("Font", "PARENT");
173        let page = category("Font", "PAGE");
174        let res = Resources::choose(None, Some(parent), Some(page));
175        assert!(
176            res.find(names::FONT, &Name::from("PARENT"), &NoResolve)
177                .is_some()
178        );
179        assert!(
180            res.find(names::FONT, &Name::from("PAGE"), &NoResolve)
181                .is_none()
182        );
183    }
184
185    #[test]
186    fn a_page_looks_up_only_in_itself() {
187        let page = category("Font", "F1");
188        let res = Resources::for_page(Some(page));
189        assert!(
190            res.find(names::FONT, &Name::from("F1"), &NoResolve)
191                .is_some()
192        );
193        assert!(
194            res.find(names::XOBJECT, &Name::from("X1"), &NoResolve)
195                .is_none()
196        );
197    }
198
199    #[test]
200    fn no_resources_at_all_finds_nothing() {
201        let res = Resources::default();
202        assert!(
203            res.find(names::FONT, &Name::from("F1"), &NoResolve)
204                .is_none()
205        );
206        assert!(res.color_spaces(&NoResolve).is_none());
207    }
208}
pdfrum_page/resources.rs

pdfrum_page/
resources.rs
