A labeled span for annotating source code in diagnostics.
Labels combine a span with a message and visual priority. They are used to highlight specific regions of source code and explain what's happening there.
Labels have two priority levels:
:primary - The main error location, highlighted prominently (typically red):secondary - Supporting context, highlighted less prominently (typically yellow)For diagnostics that span multiple files, set the :source field to identify
which file this label refers to. The rich formatter renders such labels as
continuation frames (├─[file:line:col]) against their own file, inside the
same diagnostic frame — provide content for every labeled file in the sources
passed to Pentiment.format/3, or the foreign group renders header-only.
A label whose :source equals the report's source behaves exactly as if it
were nil.
# Primary label at the error site
Label.primary(span, "expected `integer`, found `float`")
# Secondary label showing related context
Label.secondary(decl_span, "declared as `integer` here")
# Label in a different file
Label.primary(span, "error here", source: "lib/other.ex")Creates a bracket label that highlights a multi-line block.
Returns true if this is a bracket label.
Creates a new label.
Creates a primary (error site) label.
Returns true if this is a primary label.
Returns the resolved span as a Pentiment.Span.t().
Creates a secondary (context) label.
Returns true if this is a secondary label.
@type priority() :: :primary | :secondary
@type style() :: :inline | :bracket
@type t() :: %Pentiment.Label{ message: String.t() | nil, priority: priority(), source: String.t() | nil, span: Pentiment.Span.t() | Pentiment.Spannable.t(), style: style() }
@spec bracket( Pentiment.Span.t() | Pentiment.Spannable.t(), String.t() | nil, keyword() ) :: t()
Creates a bracket label that highlights a multi-line block.
Bracket labels draw a vertical bar (┃) in the left margin across a range
of lines, with a ╰── message tail below. The span must cover the full
line range (use end_line in the position span).
iex> Label.bracket(span, "property `no_stuck_states` failed")
%Label{span: span, message: "property `no_stuck_states` failed", style: :bracket}Returns true if this is a bracket label.
@spec new( Pentiment.Span.t() | Pentiment.Spannable.t(), keyword() ) :: t()
Creates a new label.
:message - The annotation message (optional):priority - :primary or :secondary (default: :primary):style - :inline or :bracket (default: :inline):source - Source identifier for multi-file diagnostics (optional)iex> Label.new(span, message: "error here")
%Label{span: span, message: "error here", priority: :primary, source: nil}@spec primary( Pentiment.Span.t() | Pentiment.Spannable.t(), String.t() | nil, keyword() ) :: t()
Creates a primary (error site) label.
Primary labels are highlighted prominently and represent the main location of the diagnostic.
iex> Label.primary(span, "expected `integer`")
%Label{span: span, message: "expected `integer`", priority: :primary}
iex> Label.primary(span)
%Label{span: span, message: nil, priority: :primary}Returns true if this is a primary label.
@spec resolved_span(t()) :: Pentiment.Span.t()
Returns the resolved span as a Pentiment.Span.t().
If the label's span implements Pentiment.Spannable, it is converted.
@spec secondary( Pentiment.Span.t() | Pentiment.Spannable.t(), String.t() | nil, keyword() ) :: t()
Creates a secondary (context) label.
Secondary labels provide supporting context and are highlighted less prominently than primary labels.
iex> Label.secondary(span, "declared here")
%Label{span: span, message: "declared here", priority: :secondary}Returns true if this is a secondary label.