@spec annotations(t()) ::
  {:ok, [PdfElixide.Document.Annotation.t()]} | {:error, PdfElixide.Error.t()}

Reads the annotations of the whole document.

Returns every page's annotations concatenated into a single flat list, in page order, as PdfElixide.Document.Annotation structs. Each carries its zero-based :page index. Returns {:ok, []} when the document has no annotations.

This builds every page's annotations in memory at once — see the "Whole-document extraction and memory" section of PdfElixide.Document for when to prefer annotations/2.

@spec annotations(t(), non_neg_integer()) ::
  {:ok, [PdfElixide.Document.Annotation.t()]} | {:error, PdfElixide.Error.t()}

Reads the annotations of the page at the given zero-based index.

Returns {:ok, []} when the page has no annotations. Each annotation — a link, sticky note, highlight, form widget, and so on — is carried as a PdfElixide.Document.Annotation struct.

@spec annotations!(t()) :: [PdfElixide.Document.Annotation.t()]

Reads the annotations of the whole document, raising an error if it fails.

@spec annotations!(t(), non_neg_integer()) :: [PdfElixide.Document.Annotation.t()]

Reads the annotations of the page at the given zero-based index, raising an error if it fails.

@spec authenticate(t(), binary()) :: {:ok, boolean()} | {:error, PdfElixide.Error.t()}

Authenticates against the document's encryption with the given password.

Returns {:ok, true} if authentication succeeded (or the PDF is not encrypted), {:ok, false} if the password was wrong, or {:error, reason} on a PDF/crypto error.

This is a password check, so a wrong password is a normal {:ok, false} result — unlike open/2's :password option, where it is an {:error, %PdfElixide.Error{reason: :wrong_password}} because the document cannot be produced.

The password is a byte string and is not required to be valid UTF-8 — see open_opts/0, whose :password option takes the same values.

An encrypted document read before it is authenticated extracts as empty — text/2 answers "", search/2 answers []. A first successful authentication reloads the document, so everything after it answers as though the handle had been opened with open/2's :password, and it costs about what opening the document cost — a rejected password too.

This is the one read-side function that takes the document's lock exclusively, so it waits for in-flight calls on the handle and blocks new ones for its duration. Authenticate before sharing the document with other processes, not after — see the Concurrency guide, whose other exclusive call is close/1.

@spec authenticate!(t(), binary()) :: boolean()

Same as authenticate/2 but raises on error.

Still returns false (does not raise) for a wrong password.

@spec chars(t(), chars_opts() | non_neg_integer()) ::
  {:ok, [PdfElixide.Document.Char.t()]} | {:error, PdfElixide.Error.t()}

Extracts characters, each with its bounding box, font metadata and typographic placement as a PdfElixide.Document.Char struct.

With a keyword list (or nothing) as the second argument, returns every page's characters concatenated into a single flat list, in page order. With a zero-based integer, returns that single page's characters instead.

Document.chars(doc)
Document.chars(doc, region: heading.bbox)
Document.chars(doc, 0)
Document.chars(doc, 0, region_mode: :fully_contained)

This is the most memory-hungry extractor here — one struct per glyph, each carrying its own text and font-name binary — so the whole-document form is the one most worth avoiding on a large document. See the "Whole-document extraction and memory" section of PdfElixide.Document, and consider spans/1, which describes the same text in runs.

See chars_opts/0 for the available options.

@spec chars(t(), non_neg_integer(), chars_opts()) ::
  {:ok, [PdfElixide.Document.Char.t()]} | {:error, PdfElixide.Error.t()}

Extracts the characters of the page at the given zero-based index.

See chars_opts/0 for the available options.

@spec chars!(t(), chars_opts() | non_neg_integer()) :: [PdfElixide.Document.Char.t()]

Extracts characters, raising an error if it fails.

@spec chars!(t(), non_neg_integer(), chars_opts()) :: [PdfElixide.Document.Char.t()]

Extracts the characters of the page at the given zero-based index, raising an error if it fails.

@spec clear_search_index(t()) :: :ok | {:error, PdfElixide.Error.t()}

Releases the cached search index, and the page text and boxes it holds.

The document stays usable; a later search/2 rebuilds what it needs. Nothing evicts from this index on its own, so on a large document this is the only release short of close/1 — see the Search guide.

