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

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.

add-callout clj

(add-callout annotation-set line callout-opts & message)

Adds a callout to an annotation set. Options are the same as for callouts, (:offset, :length, :font, :marker) though a :message key is added to the options.

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 ...)).

This is an older function, the new annotation-set approach is easier.

callouts clj

(callouts annotations)

(callouts style annotations)

(callouts style
          annotations
          {:keys [width reroute-width]
           :or {width Long/MAX_VALUE reroute-width 30}})

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, bend, 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 (as defined by :offset and :length) should not overlap.

Messages should be short, or will be word-wrapped if the :width option is provided.

Options:

Key	Description
:width	Total width to wrap annotations
:reroute-width	Minimum width to avoid rerouting. Default: 30

Rerouting: if the rightmost annotation has less than :reroute-width characters for the annotation text, then the annotation columns are rerouted to columns 0, 2, 4, etc. The :bend (from the style) is extended and used to connect the old annotaton column with its new assigned column.

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.

create-annotation-set clj

(create-annotation-set lines)

(create-annotation-set lines opts)

Creates an annotation set from a seq of lines.

Options:

:width - number (default: 120). Total width available for line numbers, callouts, and annotation text. Annotation text will be soft-wrapped to fit within the available space. :window - number (default: 2) of lines before and after an annotated line to display (for context) :line-offset - number (default 1) adjustment to actual line number when rendering

If you are using io.github.hlship/cli-tools, then net.lewisship.cli-tools.terminal/*terminal-width* is a source for the actual terminal width.

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
:bend	"┌─┘"	String used when changing the column of an annotation

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.

Note the intentional space at the end of the default :nib value.

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.

:bend is used when the column for an annotation must be rerouted; like a marker, it is a three character string that may be extended by repeating the middle character.

:bar, :nib, and :bend must be simple, not composed, strings.

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

render-annotation-set clj

(render-annotation-set annotation-set)

Invoked once all callouts have been added to the annotation set. Returns a seq of composed strings, each a single rendered line.

underline-marker clj

(underline-marker length)

Marker function that renders as a heavy underline.