@type adaptive_threshold_opts() :: [
  median_multiplier: float() | nil,
  min_threshold_pt: float() | nil,
  max_threshold_pt: float() | nil,
  use_iqr: boolean() | nil,
  min_samples: non_neg_integer() | nil
]

Options accepted as the :adaptive key of span_merging_opts/0, tuning how a space threshold is derived from a page's gap statistics. Consulted only when :use_adaptive_threshold resolves to true.

Every key defaults to nil, meaning "keep the preset's value".

@type bookmark_opts() :: [
  depth: pos_integer() | :all,
  title_prefix: String.t() | nil,
  ignore_case: boolean(),
  include_front_matter: boolean()
]

Options for bookmark_segments/2, PdfElixide.Editor.bookmark_segments/2 and PdfElixide.Editor.split_by_bookmarks/2.

• :depth — how deep in the outline a bookmark may sit and still start a segment: a positive integer, 1 being the top level, or :all. Defaults to 1.
• :title_prefix — start segments only at bookmarks whose title, with surrounding whitespace trimmed, begins with this string. Defaults to nil, which matches every bookmark.
• :ignore_case — match :title_prefix ignoring case, including letters whose case forms differ in length, such as ß and SS. Defaults to false.
• :include_front_matter — return the pages before the first matching bookmark as a segment of their own, with a nil title. Defaults to true.

@type chars_opts() :: [
  region: PdfElixide.Geometry.Rect.t() | nil,
  region_mode: region_mode(),
  exclude_layers: [String.t()],
  exclude_inks: [String.t()]
]

Options accepted by the chars and chars! functions.

• :region — a PdfElixide.Geometry.Rect keeping only the characters inside it. Defaults to nil.
• :region_mode — how :region matches; see region_mode/0. Defaults to :intersects.
• :exclude_layers — names of optional-content (OCG) layers to suppress, as listed by layers/1. Defaults to [].
• :exclude_inks — names of Separation/DeviceN inks to suppress, as listed by inks/3. Defaults to [].

@type dpi_opts() :: [{:dpi, pos_integer()}]

Options for separations/3, separation/4 and rasterize/2.

• :dpi — resolution in dots per inch. Defaults to 150, and must be positive.

These calls have a fixed per-page limit and return :unsupported above it. See Sizing the output.

@type extraction_profile() ::
  :conservative
  | :tj_heavy
  | :aggressive
  | :balanced
  | :academic
  | :policy
  | :form
  | :government
  | :scanned_ocr
  | :adaptive

A span-extraction tuning preset. A profile changes the TJ-offset and word-margin thresholds used to turn glyphs into spans, before any word clustering happens.

Passing one also changes how a rotated page's geometry is reported — see the "Legacy extraction controls" section of words_opts/0.

@type html_opts() :: [
  preserve_layout: boolean(),
  detect_headings: boolean(),
  extract_tables: boolean(),
  include_images: boolean(),
  embed_images: boolean(),
  image_output_dir: String.t() | nil,
  include_form_fields: boolean(),
  max_image_pixels: non_neg_integer() | nil,
  reading_order: :structure_tree | :column_aware | :top_to_bottom
]

Options accepted by the to_html and to_html! functions.

Only options that affect HTML output are exposed. Any other key raises ArgumentError — to_markdown/2's :bold_markers or :strip_running_headers_footers, say, or text/2's :expand_ligatures — as does a declared key given a value of the wrong type. See the "Errors versus exceptions" section of PdfElixide.Error.

• :preserve_layout — emit one absolutely positioned <div> per text span, carrying that span's coordinates and font size in inline CSS (pt units), in place of the semantic flow of <p>/<h1>/<ul> elements. Colour is written only for non-black text. This mode emits only those positioned spans: headings, lists and tables are not produced, so :detect_headings and :extract_tables have no effect under it. Defaults to false.

  The result is not directly renderable and needs two corrections from you. The generated CSS uses the PDF's own user-space coordinates verbatim, so top is measured from the bottom of the page while CSS top measures from the top: flip it with top = height - y, taking the page height from PdfElixide.Document.Page.height/1. And the per-page wrapper to_html/1 emits carries no styling, so it is not a positioned containing block — add position: relative and an explicit size to each wrapper, or every page will pile up in the same place.

