ansi_term.pl -- Print decorated text to ANSI consoles

This library allows for exploiting the color and attribute facilities of most modern terminals using ANSI escape sequences. This library provides the following:

ansi_format/3 allows writing messages to the terminal with ansi attributes.
It defines the hook prolog:message_line_element/2, which provides ansi attributes and hyperlinks for print_message/2.

The behavior of this library is controlled by two Prolog flags:

[99, 111, 108, 111, 114, 95, 116, 101, 114, 109]: When 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]: Emit terminal hyperlinks for url(Location) and url(URL, Label) elements of Prolog messages. The default is true if the environment identifies a terminal known to support OSC 8 hyperlinks.

See also: - http://en.wikipedia.org/wiki/ANSI_escape_code

ansi_format(+ClassOrAttributes, +Format, +Args) is det

ansi_format(+Stream, +ClassOrAttributes, +Format, +Args) is det

Format text with ANSI attributes. This predicate behaves as format/2 using Format and Args, but if the 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/3). The attribute names are derived from the ANSI specification. See the source for sgr_code/2 for details. Some commonly used attributes are:

bold
underline
fg(Color),bg(Color),hfg(Color),hbg(Color): For fg(Color) and bg(Color), the colour name can be '#RGB' or '#RRGGBB'
fg8(Spec),bg8(Spec): 8-bit color specification. Spec is a colour name, h(Color) or an integer 0..255.
fg(R,G,B),bg(R,G,B): 24-bit (direct color) specification. The components are integers in the range 0..255.
href(URL): Wrap the output as a link using ansi_hyperlink/3.

Defined color constants are below. default can be used to access the default color of the terminal.

black, red, green, yellow, blue, magenta, cyan, white

ANSI sequences are sent if and only if

The current_output has the property tty(true) (see stream_property/2).
The Prolog flag color_term is true.

ansi_sgr(+ClassOrAttributes, -Sequence:string) is det

True when Sequence is the ANSI Select Graphic Rendition sequence that activates the attributes of ClassOrAttributes. Sequence is the empty string if the Prolog flag color_term is 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`.

See also: - ansi_format/3 for the possible values of ClassOrAttributes.

prolog:console_color(+Theme, +Term, -AnsiAttributes) is semidet[multifile]

Hook that allows for mapping abstract terms to concrete ANSI attributes. This hook is used by theme files to adjust the rendering based on user preferences and context. Theme is the current theme: the value of the Prolog flag theme or, if no theme is selected, the theme of a loaded theme file. Defaults are defined in the file 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: The ?- prompt and its `| ` continuation.
input: The text typed by the user at the prompt.
answer(Parity): An answer written by the toplevel. Parity is 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.
binding(name): The variable name in a binding such as X = 1.

The debugger uses, besides frame(level) and port(Port):

goal(Port, Parity): The goal of a frame reported for Port. Parity is 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.

If Theme does not define Term, the theme it is based on is used (see prolog:theme_base/2).

See also: - library(theme/dark) for an example implementation and the Term values used by the system messages.

prolog:console_color(+Term, -AnsiAttributes) is semidet[multifile]

As prolog:console_color/3, but for any theme. This allows the user to define colours in the init file that apply to all themes.

prolog:theme_base(?Theme, ?Base) is nondet[multifile]

Hook that makes Theme a variation of the theme Base. If Theme does not define the colours of a class (prolog:console_color/3), those of Base are used, and so on. The same applies to the styles of the online help and the theme colours of the development tools. The theme file of Theme must load the theme file of Base, e.g.

:- module(prolog_theme_my_dark, []).
:- use_module(library(theme/dark)).
:- multifile prolog:theme/1, prolog:theme_base/2.

prolog:theme(my_dark).
prolog:theme_base(my_dark, dark).

prolog:message_line_element(+Stream, +Term) is semidet[multifile]

Hook implementation that colours the message elements produced by print_message_lines/3. Handled elements are:

ansi(Class, Fmt, Args)
ansi(Class, Fmt, Args, Ctx): Write Fmt/Args using the attributes of Class. As the element ends with a full reset, the 4th argument version re-installs the decoration of the message as a whole afterwards.
url(Location)
url(URL, Label): Write a hyperlink. See ansi_hyperlink/2,3. Label is an atom or string, a Format-Args pair or an ansi/3 or ansi/4 term. The latter combines a hyperlink with a style class.
begin(Class, Ctx)
end(Ctx): Decorate the message as a whole. See below.
nl(Ctx),flush(Ctx): End a line. If the message has a background colour, the remainder of the line is painted using `\e[K` (Erase in Line) such that the coloured block extends to the right margin.
eol(Ctx): As above, but also reset the attributes: this ends the decorated part of the line. A message uses this for its last line if that line is not ended using 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.

ansi_hyperlink(+Stream, +Location) is det

ansi_hyperlink(+Stream, +Location, +Label) is det

Create a hyperlink for a terminal emulator using the OSC 8 escape sequence. Location is one of

An absolute URL
An atom (interpreted as a file name)
A term File:Line
A term 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.

See also: - https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda

tty_url_hook(+Location, -URL)[multifile]

Hook for location_url/2.

ansi_get_color(+Which, -RGB) is semidet

Obtain the RGB color for an ANSI color parameter. Which is either a color alias or an integer ANSI color id. Defined aliases are foreground and background. This predicate sends a request to the console (user_output) and reads the reply. This assumes an xterm compatible terminal.

Arguments:

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.

Compatibility

- Up to version 10.1.13 the components were integers in the range 0..65535. The terminal reports one to four hexadecimal digits per component, so that range suggested a precision the reply does not have, and it clashed with the rgb/3 term of win_window_color/2, whose components are in the range 0..255.