Pentiment

Beautiful, compiler-style diagnostic messages for Elixir.

Features

• Rich source context — Highlighted code spans with line numbers and visual pointers
• Multiple labels — Primary and secondary annotations to show related code locations
• Helpful metadata — Error codes, notes, and actionable suggestions
• Flexible spans — Line/column positions, byte offsets, or deferred pattern search
• Elixir integration — Extract spans directly from AST metadata

Installation

def deps do
  [{:pentiment, "~> 0.1.0"}]
end

Quick Example

alias Pentiment.{Report, Label, Span, Source}

report =
  Report.error("Undefined variable")
  |> Report.with_code("E001")
  |> Report.with_source("lib/app.ex")
  |> Report.with_label(Label.primary(Span.position(10, 5), "not found in scope"))
  |> Report.with_help("did you mean `user`?")

source = Source.from_file("lib/app.ex")
IO.puts(Pentiment.format(report, source))

Use Cases

Pentiment is designed for:

• Compile-time macro errors — Validate DSL usage with precise source locations
• Parser error reporting — Convert parse failures into helpful diagnostics
• Configuration validation — Catch invalid keys and suggest corrections
• Custom linters — Build tools that report issues with rich context

Documentation

• Examples Overview — Integration patterns and quick start
• Config Validation — Compile-time config checking
• State Machine DSL — Multi-span errors
• Guard Restriction — AST walking patterns
• Parser Errors — NimbleParsec integration
• YAML Validation — Semantic file validation

Full API documentation available on HexDocs.