Unlike the other reads here it takes the handle's lock exclusively, so it waits for calls already in flight — see Concurrency.

@spec clear_search_index!(t()) :: :ok

Releases the cached search index, raising an error if it fails.

@spec close(t()) :: :ok

Releases the document's native memory immediately.

A document holds its PDF data in memory on the Rust side, normally freed only when the BEAM garbage-collects the handle. close/1 frees it now, which matters for long-lived processes that open many documents. Calling it is optional and idempotent.

It takes the handle's lock exclusively, where reads take it shared, so it waits for every in-flight call on the same document — and an extraction can hold its share of that lock for seconds. Immediately means as soon as the handle is idle, not preemptively. That is one of the exclusive calls the Concurrency guide is about.

Afterwards, functions that read the document return {:error, %PdfElixide.Error{reason: :closed}}, and their bang variants raise it. version/1, source_path/1 and page_count/1 keep working, since they read the struct rather than the native handle — page_count/1 only for a document whose count was determined at open. Any PdfElixide.Document.Image or PdfElixide.Document.Font handles already extracted from the document remain valid, owning their data independently.

doc = Document.open!("sample.pdf")
text = Document.text!(doc, 0)
:ok = Document.close(doc)

@spec closed?(t()) :: boolean()

Returns whether the document has been released with close/1.

@spec encrypted?(t()) :: boolean()

Returns whether the PDF document is encrypted.

A closed document or a native panic raises — see the "Errors versus exceptions" section of PdfElixide.Error. Nothing else can fail here.

@spec fonts(t()) ::
  {:ok, [PdfElixide.Document.Font.t()]} | {:error, PdfElixide.Error.t()}

Extracts the fonts of the whole document.

Returns every page's fonts concatenated into a single flat list, in page order, as PdfElixide.Document.Font structs. A font used on several pages appears once per page.

A page whose fonts cannot be read contributes nothing and does not fail the call — see fonts/2 for what that covers. Along with text/1 this is the only whole-document extractor that tolerates such a page, and the only one that does so with no option to say otherwise.

Each returned font holds the embedded font program behind its handle until PdfElixide.Document.Font.close/1 or GC, one handle per page per font — see the "Whole-document extraction and memory" section of PdfElixide.Document.

@spec fonts(t(), non_neg_integer()) ::
  {:ok, [PdfElixide.Document.Font.t()]} | {:error, PdfElixide.Error.t()}

Extracts the fonts referenced by the page at the given zero-based index.

Returns {:ok, []} when the page references no fonts. Each font is carried as a PdfElixide.Document.Font struct with its metadata; the raw embedded font program (when present) is pulled on demand with PdfElixide.Document.Font.data/1.

An empty list also covers a page that could not be read — one whose page-tree entry, /Resources reference or fonts do not resolve yields no fonts rather than an error. Only an out-of-range index and a failed handle are errors, and there is no strict variant that reports the difference.

@spec fonts!(t()) :: [PdfElixide.Document.Font.t()]

Extracts the fonts of the whole document, raising an error if it fails.

@spec fonts!(t(), non_neg_integer()) :: [PdfElixide.Document.Font.t()]

Extracts the fonts referenced by the page at the given zero-based index, raising an error if it fails.

@spec from_binary(binary(), open_opts()) ::
  {:ok, t()} | {:error, PdfElixide.Error.t()}

Opens a PDF document from the given binary data.

Takes bytes you already have — an HTTP response body, a database blob — so no path is involved; use open/2 to read a file. source_path/1 is nil for the resulting document.

@spec from_binary!(binary(), open_opts()) :: t()

Opens a PDF document from the given binary data, raising an error if it fails.

Takes bytes you already have — an HTTP response body, a database blob — so no path is involved; use open!/2 to read a file.

@spec has_structure_tree(t()) :: {:ok, boolean()} | {:error, PdfElixide.Error.t()}

Returns whether the PDF document is a Tagged PDF with a structure tree, reporting a structure tree that cannot be read.

The strict counterpart of has_structure_tree?/1, which cannot distinguish false from a failure. This keeps the three states apart: tagged ({:ok, true}), untagged ({:ok, false}) and unparseable ({:error, %PdfElixide.Error{}}).

@spec has_structure_tree?(t()) :: boolean()

Returns whether the PDF document is a Tagged PDF with a structure tree.

