NativeElixirPdfUtilities.Outlines (native_elixir_pdf_utilities v0.18.0)

View Source

Reads, writes, and detects PDF document outlines.

PDF viewers commonly call outline items bookmarks. Exact outline input uses one-based page numbers. Automatic detection reuses an existing outline when present and otherwise makes a best-effort guess from positioned text and relative font sizes.

Summary

Types

error_reason()
item()

A normalized outline item returned by this module.

item_input()

A concise outline item accepted by put/2.

view()

A supported PDF destination view.

Functions

automatic(pdf)

Detects an outline and writes it back to the PDF in one operation.

detect(pdf)

Returns a proposed outline for a PDF.

get(pdf)

Returns the active PDF outline as a normalized nested list.

put(pdf, items)

Replaces the active PDF outline and returns an incrementally updated PDF.

Types

error_reason()

@type error_reason() ::
  :encrypted_pdf
  | :invalid_outlines
  | :invalid_pdf_input
  | :no_outline_source
  | :resource_limit_exceeded
  | :unsupported_pdf_feature

item()

@type item() :: NativeElixirPdfUtilities.Validators.OutlineValidator.item()

A normalized outline item returned by this module.

item_input()

@type item_input() ::
  %{
    :title => String.t(),
    optional(:page) => pos_integer() | nil,
    optional(:view) => view(),
    optional(:open) => boolean(),
    optional(:children) => [item_input()]
  }
  | {String.t(), pos_integer() | nil}
  | {String.t(), pos_integer() | nil, [item_input()]}

A concise outline item accepted by put/2.

view()

@type view() :: NativeElixirPdfUtilities.Validators.OutlineValidator.view()

A supported PDF destination view.

Functions

automatic(pdf)

@spec automatic(binary()) ::
  {:ok, binary()}
  | {:error,
     {error_reason(), NativeElixirPdfUtilities.Diagnostics.diagnostic()}}

Detects an outline and writes it back to the PDF in one operation.

This is equivalent to passing the result of detect/1 to put/2.

detect(pdf)

@spec detect(binary()) ::
  {:ok, [item()]}
  | {:error,
     {error_reason(), NativeElixirPdfUtilities.Diagnostics.diagnostic()}}

Returns a proposed outline for a PDF.

Existing outlines are returned unchanged. Otherwise the detector uses painted, extractable text and relative font sizes to guess headings. This is deliberately best-effort and may require caller adjustment before put/2.

get(pdf)

@spec get(binary()) ::
  {:ok, [item()]}
  | {:error,
     {error_reason(), NativeElixirPdfUtilities.Diagnostics.diagnostic()}}

Returns the active PDF outline as a normalized nested list.

A PDF without an outline returns {:ok, []}. Page numbers are one-based. Unsupported actions are returned as destinationless items rather than being executed or copied.

put(pdf, items)

@spec put(binary(), [item_input()]) ::
  {:ok, binary()}
  | {:error,
     {error_reason(), NativeElixirPdfUtilities.Diagnostics.diagnostic()}}

Replaces the active PDF outline and returns an incrementally updated PDF.

Items may use normalized maps, {title, page} tuples, or {title, page, children} tuples. Passing an empty list removes the active outline. A map may set :view, :open, and :children; :page may be nil for a destinationless grouping item. Leaf items normalize :open to true because they have no children to expand or collapse.