PaperForge.Document (PaperForge v1.2.0)

@type t() :: %PaperForge.Document{
  components: %{optional(atom()) => function()},
  compress: boolean(),
  default_font: atom(),
  font_fallbacks: %{optional(atom()) => [atom()]},
  font_families: %{optional(atom()) => %{optional(atom()) => atom()}},
  font_program_registry: %{optional(binary()) => PaperForge.Reference.t()},
  font_registry: PaperForge.FontRegistry.t(),
  font_source_data: %{optional(atom()) => binary()},
  image_registry: PaperForge.ImageRegistry.t(),
  info_reference: PaperForge.Reference.t() | nil,
  last_outline_reference: PaperForge.Reference.t() | nil,
  named_destinations: %{optional(binary()) => list()},
  next_object_id: pos_integer(),
  objects: %{optional(pos_integer()) => PaperForge.Object.t()},
  outline_count: non_neg_integer(),
  outlines_reference: PaperForge.Reference.t() | nil,
  page_templates: %{optional(atom()) => keyword()},
  pages_reference: PaperForge.Reference.t(),
  pdf_version: binary(),
  root_reference: PaperForge.Reference.t(),
  styles: %{optional(atom()) => keyword()}
}

Functions

add_named_destination(document, name, page_reference, options \\ [])

@spec add_named_destination(
  t(),
  binary() | atom(),
  PaperForge.Reference.t(),
  keyword()
) :: t()

Adds or replaces a named destination in the PDF catalog.

add_object(document, value)

@spec add_object(t(), term()) :: {t(), PaperForge.Reference.t()}

Adds a new indirect object.

add_outline(document, title, page_reference, options \\ [])

@spec add_outline(t(), binary(), PaperForge.Reference.t(), keyword()) :: t()

Adds a PDF outline/bookmark item that points to a page.

append_page(document, page_reference)

@spec append_page(t(), PaperForge.Reference.t()) :: t()

Adds a page reference to the page tree.

attach(document, filename, data, options \\ [])

@spec attach(t(), binary(), binary(), keyword()) :: t()

Embeds a file in the PDF and associates it with the document catalog.

component(document, component_name, renderer)

@spec component(t(), atom(), (map() -> PaperForge.Flow.t())) :: t()

Registers a reusable flow component receiving an assigns map.

default_font(document, font_key)

@spec default_font(t(), atom()) :: t()

Sets the document default font key.

fetch_object(document, reference)

@spec fetch_object(t(), PaperForge.Reference.t()) ::
  {:ok, PaperForge.Object.t()} | :error

Fetches an object by reference.

fetch_object!(document, reference)

@spec fetch_object!(t(), PaperForge.Reference.t()) :: PaperForge.Object.t()

Fetches an object by reference and raises when missing.

fetch_page_template(document, template_name)

@spec fetch_page_template(t(), atom()) :: {:ok, keyword()} | :error

Fetches a page template.

font_fallback(document, primary_font, fallbacks)

@spec font_fallback(t(), atom(), [atom()]) :: t()

Registers fallback font keys for text that a primary TrueType font cannot render.

new(options \\ [])

@spec new(keyword()) :: t()

Creates a new PDF document.

The initial objects are the page tree and catalog. Fonts are registered on demand when pages are compiled.

Options

:compress — enables Flate compression. Defaults to true.
:pdf_version — PDF header version. Defaults to "1.7".
:default_font — default font key for text operations. Defaults to :helvetica.

object_count(document)

@spec object_count(t()) :: non_neg_integer()

Returns the number of indirect objects.

objects(document)

@spec objects(t()) :: [PaperForge.Object.t()]

Returns indirect objects sorted by identifier.

page_template(document, template_name, options)

@spec page_template(t(), atom(), keyword()) :: t()

Registers a reusable page template.

put_metadata(document, metadata)

@spec put_metadata(t(), PaperForge.Metadata.t()) :: t()

Adds a metadata information dictionary.

register_font(document, font_key)

@spec register_font(t(), atom()) :: {t(), PaperForge.Font.t()}

Registers and reuses a standard PDF font.

register_font(document, font_key, options)

@spec register_font(t(), atom(), keyword()) :: t()

Registers and reuses an embedded TrueType font.

register_font_family(document, family_key, variants)

@spec register_font_family(t(), atom(), keyword()) :: t()

Registers a TrueType font family.

Supported variants are :regular, :bold, :italic, and :bold_italic. Each variant accepts the same options as register_font/3, usually path: "Font.ttf" or data: binary.

register_image(document, image_data)

@spec register_image(t(), binary()) :: {t(), PaperForge.Image.t()}

Registers and deduplicates a supported image.

JPEG and PNG binaries are currently supported.

register_jpeg(document, jpeg_data)

@spec register_jpeg(t(), binary()) :: {t(), PaperForge.Image.t()}

Registers and deduplicates a JPEG image.

resolve_font_key(document, options)

@spec resolve_font_key(
  t(),
  keyword()
) :: atom()

Resolves the font key for text options, including default fonts and registered font-family variants.

resolve_page_template(document, template_name)

@spec resolve_page_template(t(), atom()) ::
  {:ok, keyword()} | :error | {:error, :cycle}

Resolves a page template and all of its :extends ancestors.

resolve_text_font_key(document, options, text)

@spec resolve_text_font_key(t(), keyword(), binary()) :: atom()

Resolves a font for an entire text run, applying registered fallbacks when needed.

style(document, style_name, options)

@spec style(t(), atom(), keyword()) :: t()

Registers a named document style used by PaperForge.Flow blocks.

update_object(document, reference, update_function)

@spec update_object(
  t(),
  PaperForge.Reference.t(),
  (term() -> term())
) :: t()

Updates an existing indirect object.

use_font_text(document, font_key, text)

@spec use_font_text(t(), atom(), binary()) :: {t(), PaperForge.Font.t()}

Records Unicode text used by an embedded TrueType font.

PaperForge keeps the embedded font file intact, but subsets the PDF width array and /ToUnicode map to the glyphs that have actually been used so far.