Answers false for a document whose structure tree cannot be read as well as for one that has none: a corrupt /StructTreeRoot is reported the same way an untagged document is. Use has_structure_tree/1 to tell the two apart. A handle that cannot be used at all — a closed document, a native panic — still raises.

@spec has_xfa(t()) :: {:ok, boolean()} | {:error, PdfElixide.Error.t()}

Returns whether the PDF document contains XFA (XML Forms Architecture) form data, reporting a catalog that cannot be read.

The strict counterpart of has_xfa?/1. Only a broken document reaches the error: every structural absence — a catalog that is not a dictionary, a missing /AcroForm, a missing /XFA — already answers {:ok, false}.

@spec has_xfa?(t()) :: boolean()

Returns whether the PDF document contains XFA (XML Forms Architecture) form data.

Answers false for a document whose catalog or /AcroForm entry cannot be read as well as for one that carries no XFA. Use has_xfa/1 to tell the two apart; a closed document or a native panic still raises.

@spec images(t()) ::
  {:ok, [PdfElixide.Document.Image.t()]} | {:error, PdfElixide.Error.t()}

Extracts the raster images of the whole document.

Returns every page's images concatenated into a single flat list, in page order, as PdfElixide.Document.Image structs. The pixel data is not carried on the struct — encode it on demand with PdfElixide.Document.Image.to_binary/2 or PdfElixide.Document.Image.save/3.

What is deferred there is the encode, not the load: every image's decoded pixels — or its original JPEG bytes — stay resident behind its handle until PdfElixide.Document.Image.close/1 or GC. See the "Whole-document extraction and memory" section of PdfElixide.Document.

@spec images(t(), non_neg_integer()) ::
  {:ok, [PdfElixide.Document.Image.t()]} | {:error, PdfElixide.Error.t()}

Extracts the raster images of the page at the given zero-based index.

Returns {:ok, []} when the page has no images. Each image — a photo, logo, or scanned picture — is carried as a PdfElixide.Document.Image struct, which holds the metadata and a handle rather than the pixel data itself; encode it on demand with PdfElixide.Document.Image.to_binary/2 or PdfElixide.Document.Image.save/3.

@spec images!(t()) :: [PdfElixide.Document.Image.t()]

Extracts the raster images of the whole document, raising an error if it fails.

@spec images!(t(), non_neg_integer()) :: [PdfElixide.Document.Image.t()]

Extracts the raster images of the page at the given zero-based index, raising an error if it fails.

@spec inks(t(), non_neg_integer(), inks_opts()) ::
  {:ok, [String.t()]} | {:error, PdfElixide.Error.t()}

Lists the Separation and DeviceN ink names the page at the given zero-based index declares — the values :exclude_inks accepts, see text_opts/0. Sorted and deduplicated.

Only the page's own /Resources is read unless inks_opts/0's :deep is set, which is where that trade-off is explained.

Some names never appear: All and None, DeviceN colorants the colour space declares to be process components, and colorants declared only inside a pattern object's own resources or an annotation's appearance stream.

Returns {:ok, []} for a page that declares no colour spaces. There is no whole-document arity — take the union yourself:

doc |> Enum.flat_map(&PdfElixide.Document.Page.inks!(&1, deep: true)) |> Enum.uniq()

@spec inks!(t(), non_neg_integer(), inks_opts()) :: [String.t()]

Lists the page's ink names, raising an error if it fails.

@spec layers(t()) :: {:ok, [String.t()]} | {:error, PdfElixide.Error.t()}

Lists the names of the optional-content groups (OCG layers) the document declares — the values :exclude_layers accepts, see text_opts/0. Pass one back unchanged rather than retyping it; the filter matches the exact string.

They arrive in /OCGs order, neither sorted nor deduplicated, so a display name two groups share appears twice. A group that cannot be read or declares no name is skipped, and a document with no optional content yields {:ok, []}.

The list is not exhaustive of what :exclude_layers acts on: filtering matches whatever group a page's content references, declared here or not.

@spec layers!(t()) :: [String.t()]

Lists the document's optional-content group names, raising an error if it fails.

@spec lines(t()) ::
  {:ok, [PdfElixide.Document.Path.t()]} | {:error, PdfElixide.Error.t()}

Extracts the straight lines of the whole document.

