Diagnostics

View Source

Native Elixir PDF Utilities returns recoverable public API failures as {:error, {reason, diagnostic}} when the library can explain why an operation cannot continue.

The reason atom is intended for programmatic branching. The diagnostic map is intended for developer debugging, logs, and user-facing support messages.

Diagnostic Fields

Diagnostic maps always include:

  • :stage - the pipeline or utility stage that failed
  • :reason - the machine-readable reason atom
  • :message - a human-readable explanation

Diagnostic maps may also include:

  • :operation - the public API or file operation being performed
  • :module - the public module returning the error
  • :source - a path, source snippet, or caller-provided input label
  • :line and :column - source location details when parser input can be located

Example

case NativeElixirPdfUtilities.Text.extract_file(path) do
  {:ok, text} ->
    text

  {:error, {_reason, diagnostic}} ->
    Logger.warning(diagnostic.message)
end

Example Diagnostic

{:error,
 {:invalid_path,
  %{
    stage: :file,
    reason: :invalid_path,
    message: "path must be a string",
    operation: :extract_file,
    module: NativeElixirPdfUtilities.Text
  }}}

Contributor Guidance

Use NativeElixirPdfUtilities.Diagnostics for new public API failures instead of inventing per-module error shapes.

Do not raise for ordinary caller/input failures such as invalid paths, missing files, unsupported documents, unsupported HTML/CSS, or empty extraction results. Prefer diagnostic error tuples and add focused tests that assert the important fields.

Malformed PDF Input

Merge.merge/1 and Text.extract/2 validate tokenized PDF input before continuing. Malformed classic PDF input returns an :invalid_pdf_input diagnostic rather than producing partial output or raising.

The tokenizer represents malformed literal and hexadecimal strings as {:error, reason} tokens. This is primarily useful to callers using NativeElixirPdfUtilities.Tokenizer directly; merge and text extraction convert such tokenization failures into their public diagnostic error shape.

To protect extraction from resource exhaustion, text extraction ignores ToUnicode CMaps that exceed its input or mapping-entry limits. It continues using the remaining supported text data and may return :empty_pdf_text when no extractable text remains.