defmodule Pdf.Reader.XRef.Stream do
@moduledoc """
Parses a PDF 1.5+ compressed cross-reference stream (`/Type /XRef`).
Per PDF 1.7 ISO 32000-1 § 7.5.8 "Cross-Reference Streams":
- The stream object dictionary must have `/Type /XRef`.
- Required fields: `/Size` (total object count), `/W [w1 w2 w3]` (byte widths).
- Optional `/Index [first count ...]` — subsection ranges; default `[0 /Size]`.
- Optional `/Prev` — byte offset of previous xref section (chain support).
- The stream body (after decoding all filters) contains exactly
`w1 + w2 + w3` bytes per entry:
- Field 1 (w1 bytes): entry type. If w1 = 0, type is implicitly 1.
- Field 2 (w2 bytes): meaning depends on type.
- Field 3 (w3 bytes): meaning depends on type.
Entry types (§ 7.5.8 Table 18):
- **Type 0** (free): f2 = next free object number, f3 = generation when reused.
- **Type 1** (in-use, classic): f2 = byte offset, f3 = generation number.
- **Type 2** (compressed): f2 = object number of containing ObjStm, f3 = index within it.
This module decodes the stream body using `Pdf.Reader.Filter.apply_chain/3`,
which handles `FlateDecode` and PNG predictors transparently (batch 1 impl).
"""
alias Pdf.Reader.Filter
# ---------------------------------------------------------------------------
# Public API
# ---------------------------------------------------------------------------
@doc """
Parses a `/Type /XRef` stream object tuple into an xref entries map.
Accepts `{:stream, dict, raw_bytes}` where `raw_bytes` is the still-encoded
(FlateDecode-compressed) stream body.
Returns:
- `{:ok, entries_map}` — map of `{obj_num, gen_num} => entry`
- `{:error, :not_an_xref_stream}` — dict does not have `/Type /XRef`
- `{:error, reason}` — filter/decoding error propagated from the filter chain
"""
@spec parse({:stream, map(), binary()}) ::
{:ok, %{Pdf.Reader.Document.ref() => Pdf.Reader.Document.xref_entry()}}
| {:error, term()}
def parse({:stream, dict, raw_bytes}) do
case dict["Type"] do
{:name, "XRef"} ->
do_parse(dict, raw_bytes)
_ ->
{:error, :not_an_xref_stream}
end
end
# ---------------------------------------------------------------------------
# Internal
# ---------------------------------------------------------------------------
defp do_parse(dict, raw_bytes) do
# Decode the stream body through the filter chain (usually FlateDecode).
with {:ok, decoded} <- decode_stream(dict, raw_bytes) do
w = extract_w(dict)
index_pairs = extract_index(dict)
entries = parse_entries(decoded, w, index_pairs, %{})
{:ok, entries}
end
end
# Apply any filters listed in the stream dict to decode the body.
# Filter names may be {:name, "FlateDecode"} tuples (from the parser) or plain
# binary strings. Filter.apply_chain/3 handles both via resolve_module/1.
defp decode_stream(dict, raw_bytes) do
filter = Map.get(dict, "Filter")
parms = Map.get(dict, "DecodeParms")
if is_nil(filter) do
# No filter — body is already in raw (uncompressed) form.
{:ok, raw_bytes}
else
Filter.apply_chain(raw_bytes, filter, parms || %{})
end
end
# Extract /W as a 3-tuple {w1, w2, w3}.
# Per spec, each may be 0 to indicate a missing (defaulted) field.
defp extract_w(%{"W" => [w1, w2, w3]}), do: {w1, w2, w3}
defp extract_w(_), do: {1, 2, 1}
# Extract /Index as a list of {first, count} pairs.
# Default: [{0, Size}].
defp extract_index(%{"Index" => index_list, "Size" => _size}) do
pair_list(index_list)
end
defp extract_index(%{"Size" => size}) do
[{0, size}]
end
defp extract_index(_), do: [{0, 0}]
defp pair_list([]), do: []
defp pair_list([first, count | rest]), do: [{first, count} | pair_list(rest)]
# Walk all subsections in order.
defp parse_entries(body, w, index_pairs, acc) do
Enum.reduce(index_pairs, {body, acc}, fn {first, count}, {remaining, map} ->
{rest, new_map} = read_subsection(remaining, w, first, count, map)
{rest, new_map}
end)
|> elem(1)
end
# Read `count` entries for the subsection starting at object number `first`.
defp read_subsection(body, w, first, count, acc) do
Enum.reduce(0..(count - 1), {body, acc}, fn i, {remaining, map} ->
{entry, rest} = read_entry(remaining, w, first + i)
{rest, Map.put(map, elem(entry, 0), elem(entry, 1))}
end)
end
# Read a single xref stream entry. Returns {{key, value}, rest_binary}.
# PDF 1.7 § 7.5.8 Table 18 — entry field semantics.
#
# Note: Elixir binary pattern matching requires compile-time-known sizes.
# We use `read_uint/2` to handle runtime-variable field widths.
defp read_entry(body, {w1, w2, w3}, obj_num) do
# Read field 1 (type): if w1 == 0, type is implicitly 1 (in_use).
{type, after_type} =
if w1 == 0 do
{1, body}
else
{t, rest} = read_uint(body, w1)
{t, rest}
end
# Read field 2 (f2).
{f2, after_f2} = read_uint(after_type, w2)
# Read field 3 (f3): if w3 == 0, default is 0.
{f3, after_f3} =
if w3 == 0 do
{0, after_f2}
else
read_uint(after_f2, w3)
end
# Map type → entry shape, key → {obj_num, gen_num}.
case type do
0 ->
# Type 0: free entry. gen = f3 (gen for next use).
key = {obj_num, f3}
{{key, :free}, after_f3}
1 ->
# Type 1: in_use. f2 = byte offset, f3 = generation.
key = {obj_num, f3}
{{key, {:in_use, f2, f3}}, after_f3}
2 ->
# Type 2: compressed. f2 = ObjStm obj_num, f3 = index within ObjStm.
# Generation is always 0 for compressed objects (§ 7.5.8).
key = {obj_num, 0}
{{key, {:compressed, f2, f3}}, after_f3}
_other ->
# Unknown type — treat as free (spec says future types may be added).
key = {obj_num, f3}
{{key, :free}, after_f3}
end
end
# Read `n` bytes from `binary` as a big-endian unsigned integer.
# Returns {value, rest_binary}.
# Uses binary_part/3 + :binary.decode_unsigned/2 to avoid compile-time
# size constraints in pattern matching.
defp read_uint(binary, n) when n > 0 and byte_size(binary) >= n do
field = binary_part(binary, 0, n)
rest = binary_part(binary, n, byte_size(binary) - n)
value = :binary.decode_unsigned(field, :big)
{value, rest}
end
end