Returns every page's lines concatenated into a single flat list, in page order, as PdfElixide.Document.Path structs — the values paths/1 returns, narrowed to those classified as single straight segments (see the "Rectangles and straight lines" section of PdfElixide.Document.Path for which shapes those are). These are vector graphics; text_lines/1 is the unrelated text extractor.

This builds every page's lines in memory at once — see the "Whole-document extraction and memory" section of PdfElixide.Document for when to prefer lines/2.

@spec lines(t(), non_neg_integer()) ::
  {:ok, [PdfElixide.Document.Path.t()]} | {:error, PdfElixide.Error.t()}

Extracts the straight lines of the page at the given zero-based index.

Returns {:ok, []} when the page draws no shape classified as a single straight segment. See the "Rectangles and straight lines" section of PdfElixide.Document.Path for which shapes qualify.

@spec lines!(t()) :: [PdfElixide.Document.Path.t()]

Extracts the straight lines of the whole document, raising an error if it fails.

@spec lines!(t(), non_neg_integer()) :: [PdfElixide.Document.Path.t()]

Extracts the straight lines of the page at the given zero-based index, raising an error if it fails.

@spec metadata(t()) ::
  {:ok, PdfElixide.Document.Metadata.t()} | {:error, PdfElixide.Error.t()}

Reads the document's Info dictionary metadata (title, author, dates, etc.).

Always returns a PdfElixide.Document.Metadata struct; a document with no /Info dictionary yields one with every field nil. For XMP metadata, see xmp_metadata/1.

@spec metadata!(t()) :: PdfElixide.Document.Metadata.t()

Reads the document's Info dictionary metadata, raising an error if it fails.

@spec open(Path.t(), open_opts()) :: {:ok, t()} | {:error, PdfElixide.Error.t()}

Opens a PDF document from the specified file path.

The path is handed to the operating system unchanged — see the "File paths" section of PdfElixide.

@spec open!(Path.t(), open_opts()) :: t()

Opens a PDF document from the specified file path, raising an error if it fails.

The path is handed to the operating system unchanged — see the "File paths" section of PdfElixide.

@spec outline(t()) ::
  {:ok, [PdfElixide.Document.OutlineItem.t()]} | {:error, PdfElixide.Error.t()}

Reads the document outline — its bookmarks / table of contents.

Returns the top-level PdfElixide.Document.OutlineItem structs, each of which may carry nested :children, forming a tree. Returns {:ok, []} when the document has no outline.

Nesting deeper than 256 levels is rejected with %PdfElixide.Error{reason: :unsupported} rather than truncated, so a malformed or hostile bookmark tree cannot overflow the native stack. No real table of contents comes close to the limit.

@spec outline!(t()) :: [PdfElixide.Document.OutlineItem.t()]

Reads the document outline, raising an error if it fails.

@spec page(t(), non_neg_integer()) ::
  {:ok, PdfElixide.Document.Page.t()} | {:error, PdfElixide.Error.t()}

Returns a PdfElixide.Document.Page handle for the page at the given zero-based index.

Builds nothing but the handle itself, and reads no page content until an extractor is called on it.

@spec page!(t(), non_neg_integer()) :: PdfElixide.Document.Page.t()

Same as page/2 but raises an error if it fails.

@spec page_count(t()) :: {:ok, non_neg_integer()} | {:error, PdfElixide.Error.t()}

Returns the number of pages in the given PDF document.

The count arrives with the handle from the call that opens the document and is cached on the struct, so this normally costs nothing and keeps working after close/1, as version/1 does.

The exception is a document whose page tree could not be read at open — an encrypted one opened without a password. Nothing is cached for it, so the count is read from the document on every call: an error until authenticate/2 succeeds, and the real count afterwards.

@spec page_count!(t()) :: non_neg_integer()

Returns the number of pages in the given PDF document, raising an error if it fails.

@spec page_labels(t()) :: {:ok, [String.t()]} | {:error, PdfElixide.Error.t()}

Returns the document's logical page labels — one per page, in page order.

Page labels are the human-facing page numbers a PDF may define (e.g. "i", "ii", "iii", "1", "2"), independent of the zero-based physical page index. Pages outside any declared label range fall back to their decimal page number, so the returned list always has one entry per page.

See also PdfElixide.Document.Page.label/1 for a single page's label.

