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
//! Parser for the PDF `/DA` (default appearance) string.
//!
//! qpdf correspondence: QPDFFormFieldObjectHelper.cc default-appearance parsing split from the form-field helper.
//!
//! A `/DA` value is a small content-stream fragment such as
//! `/Helv 0 Tf 0 g` that sets the font, size, and colour used to render
//! text in a form field. This module tokenises the fragment with the
//! shared qpdf-shaped content parser callbacks and extracts the
//! structured [`DefaultAppearance`] value.
//!
//! # Inheritance
//!
//! Call [`parse_default_appearance`] with **already-inherited** `/DA` bytes.
//! Inheritance resolution (falling back to the `/AcroForm` root `/DA` when a
//! field-level `/DA` is absent) is the caller's responsibility.
use crate::content_stream::{parse_content_operations_with_recoverable_warnings, ParseControl};
use crate::ObjectHandle;
// ── Public types ─────────────────────────────────────────────────────────────
/// Colour model for text rendering in a form field.
///
/// Corresponds to the `g`, `rg`, and `k` PDF colour operators.
/// The default (when the `/DA` string contains no colour operator) is
/// [`TextColor::Gray`]`(0.0)` (opaque black).
#[derive(Debug, Clone, PartialEq)]
pub enum TextColor {
/// Greyscale: 0.0 = black, 1.0 = white.
Gray(f64),
/// Device RGB: (red, green, blue), each in `[0.0, 1.0]`.
Rgb(f64, f64, f64),
/// Device CMYK: (cyan, magenta, yellow, black), each in `[0.0, 1.0]`.
Cmyk(f64, f64, f64, f64),
}
/// Structured representation of a parsed `/DA` (default appearance) string.
///
/// Pass **already-inherited** `/DA` bytes to [`parse_default_appearance`].
/// When a field-level `/DA` is absent the caller should fall back to the
/// `/AcroForm` root `/DA` before calling this function.
#[derive(Debug, Clone, PartialEq)]
pub struct DefaultAppearance {
/// Font resource name, without the leading `/` (e.g. `b"Helv"`).
///
/// `None` when the `/DA` string contains no `Tf` operator or the operands
/// are malformed. The caller should substitute a default font.
pub font_name: Option<Vec<u8>>,
/// The `Tf` operator's raw size operand, in points. This is the literal
/// parsed value even when it falls outside the accepted range described
/// under [`auto_size`](Self::auto_size) (for example `0.0`, a negative
/// value, or `1000.0`); check `auto_size` before using this field, since
/// an out-of-range value is not a usable point size.
pub font_size: f64,
/// `true` when the field's size should be chosen automatically instead
/// of using [`font_size`](Self::font_size) directly.
///
/// This holds whenever `font_size` falls outside the open interval
/// `(1.0, 1000.0)` — not just `font_size == 0.0` — matching qpdf's
/// accepted range for an explicit `Tf` operand. `0.0`, a negative
/// value, exactly `1.0`, exactly `1000.0`, and anything above `1000.0`
/// are all auto-size.
pub auto_size: bool,
/// Text colour. Defaults to [`TextColor::Gray`]`(0.0)` (black).
pub color: TextColor,
}
// ── Public function ──────────────────────────────────────────────────────────
/// Parse a `/DA` content-stream fragment into a [`DefaultAppearance`].
///
/// The argument should be the **already-inherited** `/DA` bytes (field-level
/// `/DA` if present, otherwise the `/AcroForm` root `/DA`).
///
/// Malformed or unrecognised tokens are silently skipped. When an operator
/// appears more than once the **last** occurrence wins.
///
/// # Examples
///
/// ```
/// use flpdf::{parse_default_appearance, TextColor};
///
/// let da = parse_default_appearance(b"/Helv 0 Tf 0 g");
/// assert_eq!(da.font_name.as_deref(), Some(b"Helv" as &[u8]));
/// assert!(da.auto_size);
/// assert_eq!(da.color, TextColor::Gray(0.0));
/// ```
pub fn parse_default_appearance(da: &[u8]) -> DefaultAppearance {
let mut font_name: Option<Vec<u8>> = None;
let mut font_size: f64 = 0.0;
let mut auto_size: bool = true;
let mut color: TextColor = TextColor::Gray(0.0);
// qpdf's default-appearance finder uses a warning-and-continue tokenizer
// context (`QPDFFormFieldObjectHelper.cc:804-810`), so malformed tokens do
// not drop later operators. Ignore the final structural error for this
// best-effort public API, preserving its "skip malformed / last wins"
// contract.
let _ = parse_content_operations_with_recoverable_warnings(da, |operands, operator| {
match operator {
b"Tf" => {
// Operands: /FontName size. PDF operators consume their operands
// from the top of the stack, so read the **last** two operands
// (`[.., name, size]`) rather than the first two — any leading
// dangling operands (from malformed runs) must not be mistaken
// for `Tf`'s arguments. `Tf` is only meaningful when both a name
// and a numeric size are present, so update all three fields
// together; a malformed `Tf` (missing/typed operand) is ignored
// wholesale rather than partially applied.
if let [.., name, size] = operands {
if let (Some(name), Some(size)) = (name.as_name(), obj_as_f64(size)) {
font_name = Some(name.to_vec());
font_size = size;
// qpdf's TfFinder only accepts an explicit Tf
// operand within the open interval (1.0, 1000.0)
// (`QPDFFormFieldObjectHelper.cc:704-710`); a value
// at or outside those bounds (0, a negative size,
// 1000, or larger) is auto-size, not just an
// operand of exactly 0.0.
auto_size = !(size > 1.0 && size < 1000.0);
}
}
}
b"g" => {
// Greyscale: g (1 operand — top of stack)
if let Some(gray) = operands.last().and_then(obj_as_f64) {
color = TextColor::Gray(gray);
}
}
b"rg" => {
// Device RGB: r g b (3 operands — top of stack)
if let [.., r, g, b] = operands {
if let (Some(r), Some(g), Some(b)) =
(obj_as_f64(r), obj_as_f64(g), obj_as_f64(b))
{
color = TextColor::Rgb(r, g, b);
}
}
}
b"k" => {
// Device CMYK: c m y k (4 operands — top of stack)
if let [.., c, m, y, k] = operands {
if let (Some(c), Some(m), Some(y), Some(k)) =
(obj_as_f64(c), obj_as_f64(m), obj_as_f64(y), obj_as_f64(k))
{
color = TextColor::Cmyk(c, m, y, k);
}
}
}
_ => {}
}
Ok(ParseControl::Continue)
});
DefaultAppearance {
font_name,
font_size,
auto_size,
color,
}
}
// ── Private helpers ──────────────────────────────────────────────────────────
/// Convert a PDF [`ObjectHandle`] (Integer or Real) to `f64`.
///
/// Returns `None` for any other object type, including indirect references
/// (which do not appear in content-stream fragments).
fn obj_as_f64(obj: &ObjectHandle) -> Option<f64> {
obj.as_real().or_else(|| obj.as_integer().map(|i| i as f64))
}
// ── Tests ────────────────────────────────────────────────────────────────────
#[cfg(test)]
mod tests {
use super::*;
/// Helper: compare two f64 values within a small epsilon.
fn approx_eq(a: f64, b: f64) -> bool {
(a - b).abs() < 1e-9
}
#[test]
fn helv_auto_size_black() {
// '/Helv 0 Tf 0 g' — canonical auto-size black text
let da = parse_default_appearance(b"/Helv 0 Tf 0 g");
assert_eq!(da.font_name.as_deref(), Some(b"Helv" as &[u8]));
assert!(approx_eq(da.font_size, 0.0));
assert!(da.auto_size);
assert_eq!(da.color, TextColor::Gray(0.0));
}
#[test]
fn helv_size12_rgb_red() {
// '/Helv 12 Tf 1 0 0 rg' — 12pt, red
let da = parse_default_appearance(b"/Helv 12 Tf 1 0 0 rg");
assert_eq!(da.font_name.as_deref(), Some(b"Helv" as &[u8]));
assert!(approx_eq(da.font_size, 12.0));
assert!(!da.auto_size);
assert_eq!(da.color, TextColor::Rgb(1.0, 0.0, 0.0));
}
#[test]
fn courier_cmyk_black() {
// '/Cour 10 Tf 0 0 0 1 k' — 10pt, CMYK black
let da = parse_default_appearance(b"/Cour 10 Tf 0 0 0 1 k");
assert_eq!(da.font_name.as_deref(), Some(b"Cour" as &[u8]));
assert!(approx_eq(da.font_size, 10.0));
assert!(!da.auto_size);
assert_eq!(da.color, TextColor::Cmyk(0.0, 0.0, 0.0, 1.0));
}
#[test]
fn empty_input_returns_defaults() {
let da = parse_default_appearance(b"");
assert_eq!(da.font_name, None);
assert!(approx_eq(da.font_size, 0.0));
assert!(da.auto_size);
assert_eq!(da.color, TextColor::Gray(0.0));
}
#[test]
fn malformed_tokens_fallback_to_defaults() {
// Garbage bytes that the parser cannot make into a valid Tf/g/rg/k
let da = parse_default_appearance(b"not valid pdf tokens !@#");
assert_eq!(da.font_name, None);
assert!(approx_eq(da.font_size, 0.0));
assert!(da.auto_size);
assert_eq!(da.color, TextColor::Gray(0.0));
}
#[test]
fn real_font_size() {
// '/F1 11.5 Tf' — Real operand for size
let da = parse_default_appearance(b"/F1 11.5 Tf");
assert_eq!(da.font_name.as_deref(), Some(b"F1" as &[u8]));
assert!(approx_eq(da.font_size, 11.5));
assert!(!da.auto_size);
// No colour operator → default
assert_eq!(da.color, TextColor::Gray(0.0));
}
#[test]
fn last_color_wins() {
// Two colour operators — last one (k) should win
let da = parse_default_appearance(b"/Helv 12 Tf 1 0 0 rg 0 0 0 1 k");
assert_eq!(da.color, TextColor::Cmyk(0.0, 0.0, 0.0, 1.0));
}
#[test]
fn last_tf_wins() {
// Two Tf operators — last one should win
let da = parse_default_appearance(b"/Helv 12 Tf /Cour 9 Tf");
assert_eq!(da.font_name.as_deref(), Some(b"Cour" as &[u8]));
assert!(approx_eq(da.font_size, 9.0));
}
#[test]
fn grey_color_operator() {
// Explicit greyscale value
let da = parse_default_appearance(b"/Helv 10 Tf 0.5 g");
assert_eq!(da.color, TextColor::Gray(0.5));
}
#[test]
fn missing_tf_operands_skipped() {
// Tf with no operands → font_name stays None, auto_size stays true
let da = parse_default_appearance(b"Tf 0 g");
assert_eq!(da.font_name, None);
assert!(da.auto_size);
assert_eq!(da.color, TextColor::Gray(0.0));
}
#[test]
fn malformed_trailing_tf_does_not_partially_overwrite() {
// A valid `Tf` followed by a malformed one (`/Bad Tf`, missing the
// numeric size) must be ignored wholesale: the earlier valid pair is
// preserved rather than producing the never-present (Bad, 12) combo.
let da = parse_default_appearance(b"/Helv 12 Tf /Bad Tf");
assert_eq!(da.font_name.as_deref(), Some(b"Helv" as &[u8]));
assert!(approx_eq(da.font_size, 12.0));
assert!(!da.auto_size);
}
#[test]
fn leading_dangling_operands_use_stack_top() {
// PDF operators consume operands from the top of the stack. When extra
// leading operands precede an operator (malformed run, unrecognised
// sequence), the operator's real arguments are the *last* ones. Reading
// from the front would mistake the dangling `99 88` / `7 7` for the
// operands and either skip or mis-parse the operator.
let da = parse_default_appearance(b"99 88 /Helv 12 Tf 7 7 0.25 g");
assert_eq!(da.font_name.as_deref(), Some(b"Helv" as &[u8]));
assert!(approx_eq(da.font_size, 12.0));
assert!(!da.auto_size);
assert_eq!(da.color, TextColor::Gray(0.25));
}
#[test]
fn malformed_token_midstream_does_not_drop_later_operators() {
// A stray `}` is an unparseable token. The shared parser would fuse on
// it, but `/DA` parsing enables recovery so later operators still apply
// ("skip malformed, last-wins" — matching qpdf's allow_bad scanning).
// Here the `rg` colour after the bad token must still take effect.
let da = parse_default_appearance(b"/Helv 12 Tf } 1 0 0 rg");
assert_eq!(da.font_name.as_deref(), Some(b"Helv" as &[u8]));
assert!(approx_eq(da.font_size, 12.0));
assert_eq!(da.color, TextColor::Rgb(1.0, 0.0, 0.0));
}
#[test]
fn leading_dangling_operands_rgb_and_cmyk_use_stack_top() {
// rg / k must also read their 3 / 4 operands from the top of the stack.
let rgb = parse_default_appearance(b"42 1.0 0.0 0.0 rg");
assert_eq!(rgb.color, TextColor::Rgb(1.0, 0.0, 0.0));
let cmyk = parse_default_appearance(b"9 9 0.1 0.2 0.3 0.4 k");
assert_eq!(cmyk.color, TextColor::Cmyk(0.1, 0.2, 0.3, 0.4));
}
// ── Tf acceptance range (qpdf TfFinder::handleToken, (1.0, 1000.0) ──────
// exclusive) ────────────────────────────────────────────────────────────
#[test]
fn tf_boundary_exactly_one_is_auto_size() {
// qpdf's acceptance test is `last_num > 1.0`, so exactly 1.0 is
// rejected (auto-size), not accepted.
let da = parse_default_appearance(b"/Helv 1 Tf");
assert!(approx_eq(da.font_size, 1.0));
assert!(da.auto_size, "exactly 1.0 must be treated as auto-size");
}
#[test]
fn tf_boundary_exactly_1000_is_auto_size() {
// qpdf's acceptance test is `last_num < 1000.0`, so exactly 1000.0
// is rejected (auto-size), not accepted.
let da = parse_default_appearance(b"/Helv 1000 Tf");
assert!(approx_eq(da.font_size, 1000.0));
assert!(da.auto_size, "exactly 1000.0 must be treated as auto-size");
}
#[test]
fn tf_just_inside_accepted_range_is_not_auto_size() {
let low = parse_default_appearance(b"/Helv 1.001 Tf");
assert!(!low.auto_size);
assert!(approx_eq(low.font_size, 1.001));
let high = parse_default_appearance(b"/Helv 999.999 Tf");
assert!(!high.auto_size);
assert!(approx_eq(high.font_size, 999.999));
}
#[test]
fn tf_negative_operand_is_auto_size() {
// qpdf treats a negative Tf operand as out of range too (only
// `last_num > 1.0` is accepted), unlike flpdf's previous
// `font_size == 0.0`-only check, which would have left a negative
// size unmodified.
let da = parse_default_appearance(b"/Helv -5 Tf");
assert!(approx_eq(da.font_size, -5.0));
assert!(da.auto_size, "a negative Tf operand must be auto-size");
}
#[test]
fn tf_operand_beyond_1000_is_auto_size() {
let da = parse_default_appearance(b"/Helv 1200 Tf");
assert!(approx_eq(da.font_size, 1200.0));
assert!(da.auto_size, "an operand >= 1000.0 must be auto-size");
}
}