clj-commons.pretty.annotations — org.clj-commons/pretty 3.6.7

Tools to annotate a line of source code, in the form of callouts (lines and arrows) connected to a message.

SELECT DATE, AMT FROM PAYMENTS WHEN AMT > 10000
             ▲▲▲               ▲▲▲▲
             │                 │
             │                 └╴ Unknown token
             │
             └╴ Invalid column name

This kind of output is common with various kinds of parsers or interpreters.

Specs for types and functions are in the [[spec]] namespace.

*default-style* clj

The default style used when no style is provided; some applications may bind or override this.

annotate-lines clj

(annotate-lines lines)

(annotate-lines opts lines)

Intersperses numbered lines with callouts to form a new sequence of composable strings where input lines are numbered, and callout lines are indented beneath the input lines.

Example:

1: SELECT DATE, AMT
          ▲▲▲
          │
          └╴ Invalid column name
2: FROM PAYMENTS WHEN AMT > 10000
                 ▲▲▲▲
                 │
                 └╴ Unknown token

Each line is a map:

Key	Value
:line	Composed string for a single line of input (usually, just a string)
:annotations	Optional, a seq of annotation maps (used to create the callouts)

Option keys are all optional:

Key	Value
:style	style map (for callouts), defaults to [default-style]
:start-line	Defaults to 1
:line-number-width	Width for the line numbers column, or 0 for no line numbers

The :line-number-width option is usually computed from the maximum line number that will be output.

Returns a seq of composed strings, each representing a single line of output. For example, (run! ansi/perr (annotation-lines ...)).

callouts clj

(callouts annotations)

(callouts style annotations)

Creates callouts (the marks, bars, and messages from the example) from annotations.

Each annotation is a map:

Key	Description
:message	Composed string of the message to present
:offset	Integer position (from 0) to mark on the line
:length	Number of characters in the marker (min 1, defaults to 1)
:font	Override of the style's font; used for marker, bars, nib, and message
:marker	Override of the style's marker

The leftmost column has offset 0; some frameworks may report this as column 1 and an adjustment is necessary before invoking callouts.

At least one annotation is required; they will be sorted into an appropriate order. Annotation's ranges should not overlap.

The messages should be relatively short, and not contain any line breaks.

Returns a sequence of composed strings, one for each line of output.

The calling code is responsible for any output; even the line being annotated; this might look something like:

(ansi/perr source-line)
(run! ansi/perr (annotations/annotate annotations))

Uses the style defined by *default-style* if no style is provided.

default-style clj

The default style used when generating callouts.

Key	Default	Description
:font	:yellow	Default font characteristics if not overrided by annotation
:spacing	:compact	One of :tall, :compact, or :minimal
:marker	"▲"	The marker used to identify the offset/length of an annotation
:bar	"│"	Character used as the vertical bar in the callout
:nib	"└╴ "	String used just before the annotation's message

When :spacing is :minimal, only the lines with markers or error messages appear (the lines with just vertical bars are omitted). :compact spacing is the same, but one line of bars appears between the markers and the first annotation message.

The :marker is used to build a string that matches the :length of the callout.

:marker can be a single string, which is repeated.

:marker can be a three-character string. The middle character is repeated to pad the marker to the necessary length.

:marker can also be a function; the function is passed the length and returns a string (or composed string) that must be that number of characters wide.

Note: rendering of Unicode characters in HTML often uses incorrect fonts or adds unwanted character spacing; the annotations look proper in console output.

underline-marker clj

(underline-marker length)

Marker function that renders as a heavy underline.