@spec page_labels!(t()) :: [String.t()]

Returns the document's logical page labels, raising an error if it fails.

@spec pages(t()) :: [PdfElixide.Document.Page.t()]

Returns a PdfElixide.Document.Page handle for every page in the document.

The list is built eagerly, but each handle is just the document and a zero-based index and holds no native resource, so building one costs nothing. To walk a large document without materializing every handle, enumerate the document itself: it implements Enumerable over its pages.

Reads the page count cached on the struct, so it raises only for a document whose count could not be determined at open — see page_count/1.

@spec paths(t()) ::
  {:ok, [PdfElixide.Document.Path.t()]} | {:error, PdfElixide.Error.t()}

Extracts the vector paths of the whole document.

Returns every page's paths concatenated into a single flat list, in page order, as PdfElixide.Document.Path structs.

This builds every page's paths in memory at once — see the "Whole-document extraction and memory" section of PdfElixide.Document for when to prefer paths/2.

@spec paths(t(), non_neg_integer()) ::
  {:ok, [PdfElixide.Document.Path.t()]} | {:error, PdfElixide.Error.t()}

Extracts the vector paths of the page at the given zero-based index.

Returns {:ok, []} when the page has no vector graphics. Each path — a line, curve, rectangle, or filled shape — is carried as a PdfElixide.Document.Path struct.

@spec paths!(t()) :: [PdfElixide.Document.Path.t()]

Extracts the vector paths of the whole document, raising an error if it fails.

@spec paths!(t(), non_neg_integer()) :: [PdfElixide.Document.Path.t()]

Extracts the vector paths of the page at the given zero-based index, raising an error if it fails.

@spec permissions(t()) ::
  {:ok, PdfElixide.Document.Permissions.t() | nil}
  | {:error, PdfElixide.Error.t()}

Reads the document's /P permission flags.

Returns {:ok, %PdfElixide.Document.Permissions{}} for an encrypted document, or {:ok, nil} when the document is not encrypted (no permission dictionary).

Per the PDF specification these flags are advisory; see PdfElixide.Document.Permissions.

@spec permissions!(t()) :: PdfElixide.Document.Permissions.t() | nil

Reads the document's permission flags, raising an error if it fails.

@spec prepare_search(t()) :: :ok | {:error, PdfElixide.Error.t()}

Builds the search index for every page, so a later search/2 does not pay for the whole document at once.

Searching already builds the index lazily, so this only moves that cost — see the Search guide.

@spec prepare_search!(t()) :: :ok

Builds the search index for every page, raising an error if it fails.

@spec rects(t()) ::
  {:ok, [PdfElixide.Document.Path.t()]} | {:error, PdfElixide.Error.t()}

Extracts the rectangles of the whole document.

Returns every page's rectangles concatenated into a single flat list, in page order, as PdfElixide.Document.Path structs — the values paths/1 returns, narrowed to those classified as rectangles (see the "Rectangles and straight lines" section of PdfElixide.Document.Path for which shapes those are).

This builds every page's rectangles in memory at once — see the "Whole-document extraction and memory" section of PdfElixide.Document for when to prefer rects/2.

@spec rects(t(), non_neg_integer()) ::
  {:ok, [PdfElixide.Document.Path.t()]} | {:error, PdfElixide.Error.t()}

Extracts the rectangles of the page at the given zero-based index.

Returns {:ok, []} when the page draws no shape classified as a rectangle. See the "Rectangles and straight lines" section of PdfElixide.Document.Path for which shapes qualify.

@spec rects!(t()) :: [PdfElixide.Document.Path.t()]

Extracts the rectangles of the whole document, raising an error if it fails.

@spec rects!(t(), non_neg_integer()) :: [PdfElixide.Document.Path.t()]

Extracts the rectangles of the page at the given zero-based index, raising an error if it fails.

@spec search(t(), String.t(), search_opts() | non_neg_integer()) ::
  {:ok, [PdfElixide.Document.SearchMatch.t()]} | {:error, PdfElixide.Error.t()}

Finds every occurrence of pattern in the document's text, as PdfElixide.Document.SearchMatch structs.

With a keyword list (or nothing) as the third argument, searches every page and returns the matches in page order. With a zero-based integer, searches that single page instead.