• :detect_headings — cluster font sizes to emit <h1>–<h6> elements instead of plain <p> paragraphs. Defaults to true.

• :extract_tables — detect tables and render them as <table>/<thead>/<tbody> markup, with colspan and rowspan on the cells. Defaults to true.

• :include_images — emit <img> elements. Defaults to false for the reason given in markdown_opts/0. Images are appended to the end of the page in a <div class="page-images"> rather than placed at their position in the content.

• :embed_images — behaves exactly as it does for Markdown; see markdown_opts/0. Defaults to true.

• :image_output_dir — directory to write extracted images to, used only when :include_images is true and :embed_images is false. Behaves exactly as it does for Markdown, including the filename-collision caveat and the requirement that it be valid UTF-8 rather than an arbitrary path — see markdown_opts/0. Defaults to nil.

  It is interpolated into the src attribute without HTML escaping, so a directory whose name contains " or & produces malformed markup and a crafted one can inject attributes. Never build it from untrusted input. It is the only unescaped input here — see the "Escaping" section of to_html/2.

• :include_form_fields — inline AcroForm field values at their positions on the page. Defaults to true.

• :max_image_pixels — behaves exactly as it does for Markdown, including nil meaning the built-in 16 MP limit rather than "no limit"; see markdown_opts/0. Defaults to nil.

• :reading_order — behaves exactly as it does for Markdown; see markdown_opts/0. Defaults to :structure_tree.

Calling to_html/1 is equivalent to to_html/2 with no options.

@type inks_opts() :: [{:deep, boolean()}]

Options for inks/3.

• :deep — also walk into the Form XObjects the page's content stream invokes, returning every ink reachable from the page rather than only those it declares itself. Defaults to false.

The default reads the page's own /Resources and nothing else, so it can miss inks the page actually paints with — a colorant declared inside a Form XObject's own resources is absent from the list even though the extraction filters still honor it. deep: true returns the complete set.

What it costs is failure modes: deep: true parses the page's content stream and every form's, so it reports an error where the default would have succeeded — an undecryptable or malformed stream, or an XObject tree nested deeper than the parser follows. Prefer the default when the page's own declarations are enough, and deep: true when building a picker a user will choose from.

@type markdown_opts() :: [
  detect_headings: boolean(),
  extract_tables: boolean(),
  include_images: boolean(),
  embed_images: boolean(),
  image_output_dir: String.t() | nil,
  include_form_fields: boolean(),
  strip_running_headers_footers: boolean(),
  max_image_pixels: non_neg_integer() | nil,
  reading_order: :structure_tree | :column_aware | :top_to_bottom,
  bold_markers: :conservative | :aggressive
]

Options accepted by the to_markdown and to_markdown! functions.

• :detect_headings — cluster font sizes to emit # headings instead of plain paragraphs. Defaults to true.

• :extract_tables — detect tables and render them as Markdown tables. Defaults to true.

• :include_images — emit ![](…) image syntax. Defaults to false, since embedded images can add hundreds of kilobytes per page.

• :embed_images — when true, images are inlined as base64 data URIs and :image_output_dir is ignored. When false, they are written to :image_output_dir and referenced by path — and if that option is nil, no image is emitted at all. Only applies when :include_images is true. Defaults to true.

