This library allows for exploiting the color and attribute facilities of most modern terminals using ANSI escape sequences. This library provides the following:
The behavior of this library is controlled by two Prolog flags:
[|](99,
[111,108,111,114,95,116,101,114,109])true, activate the color output for this library.
Otherwise simply call format/3.
[|](104,
[121,112,101,114,108,105,110,107,95,116,101,114,109])url(Location) and url(URL, Label)
elements of Prolog messages.
current_output is a
terminal, it adds ANSI escape sequences according to Attributes. For
example, to print a text in bold cyan, do
?- ansi_format([bold,fg(cyan)], 'Hello ~w', [world]).
Attributes is either a single attribute, a list thereof or a term that is mapped to concrete attributes based on the current theme (see prolog:console_color/2). The attribute names are derived from the ANSI specification. See the source for sgr_code/2 for details. Some commonly used attributes are:
fg(Color), bg(Color), hfg(Color), hbg(Color)fg(Color) and bg(Color), the colour name
can be '#RGB' or
'#RRGGBB'
fg8(Spec), bg8(Spec)h(Color)
or an integer 0..255.
fg(R, G, B), bg(R,
G, B)Defined color constants are below. default can be used
to access the default color of the terminal.
ANSI sequences are sent if and only if
current_output has the property tty(true)
(see
stream_property/2).
true.
false or the class resolves to no attributes.
Unlike ansi_format/4
this does not write to a stream and thus does not require a terminal. It
is used to decorate strings that are handed to code that is not aware of
colors, notably the toplevel prompt (see the Prolog flag toplevel_prompt).
As the caller controls where the sequence ends up, the caller is also
responsible for verifying that the destination is a terminal and for
emitting the reset sequence ‘\e[0m`.
boot/messages.pl, default_theme/2.
Besides the classes used for messages (code, comment, var,
warning, error, truth(Truth), port(Port), message(Kind),
...), the interactive toplevel uses these:
?- prompt and its ‘| ‘
continuation.
odd
or even and alternates over the answers of a single query,
which allows for striping the answers using a background color.
Only an answer that shows bindings, residual goals or delays uses this
class: true. and false. are not answers to
stripe, and neither is the empty line that separates the answer from the
next query.
X = 1.
The debugger uses, besides frame(level) and port(Port):
odd
or even and alternates over the steps of a trace, which
allows for
striping the goals using a background color. Match on Port
to color the goal by port instead of (or in addition to) striping.
Note that a background color on prompt, input
or answer(_) is painted up to the right margin using ‘\e[K`.
A background on
goal(_,_) is not: the debugger writes its ?
prompt on the same line.
nl(Ctx), flush(Ctx)\e[K` (Erase in Line)
such that the coloured block extends to the right margin.
nl. Resetting matters because a terminal that
scrolls while a background colour is in effect paints the newly exposed
line with it.
Ctx is the message context. It is created by the handler for begin/2 as a term
ansi(Reset, ReInstall, EraseEol)
where Reset is the sequence written by end/1,
ReInstall is a Format-Args pair that re-installs the attributes of the
message and EraseEol is the sequence that paints the remainder of the
line or the empty atom. Callers must treat Ctx as opaque. It is left
unbound if Stream is not a terminal, if the color_term
flag is
false or if the message has no attributes. All handlers
that use Ctx therefore fail if it is unbound, which makes
print_message_lines/3
fall back to writing plain text.
OSC 8
escape sequence. Location is one of
File:Line
File:Line:Column
There is no official standard for encoding the Line and Column. We emit
``file://AbsFileName[#Line[:Column]]``
Both Line and Column count from 1, as in the
messages we print and as used by e.g., rg --hyperlink-format=....
Note that a capital L before the line, as used by GitHub,
is accepted by Epilog as well.
The sequence is emitted if and only if the Prolog flag
hyperlink_term is true and Stream
has the property tty(true).
ansi_format/4 is
guarded the same way for color_term, so that a message
captured using with_output_to/2
is plain text.
foreground and background. This predicate
sends a request to the console (user_output) and reads the
reply. This assumes an xterm compatible terminal.
| RGB | is a term rgb(Red,Green,Blue).
The color components are floats in the range 0.0..1.0. They are sRGB
encoded, as that is what the terminal reports; linearise them before
doing colour arithmetic that assumes light intensities. |