Document.search(doc, "Figure 3")
Document.search(doc, "figure 3", case_insensitive: true)
Document.search(doc, "Figure 3", 0)
Document.search(doc, ~S"Figure \d+", 0, literal: false)

The pattern is plain text by default. Pass literal: false to treat it as a regular expression, which reports an unparseable one as %PdfElixide.Error{reason: :invalid_pattern}.

A match's boxes cover whole runs of text rather than the matched characters — see PdfElixide.Document.SearchMatch. Searching builds a per-page index that is reused by later searches and released by clear_search_index/1 or close/1. The Search guide covers both.

The whole-document form builds every page's matches in memory at once — see the "Whole-document extraction and memory" section of PdfElixide.Document for when to prefer the per-page arity.

See search_opts/0 for the available options.

@spec search(t(), String.t(), non_neg_integer(), search_opts()) ::
  {:ok, [PdfElixide.Document.SearchMatch.t()]} | {:error, PdfElixide.Error.t()}

Finds every occurrence of pattern on the page at the given zero-based index.

See search_opts/0 for the available options.

@spec search!(t(), String.t(), search_opts() | non_neg_integer()) :: [
  PdfElixide.Document.SearchMatch.t()
]

Finds every occurrence of pattern, raising an error if it fails.

@spec search!(t(), String.t(), non_neg_integer(), search_opts()) :: [
  PdfElixide.Document.SearchMatch.t()
]

Finds every occurrence of pattern on the page at the given zero-based index, raising an error if it fails.

@spec source_path(t()) :: Path.t() | nil

Returns the file path from which the document was loaded, or nil if it was loaded from binary data.

@spec spans(t(), spans_opts() | non_neg_integer()) ::
  {:ok, [PdfElixide.Document.Span.t()]} | {:error, PdfElixide.Error.t()}

Extracts spans — runs of text sharing one text state — as PdfElixide.Document.Span structs.

With a keyword list (or nothing) as the second argument, returns every page's spans concatenated into a single flat list, in page order. With a zero-based integer, returns that single page's spans instead.

Document.spans(doc)
Document.spans(doc, reading_order: :column_aware)
Document.spans(doc, 0)
Document.spans(doc, 0, span_merging: [preset: :aggressive])

A span covers a run of text rather than one glyph, so this is the cheaper way to ask for what chars/1 returns. The whole-document form still builds every page's spans in memory at once — see the "Whole-document extraction and memory" section of PdfElixide.Document.

See spans_opts/0 for the available options.

@spec spans(t(), non_neg_integer(), spans_opts()) ::
  {:ok, [PdfElixide.Document.Span.t()]} | {:error, PdfElixide.Error.t()}

Extracts the spans of the page at the given zero-based index.

See spans_opts/0 for the available options.

@spec spans!(t(), spans_opts() | non_neg_integer()) :: [PdfElixide.Document.Span.t()]

Extracts spans, raising an error if it fails.

@spec spans!(t(), non_neg_integer(), spans_opts()) :: [PdfElixide.Document.Span.t()]

Extracts the spans of the page at the given zero-based index, raising an error if it fails.

@spec tables(t(), tables_opts() | non_neg_integer()) ::
  {:ok, [PdfElixide.Document.Table.t()]} | {:error, PdfElixide.Error.t()}

Detects tables, as PdfElixide.Document.Table structs.

With a keyword list (or nothing) as the second argument, returns every page's tables concatenated into a single flat list, in page order. With a zero-based integer, returns that single page's tables instead.

Document.tables(doc)
Document.tables(doc, 0)
Document.tables(doc, 0, preset: :strict, row_tolerance: 1.5)

Detection is heuristic — see PdfElixide.Document.Table for the :real_grid? flag and how to filter out likely false positives, and tables_opts/0 for the available options.

Every returned table stays resident behind its handle until PdfElixide.Document.Table.close/1 or GC — see the "Whole-document extraction and memory" section of PdfElixide.Document.

@spec tables(t(), non_neg_integer(), tables_opts()) ::
  {:ok, [PdfElixide.Document.Table.t()]} | {:error, PdfElixide.Error.t()}

Detects the tables of the page at the given zero-based index.

Returns {:ok, []} when the page has no detectable table. See tables_opts/0 for the available options.

@spec tables!(t(), tables_opts() | non_neg_integer()) :: [
  PdfElixide.Document.Table.t()
]

