NativeElixirPdfUtilities.Diagnostics (native_elixir_pdf_utilities v0.6.0)

View Source

Shared diagnostic helpers for public API errors.

Public operations return diagnostic errors as {:error, {reason, diagnostic}} when the library can explain why an operation cannot continue. The diagnostic map always includes :stage, :reason, and :message, and may include actionable context such as :operation, :module, :line, :column, or :source.

Summary

Types

detailed_error()
diagnostic()
diagnostic_option()

Functions

diagnostic(stage, reason, message, opts \\ [])

Builds a diagnostic map for a public API failure.

error(stage, reason, message, opts \\ [])

Builds a standard {:error, {reason, diagnostic}} result.

with_context(diagnostic, opts \\ [])

Adds operation, module, or source context to an existing diagnostic map.

Types

detailed_error()

@type detailed_error() :: {atom(), diagnostic()}

diagnostic()

@type diagnostic() :: %{
  :stage => atom(),
  :reason => atom(),
  :message => String.t(),
  optional(:operation) => atom(),
  optional(:module) => module(),
  optional(:line) => pos_integer(),
  optional(:column) => pos_integer(),
  optional(:source) => String.t()
}

diagnostic_option()

@type diagnostic_option() ::
  {:operation, atom()}
  | {:module, module()}
  | {:line, pos_integer()}
  | {:column, pos_integer()}
  | {:source, String.t()}
  | {:source, nil}

Functions

diagnostic(stage, reason, message, opts \\ [])

@spec diagnostic(atom(), atom(), String.t(), [diagnostic_option()]) :: diagnostic()

Builds a diagnostic map for a public API failure.

error(stage, reason, message, opts \\ [])

@spec error(atom(), atom(), String.t(), [diagnostic_option()]) ::
  {:error, detailed_error()}

Builds a standard {:error, {reason, diagnostic}} result.

with_context(diagnostic, opts \\ [])

@spec with_context(diagnostic(), [diagnostic_option()]) :: diagnostic()

Adds operation, module, or source context to an existing diagnostic map.