@spec close_document(reference()) :: :ok

Closes a document and frees what it held. A closed document answers {:error, :document_closed} to everything.

@spec create_document() :: {:ok, reference()}

Makes an empty document.

{:ok, document} = PDFium.create_document()

@spec flatten_page(reference(), non_neg_integer(), :display | :print) ::
  :ok | {:error, atom()}

Draws a page's annotations into its content and drops them, in place.

:ok = PDFium.flatten_page(document, 0)
:ok = PDFium.flatten_page(document, 1, :print)

usage picks the appearance drawn: :display is what a reader shows, :print what it would print.

@spec get_annotation_counts(reference()) ::
  {:ok, [non_neg_integer()]} | {:error, atom()}

How many annotations each page carries, in order.

{:ok, [2, 0]} = PDFium.get_annotation_counts(document)

@spec get_meta_text(reference(), binary()) :: {:ok, binary()} | {:error, atom()}

An entry of the document's Info dictionary, or "" when it has none.

{:ok, "A contract"} = PDFium.get_meta_text(document, "Title")

@spec get_page_bitmap(reference(), non_neg_integer(), pos_integer()) ::
  {:ok, {binary(), non_neg_integer(), non_neg_integer()}} | {:error, atom()}

Renders a page to RGBA pixels at dpi, annotations included.

{:ok, {pixels, width, height}} = PDFium.get_page_bitmap(document, 0, 150)

@spec get_page_boxes(reference()) :: {:ok, [page_box()]} | {:error, atom()}

The box and rotation of every page, in order: what placing content in a page's own coordinates needs.

{:ok, [%{left: 0.0, bottom: 0.0, right: 612.0, top: 792.0, rotation: 0}]} =
  PDFium.get_page_boxes(document)

@spec get_page_count(reference()) :: {:ok, non_neg_integer()} | {:error, atom()}

How many pages the document has.

{:ok, 3} = PDFium.get_page_count(document)

@spec get_page_sizes(reference()) :: {:ok, [page_size()]} | {:error, atom()}

The size of every page as a reader shows it, in points, in order.

{:ok, [%{width: 612.0, height: 792.0}]} = PDFium.get_page_sizes(document)

@spec get_security_handler_revision(reference()) ::
  {:ok, pos_integer() | nil} | {:error, atom()}

The revision of the standard security handler the document is encrypted with, or nil when it is not encrypted.

{:ok, 6} = PDFium.get_security_handler_revision(document)

@spec import_pages(
  reference(),
  reference(),
  :all | [non_neg_integer()],
  non_neg_integer()
) ::
  :ok | {:error, atom()}

Copies pages of source into destination at position at. pages is :all or page indexes counted from zero, in the order they should arrive.

:ok = PDFium.import_pages(destination, source, :all)
:ok = PDFium.import_pages(destination, source, [2, 0], 1)

@spec open_document(source(), [{:password, binary()}]) ::
  {:ok, reference()} | {:error, load_error()}

Opens a document from a path or from {:bytes, contents}.

{:ok, document} = PDFium.open_document("contract.pdf")
{:ok, document} = PDFium.open_document({:bytes, contents}, password: "secret")

The document keeps the contents for as long as it is open.

@spec save(reference(), Path.t(), security()) :: :ok | {:error, atom()}

Writes the document to output_path.

:ok = PDFium.save(document, "out.pdf")
:ok = PDFium.save(document, "out.pdf", :remove)

@spec save_to_binary(reference(), security()) :: {:ok, binary()} | {:error, atom()}

The document as it would be written.

{:ok, <<"%PDF-", _::binary>>} = PDFium.save_to_binary(document)

@spec stamp(reference(), [
  {reference(), non_neg_integer(), non_neg_integer(), placement()}
]) ::
  :ok | {:error, atom()}

Draws overlays over pages of document, in place.

:ok = PDFium.stamp(document, [{overlay, 0, 0, {1, 0, 0, 1, 0, 0}}])

A placement is {overlay, overlay_page, page_index, matrix}, pages counted from zero. Placements on one page stack in the order given. A placement that fails leaves the document as it was.

@spec with_document(source(), (reference() -> result), [{:password, binary()}]) ::
  result | {:error, load_error()}
when result: term()

Opens source, runs function with the document, and closes it again, even if the work raises.

{:ok, 3} = PDFium.with_document("contract.pdf", &PDFium.get_page_count/1)

@spec with_new_document((reference() -> result)) :: result | {:error, atom()}
when result: term()

Runs function with an empty document and closes it again.

{:ok, binary} =
  PDFium.with_new_document(fn output ->
    with :ok <- PDFium.import_pages(output, source, [0]), do: PDFium.save_to_binary(output)
  end)