Detects tables, raising an error if it fails.

@spec tables!(t(), non_neg_integer(), tables_opts()) :: [
  PdfElixide.Document.Table.t()
]

Detects the tables of the page at the given zero-based index, raising an error if it fails.

@spec text(t(), text_opts() | non_neg_integer()) ::
  {:ok, String.t()} | {:error, PdfElixide.Error.t()}

Extracts text content.

With a keyword list (or nothing) as the second argument, extracts the whole document — every page's text concatenated in order, separated by a form-feed (\f) page separator. With a zero-based integer, extracts that single page instead.

Document.text(doc)
Document.text(doc, extract_tables: false)
Document.text(doc, 0)
Document.text(doc, 0, region: word.bbox)

A page that fails to extract contributes an empty string to the whole-document result rather than failing the call. Its separator is emitted regardless, so the result always splits into exactly page_count/1 parts and a skipped page reads as a blank one. Pass on_page_error: :halt to fail the call instead.

The whole-document form builds every page's text in memory at once — see the "Whole-document extraction and memory" section of PdfElixide.Document.

See text_opts/0 for the available options.

@spec text(t(), non_neg_integer(), text_opts()) ::
  {:ok, String.t()} | {:error, PdfElixide.Error.t()}

Extracts the text content of the page at the given zero-based index.

See text_opts/0 for the available options.

@spec text!(t(), text_opts() | non_neg_integer()) :: String.t()

Extracts text content, raising an error if it fails.

@spec text!(t(), non_neg_integer(), text_opts()) :: String.t()

Extracts the text content of the page at the given zero-based index, raising an error if it fails.

@spec text_lines(t(), text_lines_opts() | non_neg_integer()) ::
  {:ok, [PdfElixide.Document.TextLine.t()]} | {:error, PdfElixide.Error.t()}

Extracts text lines, each with its bounding box and constituent words as a PdfElixide.Document.TextLine struct.

With a keyword list (or nothing) as the second argument, returns every page's lines concatenated into a single flat list, in page order. With a zero-based integer, returns that single page's lines instead.

Document.text_lines(doc)
Document.text_lines(doc, include_artifacts: false)
Document.text_lines(doc, 0)
Document.text_lines(doc, 0, region: heading.bbox)

The whole-document form builds every page's lines in memory at once — see the "Whole-document extraction and memory" section of PdfElixide.Document for when to prefer the per-page arity.

See text_lines_opts/0 for the available options.

@spec text_lines(t(), non_neg_integer(), text_lines_opts()) ::
  {:ok, [PdfElixide.Document.TextLine.t()]} | {:error, PdfElixide.Error.t()}

Extracts the text lines of the page at the given zero-based index.

See text_lines_opts/0 for the available options.

@spec text_lines!(t(), text_lines_opts() | non_neg_integer()) :: [
  PdfElixide.Document.TextLine.t()
]

Extracts text lines, raising an error if it fails.

@spec text_lines!(t(), non_neg_integer(), text_lines_opts()) :: [
  PdfElixide.Document.TextLine.t()
]

Extracts the text lines of the page at the given zero-based index, raising an error if it fails.

@spec to_html(t(), html_opts() | non_neg_integer()) ::
  {:ok, String.t()} | {:error, PdfElixide.Error.t()}

Converts the document to HTML.

With a keyword list (or nothing) as the second argument, converts the whole document, wrapping each page in a <div class="page" data-page="N"> element whose N is the one-based page number. With a zero-based integer, converts that single page instead, without the wrapper.

Document.to_html(doc)
Document.to_html(doc, detect_headings: false)
Document.to_html(doc, 0)

The result is an HTML fragment, not a standalone document: there is no doctype, no <html>/<body>, and no stylesheet — bring your own, or wrap the fragment yourself. A page with no extractable content converts to an empty string, as does a document that is encrypted and could not be decrypted.

The whole-document form builds the entire conversion in memory at once, which :include_images can make considerably larger — see the "Whole-document extraction and memory" section of PdfElixide.Document.

Escaping

Text taken from the PDF is escaped before it reaches the fragment — &, <, > and " become entities in span text, headings and table cells alike, in :preserve_layout mode as well — so a crafted document cannot inject markup. ' is left as-is, which is safe only because every attribute the converter emits is double-quoted: don't re-quote the fragment with single quotes.

