Pentiment

Beautiful, compiler-style diagnostic messages for Elixir.

State machine error example

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.

Next Page → Examples Overview