• :image_output_dir — directory to write extracted images to, used only when :include_images is true and :embed_images is false. It is created if missing, and one that cannot be created is an :io error; the writes themselves are best-effort, since an image that fails to encode or write is dropped. Defaults to nil.

  This is a String.t/0 and not a path in the sense the "File paths" section of PdfElixide describes: it is also pasted into the src attribute of every generated image reference, so it must be valid UTF-8 and a value that is not raises ArgumentError naming the key. A directory whose name has no UTF-8 spelling cannot be used here even where the filesystem allows one.

  Give every concurrent conversion its own directory. Filenames are fixed — pageN_M.png, one-based page then one-based position in that page's kept image list — so two conversions writing to one directory overwrite each other's files, non-atomically. That includes two conversions of the same document, since :max_image_pixels changes which images are kept and so renumbers the rest.

• :include_form_fields — inline AcroForm field values at their positions on the page. Defaults to true.

• :strip_running_headers_footers — drop text lines that repeat in the top/bottom band of a majority of pages. Defaults to false.

• :max_image_pixels — skip images whose width times height exceeds this count. nil means the built-in 16 MP limit, not "no limit" — pass a large integer to lift it, or 0 to skip every image. Defaults to nil.

• :reading_order — how text blocks are ordered: :structure_tree (follow a tagged PDF's structure tree, falling back to an XY-cut), :column_aware, or :top_to_bottom. Defaults to :structure_tree.

• :bold_markers — :conservative applies ** only to content-bearing text; :aggressive also wraps whitespace-only spans. Defaults to :conservative.

Calling to_markdown/1 is equivalent to to_markdown/2 with no options.

An unknown key, or a declared key given a value of the wrong type, raises ArgumentError naming the offending key; see the "Errors versus exceptions" section of PdfElixide.Error.

@type office_opts() :: [{:mode, :auto | :layout | :flow}]

Options accepted by to_docx/2, to_pptx/2 and to_xlsx/2, and their bang variants.

• :mode — how pages are laid out in the Office file. Defaults to :auto.
  • :layout places each run of text at its position on the PDF page.
  • :flow groups text into paragraphs or cells that flow like an ordinary document.
  • :auto uses :layout for short documents and :flow for long ones.

See Choosing a mode in the Office conversion guide for the trade-off, and Round trips before converting the result back to PDF.

An unknown key, or a :mode other than those three, raises ArgumentError.

@type open_opts() :: [{:password, binary() | nil}]

Options accepted by open/2, open!/2, from_binary/2, and from_binary!/2.

• :password — password used to authenticate against an encrypted PDF. When the password is wrong, the call returns {:error, %PdfElixide.Error{reason: :wrong_password}} (or raises, for the bang variants). When omitted or nil, only the empty password is tried automatically.

The password is a byte string, not necessarily valid UTF-8: a password for a PDF of encryption revision 4 or lower is PDFDocEncoded, so "caf" <> <<0xE9>> is a legitimate password that no UTF-8 spelling can express. authenticate/2 accepts and rejects exactly the same values.

To check a password against an already-open document without treating a wrong one as an error, use authenticate/2, which returns {:ok, false} rather than a :wrong_password error.

An unknown key, or a :password that is neither a binary nor nil, raises ArgumentError — see the "Errors versus exceptions" section of PdfElixide.Error.

@type page_text_opts() :: [
  extract_tables: boolean(),
  expand_ligatures: boolean(),
  table_detection: text_table_detection_opts() | nil,
  region: PdfElixide.Geometry.Rect.t() | nil,
  region_mode: region_mode(),
  exclude_regions: [PdfElixide.Geometry.Rect.t()],
  exclude_regions_mode: region_mode(),
  exclude_layers: [String.t()],
  exclude_inks: [String.t()]
]

Options for per-page text extraction: every text_opts/0 key except :on_page_error.

@type plain_text_opts() :: [
  extract_tables: boolean(),
  table_detection: text_table_detection_opts() | nil,
  reading_order: :structure_tree | :column_aware | :top_to_bottom,
  include_form_fields: boolean()
]

Options accepted by the to_plain_text and to_plain_text! functions.

• :extract_tables — detect tables and render them inline as space-padded, column-aligned rows. Defaults to true.
• :table_detection — a keyword list tuning the spatial table detector; see text_table_detection_opts/0. Only consulted when :extract_tables is true. Defaults to nil.
• :reading_order — how text blocks are ordered: :structure_tree, :column_aware or :top_to_bottom. Defaults to :structure_tree. On an untagged document, :structure_tree and :column_aware produce the same column-aware order; :top_to_bottom does not detect columns.
• :include_form_fields — inline AcroForm field values at their positions on the page. Defaults to true. text/2 has no such option and always includes them.

:reading_order and :include_form_fields have no effect when a trustworthy structure tree supplies the reading order. The Text extraction guide covers that case and compares these options with text_opts/0.

Calling to_plain_text/1 is equivalent to to_plain_text/2 with no options.

An unknown key, or a declared key given a value of the wrong type, raises ArgumentError naming the offending key; see the "Errors versus exceptions" section of PdfElixide.Error.

@type region_mode() :: :intersects | :fully_contained | {:min_overlap, float()}

How a :region (or :exclude_regions) decides whether an object is inside it.

• :intersects — any overlap at all counts. This is the default.
• :fully_contained — the object's bounding box must lie entirely within the region.
• {:min_overlap, ratio} — at least ratio of the object's area must lie within the region.

ratio must be between 0.0 and 1.0; anything outside that range raises ArgumentError, like any other bad option value. Two behaviors are worth knowing before choosing one:

• The fraction is of the object's own area, not the region's. A large element clipped by a small region scores low however much of the region it covers, so :min_overlap answers "how much of this object is in the region?", never the reverse.
• {:min_overlap, 0.0} matches everything, including objects that do not touch the region at all — a non-overlapping object scores 0.0, and the comparison is >=. Use :intersects if you meant "any overlap".

@type render_opts() :: [
  dpi: pos_integer(),
  format: PdfElixide.Document.RenderedPage.format(),
  background: PdfElixide.Color.RGB.t() | nil,
  render_annotations: boolean(),
  jpeg_quality: 1..100,
  exclude_layers: [String.t()],
  fit: {pos_integer(), pos_integer()} | nil,
  region: PdfElixide.Geometry.Rect.t() | nil,
  max_output_pixels: pos_integer() | nil
]

Options for render/3.

• :dpi — positive resolution in dots per inch. Defaults to 150.
• :format — :png (the default), :jpeg, or :rgba8 for bare premultiplied pixels; see PdfElixide.Document.RenderedPage for the layout.
• :background — a PdfElixide.Color.RGB with components in 0.0..1.0, or nil for transparent untouched areas. Defaults to opaque white. With :jpeg, nil leaves untouched areas black.
• :render_annotations — paint annotation appearances (form fields, stamps, highlights) over the page content. Defaults to true.
• :jpeg_quality — 1..100, defaulting to 85. Inert unless :format is :jpeg.
• :exclude_layers — names of optional-content groups to leave unpainted, from layers/1. Defaults to [].
• :fit — {width, height} in pixels to scale the page into, preserving its aspect ratio, so the result is no larger than the box on either axis. Both dimensions must be positive.
• :region — a PdfElixide.Geometry.Rect in PDF points in the page's raw, unrotated user space, clipped to the page. An empty intersection returns {:error, %PdfElixide.Error{reason: :out_of_range}}. There is no :region_mode. See Cropping with :region for using extractor boxes on rotated pages; PdfElixide.Geometry.Rect.to_user_space/3 maps a displayed box back.
• :max_output_pixels — a positive pixel budget. When set, scales an oversized render down instead of refusing it. It can only lower the library's own ceiling, never raise it: a budget above that ceiling is refused with %PdfElixide.Error{reason: :unsupported} naming the key. Defaults to nil, which preserves the requested scale or returns an error.

Cropping still renders the full page, so :region does not reduce rendering cost or the size limit. A :region render returns :unsupported when :max_output_pixels would require scaling the page first.

:region cannot be combined with format: :rgba8, and :fit cannot be combined with :dpi or :region. These combinations raise ArgumentError.

@type running_regions_opts() :: [area: :header | :footer | :both, threshold: float()]

Options accepted by the running_regions and running_regions! functions.

• :area — which running content to look for: :header, :footer or :both. Defaults to :both.
• :threshold — the fraction of pages, from 0.0 to 1.0, on which a line must repeat for heuristic detection. It is ignored for an area answered from tagged artifacts. Values outside the range raise ArgumentError. Defaults to 0.8.

@type search_opts() :: [
  literal: boolean(),
  case_insensitive: boolean(),
  whole_word: boolean(),
  max_results: non_neg_integer()
]

Options accepted by the search and search! functions.

• :literal — treat the pattern as plain text rather than a regular expression. Defaults to true; see the Text search guide for the regular expression syntax literal: false accepts.
• :case_insensitive — match regardless of case. Defaults to false.
• :whole_word — require a word boundary at each end of the match, so "cat" finds cat but not category. Defaults to false. The boundaries enclose the whole pattern: under literal: false, "cat|dog" finds cat and dog as whole words. A word boundary needs a word character on the inside, so a pattern that begins or ends in punctuation or whitespace — "(a)" on either path — matches only where the text has a word character right against it.
• :max_results — stop after this many matches, counted across pages. Defaults to 0, meaning no limit. This bounds the work as well as the list: searching the whole document stops at the page that reaches the limit, leaving the ones after it unread and unindexed.

There is no :page_range: searching one page is what search/3 and search/4 are for.

@type span_merging_opts() :: [
  preset: :default | :aggressive | :conservative | :adaptive | :legacy,
  space_threshold_em_ratio: float() | nil,
  conservative_threshold_pt: float() | nil,
  column_boundary_threshold_pt: float() | nil,
  severe_overlap_threshold_pt: float() | nil,
  use_adaptive_threshold: boolean() | nil,
  adaptive: adaptive_threshold_opts() | nil,
  detect_email_patterns: boolean() | nil,
  email_threshold_multiplier: float() | nil,
  detect_citation_markers: boolean() | nil,
  citation_font_size_ratio: float() | nil,
  merge_tm_tj_runs: boolean() | nil
]

Options tuning how glyph runs are merged into spans, accepted as :span_merging.

• :preset — the base configuration every other key overrides: :default, :aggressive (splits more readily), :conservative (merges across wider gaps), :adaptive (derives thresholds from page gap statistics), or :legacy. Defaults to :default. The names mean aggression about inserting spaces, so :aggressive produces more word boundaries, not fewer.
• :space_threshold_em_ratio — gap, as a fraction of font size, that becomes a space.
• :conservative_threshold_pt — floor gap in points below which no space is inserted.
• :column_boundary_threshold_pt — gap in points treated as a column break rather than a space.
• :severe_overlap_threshold_pt — negative gap indicating real glyph overlap.
• :use_adaptive_threshold — derive the space threshold from page gap statistics.
• :adaptive — a adaptive_threshold_opts/0 keyword list tuning that derivation. Only consulted when :use_adaptive_threshold resolves to true.
• :detect_email_patterns / :email_threshold_multiplier — keep addresses from being split at the @.
• :detect_citation_markers / :citation_font_size_ratio — treat small raised runs as citation markers.
• :merge_tm_tj_runs — when false, every text-matrix operator starts a fresh span. When true, one that stays on the same line and moves forward by less than a column gap continues the open span instead.

Every key except :preset defaults to nil, meaning "keep the preset's value".

@type spans_opts() :: [
  reading_order: :top_to_bottom | :column_aware | :structure_tree,
  span_merging: span_merging_opts() | nil,
  region: PdfElixide.Geometry.Rect.t() | nil,
  region_mode: region_mode(),
  exclude_layers: [String.t()],
  exclude_inks: [String.t()]
]

Options accepted by the spans and spans! functions.

• :reading_order — how spans are ordered: :top_to_bottom (simple geometric sorting), :column_aware (XY-cut column detection), or :structure_tree (column-aware order, with the cells of a tagged table reordered row-major by the structure tree; identical to :column_aware on an untagged document). The same values as markdown_opts/0, but the default here is :top_to_bottom.
• :span_merging — a span_merging_opts/0 keyword list, or nil for the default merging behavior. Defaults to nil.
• :region — a PdfElixide.Geometry.Rect keeping only the spans inside it. Defaults to nil.
• :region_mode — how :region matches; see region_mode/0. Defaults to :intersects.
• :exclude_layers — names of optional-content (OCG) layers to suppress, as listed by layers/1. Defaults to [].
• :exclude_inks — names of Separation/DeviceN inks to suppress, as listed by inks/3. Defaults to [].

:span_merging is exclusive with the other options

When :span_merging is set, only :region and :region_mode can be combined with it. Giving :reading_order, :exclude_layers or :exclude_inks a value other than its default raises ArgumentError naming the key.

@type structured_opts() :: [{:column_mode, :auto | :two | :single}]

Options accepted by the structured and structured! functions.

• :column_mode — how a two-column body is recognised. :auto splits only when a clear vertical gutter separates two columns of body text; :two always splits, at the detected gutter or else at the page's horizontal midpoint; :single never splits, so every region's :column is nil. Decides only :column; roles are unaffected. Defaults to :auto.

@type t() :: %PdfElixide.Document{
  page_count: non_neg_integer() | nil,
  ref: reference(),
  source_path: Path.t() | nil,
  version: {non_neg_integer(), non_neg_integer()}
}

A handle on an open PDF document.

:version and :page_count are cached when the document is opened and served from the struct thereafter, since both are immutable for a read-only document.

:page_count is nil when the count could not be determined at open — for example, when an encrypted document's page tree needs a password — in which case page_count/1 asks the document instead.

:ref is an internal handle; do not read it or construct the struct directly.

@type table_detection_opts() :: [
  preset: :default | :strict | :relaxed,
  enabled: boolean() | nil,
  horizontal_strategy: :lines | :text | :both | nil,
  vertical_strategy: :lines | :text | :both | nil,
  column_tolerance: float() | nil,
  row_tolerance: float() | nil,
  min_table_cells: non_neg_integer() | nil,
  min_table_columns: non_neg_integer() | nil,
  regular_row_ratio: float() | nil,
  max_table_columns: non_neg_integer() | nil,
  column_merge_threshold: float() | nil,
  v_split_gap: float() | nil,
  text_fallback: boolean() | nil
]

Options tuning the spatial table detector, accepted directly by the tables functions. For the text-conversion variant, see text_table_detection_opts/0.

• :preset — the base configuration every other key overrides: :default, :strict (demands ruling lines and regular rows) or :relaxed (tolerant, text-driven). Defaults to :default.
• :horizontal_strategy / :vertical_strategy — what evidence delimits cells on that axis: :lines (ruling lines only), :text (glyph alignment only) or :both.
• :column_tolerance / :row_tolerance — coordinate slack in points when grouping cells into columns and rows.
• :min_table_cells / :min_table_columns — smallest grid accepted as a table.
• :max_table_columns — reject anything wider as a false positive.
• :regular_row_ratio — fraction of rows that must share the column count.
• :column_merge_threshold — slack for the post-clustering column merge pass.
• :v_split_gap — minimum gap between vertical-line groups that splits a cluster.
• :text_fallback — allow text-only detection when a page has no ruling lines.
• :enabled — set to false to disable detection entirely.

Every key except :preset defaults to nil, meaning "keep the preset's value".

@type tables_opts() :: [
  region: PdfElixide.Geometry.Rect.t() | nil,
  region_mode: region_mode(),
  preset: :default | :strict | :relaxed,
  enabled: boolean() | nil,
  horizontal_strategy: :lines | :text | :both | nil,
  vertical_strategy: :lines | :text | :both | nil,
  column_tolerance: float() | nil,
  row_tolerance: float() | nil,
  min_table_cells: non_neg_integer() | nil,
  min_table_columns: non_neg_integer() | nil,
  regular_row_ratio: float() | nil,
  max_table_columns: non_neg_integer() | nil,
  column_merge_threshold: float() | nil,
  v_split_gap: float() | nil,
  text_fallback: boolean() | nil
]

Options accepted by the tables and tables! functions: every table_detection_opts/0 key, plus

• :region — a PdfElixide.Geometry.Rect keeping only the tables matching it. Defaults to nil. A table whose bbox is nil never matches a region.
• :region_mode — how :region matches; see region_mode/0. Defaults to :intersects.

Unlike the :table_detection option of the text functions, the detection keys are given flat here rather than nested under one key.

:region keeps the detection options you passed rather than loosening them. Pass preset: :relaxed to ask for that explicitly.

@type text_lines_opts() :: [
  include_artifacts: boolean(),
  region: PdfElixide.Geometry.Rect.t() | nil,
  region_mode: region_mode(),
  word_gap_threshold: float() | nil,
  line_gap_threshold: float() | nil,
  profile: extraction_profile() | nil
]

Options accepted by the text_lines and text_lines! functions.

The same options as words_opts/0 — including the legacy controls :word_gap_threshold and :profile documented there — plus:

• :line_gap_threshold — the vertical gap in points that starts a new line. nil computes it automatically. Defaults to nil; like the other two legacy controls, prefer leaving it unset.

:word_gap_threshold behaves differently here than it does on words/2,3: nothing re-joins the words a line is built from, so the threshold decides the boundaries within a run that a space has not already fixed.

@type text_opts() :: [
  extract_tables: boolean(),
  expand_ligatures: boolean(),
  table_detection: text_table_detection_opts() | nil,
  region: PdfElixide.Geometry.Rect.t() | nil,
  region_mode: region_mode(),
  exclude_regions: [PdfElixide.Geometry.Rect.t()],
  exclude_regions_mode: region_mode(),
  exclude_layers: [String.t()],
  exclude_inks: [String.t()],
  on_page_error: :skip | :halt
]

Options accepted by the text and text! functions.

• :extract_tables — detect tables and render them inline as space-padded, column-aligned rows, the padding collapsed to single spaces. Defaults to true; with it off, a recognised table's values come back as ordinary flow text. See "Tables inside a text result" in the Text extraction guide.
• :expand_ligatures — expand U+FB00–U+FB06 ligatures to their component letters (fi to fi, and so on). Defaults to false.
• :table_detection — a keyword list tuning the spatial table detector; see text_table_detection_opts/0. Only consulted when :extract_tables is true. Defaults to nil.
• :region — a PdfElixide.Geometry.Rect keeping only the text inside it. An extracted bbox can be handed straight back in. Defaults to nil.
• :region_mode — how :region matches; see region_mode/0. Defaults to :intersects.
• :exclude_regions — a list of rects whose text is dropped. Applied before :region, so exclusion wins. Defaults to [].
• :exclude_regions_mode — how :exclude_regions match. Defaults to :intersects.
• :exclude_layers — names of optional-content (OCG) layers to suppress, as listed by layers/1. Defaults to [].
• :exclude_inks — names of Separation/DeviceN inks to suppress, as listed by inks/3. Defaults to [].
• :on_page_error — what a page that fails to extract does to the whole-document result: :halt, failing the call with the first such page's error (the default), or :skip it. See below.

:on_page_error and partly extractable documents

Accepted only on the whole-document arity; per-page calls raise ArgumentError. Under the :halt default a failed page fails the call with {:error, %PdfElixide.Error{}}, the failing page's zero-based index prefixed to the message. :skip instead makes a failed page contribute an empty string; its page separator is emitted either way, and the call returns {:ok, text} with that page's content silently missing.

:halt is not a general corruption detector, though: almost every damaged page degrades to empty text rather than an error — an undecodable content stream, missing fonts, a scan with no text layer and an undecryptable document all extract as "". All it can catch is a page whose page-tree entry does not resolve at all — the same page every other whole-document call but fonts/1 fails on, as the "When a page cannot be read" section of PdfElixide.Document describes. Nor do those conditions leave a warning behind: neither structured_warnings/1 nor PdfElixide.Logging.structured_warnings/0 records them, and only PdfElixide.Logging capture makes them visible. The one exception is a page whose object ran into the end of the file before it could be read: it extracts as "" and records an :eof_premature warning on the document.

Layer and ink filtering is exclusive with the other options

When :exclude_layers or :exclude_inks is non-empty, only :region and :region_mode can be combined with it. Giving :extract_tables, :expand_ligatures, :table_detection, :exclude_regions or :exclude_regions_mode a value other than its default raises ArgumentError naming the key.

:reading_order, :include_form_fields and :strip_running_headers_footers are valid for to_markdown/2 but have no effect here, so they are not accepted; passing one raises ArgumentError, as any other undeclared key does.

There is a second way to read a page as text — to_plain_text/2, which returns reflowed paragraphs rather than the page's visual lines and takes a different, smaller set of options. The Text extraction guide compares the two.

@type text_table_detection_opts() :: [
  preset: :default | :strict | :relaxed,
  enabled: boolean() | nil,
  horizontal_strategy: :lines | :text | :both | nil,
  vertical_strategy: :lines | :text | :both | nil,
  column_tolerance: float() | nil,
  row_tolerance: float() | nil,
  min_table_cells: non_neg_integer() | nil,
  min_table_columns: non_neg_integer() | nil,
  regular_row_ratio: float() | nil,
  max_table_columns: non_neg_integer() | nil,
  column_merge_threshold: float() | nil,
  v_split_gap: float() | nil
]

The :table_detection option of the text and to_plain_text functions: every table_detection_opts/0 key except :text_fallback.

These functions never use the text-only fallback, so a page with no ruling lines yields no inline table. Passing :text_fallback raises ArgumentError; tables/2,3 accepts it.

@type words_opts() :: [
  include_artifacts: boolean(),
  region: PdfElixide.Geometry.Rect.t() | nil,
  region_mode: region_mode(),
  word_gap_threshold: float() | nil,
  profile: extraction_profile() | nil
]

Options accepted by the words and words! functions.

• :include_artifacts — keep spans tagged /Artifact (running headers and footers, page numbers, watermarks; ISO 32000-1 §14.8.2.2.1). Defaults to true; false selects the spec-correct variant.
• :region — a PdfElixide.Geometry.Rect keeping only the words inside it. Defaults to nil.
• :region_mode — how :region matches; see region_mode/0. Defaults to :intersects.
• :word_gap_threshold — the inter-glyph gap in points that starts a new word. nil computes it adaptively from page statistics (median character width × 0.3). Defaults to nil.
• :profile — a extraction_profile/0, or nil for none. Defaults to nil.

Legacy extraction controls

:word_gap_threshold and :profile are retained for compatibility but are deprecated. Prefer leaving them at nil.

• :word_gap_threshold may have no visible effect because words/2,3 can merge adjacent pieces again. text_lines/2,3 preserves those word boundaries; see text_lines_opts/0.

• :profile may change word order and bounding boxes, even when set to :conservative: a box shifts slightly on any page, and on a rotated one it comes back in raw user space rather than the displayed frame — see Rotated pages and extracted geometry.

:region composes with everything else here: it is applied after extraction, so it does not discard the thresholds or the profile.