A /Link annotation's URI is escaped too, and an anchor is emitted only for the http, https, mailto, tel, ftp and ftps schemes; any other target keeps its link text and loses the link. Anchors carry rel="noopener noreferrer".

The one input that is not escaped is :image_output_dir; see html_opts/0. So the fragment is safe to render as raw HTML as long as that path is yours and not an untrusted one.

See html_opts/0 for the available options.

@spec to_html(t(), non_neg_integer(), html_opts()) ::
  {:ok, String.t()} | {:error, PdfElixide.Error.t()}

Converts the page at the given zero-based index to HTML.

See html_opts/0 for the available options, and the "Escaping" section of to_html/2 for what in the fragment is escaped.

@spec to_html!(t(), html_opts() | non_neg_integer()) :: String.t()

Converts the document to HTML, raising an error if it fails.

@spec to_html!(t(), non_neg_integer(), html_opts()) :: String.t()

Converts the page at the given zero-based index to HTML, raising an error if it fails.

@spec to_markdown(t(), markdown_opts() | non_neg_integer()) ::
  {:ok, String.t()} | {:error, PdfElixide.Error.t()}

Converts the document to Markdown.

With a keyword list (or nothing) as the second argument, converts the whole document, joining pages with a --- thematic break — note that this differs from text/1, which uses a form feed. With a zero-based integer, converts that single page instead.

Document.to_markdown(doc)
Document.to_markdown(doc, detect_headings: false)
Document.to_markdown(doc, 0)

The whole-document form builds the entire conversion in memory at once, which :include_images can make considerably larger — see the "Whole-document extraction and memory" section of PdfElixide.Document.

See markdown_opts/0 for the available options.

@spec to_markdown(t(), non_neg_integer(), markdown_opts()) ::
  {:ok, String.t()} | {:error, PdfElixide.Error.t()}

Converts the page at the given zero-based index to Markdown.

See markdown_opts/0 for the available options.

@spec to_markdown!(t(), markdown_opts() | non_neg_integer()) :: String.t()

Converts the document to Markdown, raising an error if it fails.

@spec to_markdown!(t(), non_neg_integer(), markdown_opts()) :: String.t()

Converts the page at the given zero-based index to Markdown, raising an error if it fails.

@spec version(t()) :: {non_neg_integer(), non_neg_integer()}

Returns the PDF specification version of the given document as a {major, minor} tuple.

@spec words(t(), words_opts() | non_neg_integer()) ::
  {:ok, [PdfElixide.Document.Word.t()]} | {:error, PdfElixide.Error.t()}

Extracts words, each with its bounding box and font metadata as a PdfElixide.Document.Word struct.

With a keyword list (or nothing) as the second argument, returns every page's words concatenated into a single flat list, in page order. With a zero-based integer, returns that single page's words instead.

Document.words(doc)
Document.words(doc, include_artifacts: false)
Document.words(doc, 0)
Document.words(doc, 0, region: heading.bbox)

The whole-document form builds every page's words in memory at once — see the "Whole-document extraction and memory" section of PdfElixide.Document for when to prefer the per-page arity.

See words_opts/0 for the available options.

@spec words(t(), non_neg_integer(), words_opts()) ::
  {:ok, [PdfElixide.Document.Word.t()]} | {:error, PdfElixide.Error.t()}

Extracts the words of the page at the given zero-based index.

See words_opts/0 for the available options.

@spec words!(t(), words_opts() | non_neg_integer()) :: [PdfElixide.Document.Word.t()]

Extracts words, raising an error if it fails.

@spec words!(t(), non_neg_integer(), words_opts()) :: [PdfElixide.Document.Word.t()]

Extracts the words of the page at the given zero-based index, raising an error if it fails.

@spec xmp_metadata(t()) ::
  {:ok, PdfElixide.Document.XmpMetadata.t() | nil}
  | {:error, PdfElixide.Error.t()}

Reads the document's XMP (Extensible Metadata Platform) metadata.

Returns {:ok, %PdfElixide.Document.XmpMetadata{}} when the document carries an XMP packet, or {:ok, nil} when it does not. For the classic Info dictionary metadata, see metadata/1.

@spec xmp_metadata!(t()) :: PdfElixide.Document.XmpMetadata.t() | nil

Reads the document's XMP metadata, raising an error if it fails.