% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\section{library(ansi_term): Print decorated text to ANSI consoles}

\label{sec:ansiterm}

\begin{tags}
    \tag{See also}
\url{http://en.wikipedia.org/wiki/ANSI_escape_code}
\end{tags}

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

\begin{itemize}
    \item \predref{ansi_format}{3} allows writing messages to the terminal with ansi
attributes.
    \item It defines the hook \qpredref{prolog}{message_line_element}{2}, which provides
ansi attributes and hyperlinks for \predref{print_message}{2}.
\end{itemize}

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

\begin{description}
    \termitem{\Scons}{99, [111,108,111,114,95,116,101,114,109]}
When \const{true}, activate the color output for this library. Otherwise
simply call \predref{format}{3}.
    \termitem{\Scons}{104, [121,112,101,114,108,105,110,107,95,116,101,114,109]}
Emit terminal hyperlinks for \verb$url(Location)$ and \verb$url(URL, Label)$
elements of Prolog messages.
\end{description}

\vspace{0.7cm}

\begin{description}
    \predicate[det]{ansi_format}{3}{+ClassOrAttributes, +Format, +Args}
\arg{Format} text with ANSI attributes. This predicate behaves as
\predref{format}{2} using \arg{Format} and \arg{Args}, but if the \verb$current_output$ is a
terminal, it adds ANSI escape sequences according to Attributes.
For example, to print a text in bold cyan, do

\begin{code}
?- ansi_format([bold,fg(cyan)], 'Hello ~w', [world]).
\end{code}

Attributes is either a single attribute, a list thereof or a term
that is mapped to concrete attributes based on the current theme
(see \qpredref{prolog}{console_color}{2}). The attribute names are derived from
the ANSI specification. See the source for \predref{sgr_code}{2} for details.
Some commonly used attributes are:

\begin{description}
    \termitem{bold}{}
    \termitem{underline}{}
    \infixtermitem{\Scomma}{\term{fg}{Color}}{\infixterm{\Scomma}{\term{bg}{Color}}{\infixterm{\Scomma}{\term{hfg}{Color}}{\term{hbg}{Color}}}}
For \verb$fg(Color)$ and \verb$bg(Color)$, the colour name can be '\#RGB' or
'\#RRGGBB'
    \infixtermitem{\Scomma}{\term{fg8}{Spec}}{\term{bg8}{Spec}}
8-bit color specification. \arg{Spec} is a colour name, \verb$h(Color)$
or an integer 0..255.
    \infixtermitem{\Scomma}{\term{fg}{R, G, B}}{\term{bg}{R, G, B}}
24-bit (direct color) specification. The components are
integers in the range 0..255.
\end{description}

Defined color constants are below. \const{default} can be used to
access the default color of the terminal.

\begin{itemize}
    \item black, red, green, yellow, blue, magenta, cyan, white
\end{itemize}

ANSI sequences are sent if and only if

\begin{shortlist}
    \item The \verb$current_output$ has the property \verb$tty(true)$ (see
\predref{stream_property}{2}).
    \item The Prolog flag \verb$color_term$ is \const{true}.
\end{shortlist}

\qpredicate[semidet,multifile]{prolog}{console_color}{2}{+Term, -AnsiAttributes}Hook that allows for mapping abstract terms to concrete ANSI
attributes. This hook is used by \textit{theme} files to adjust the
rendering based on user preferences and context. Defaults are
defined in the file \verb$boot/messages.pl$.

\begin{tags}
    \tag{See also}
\file{library(theme/dark)} for an example implementation and the \arg{Term}
values used by the system messages.
\end{tags}

\qpredicate[semidet,multifile]{prolog}{message_line_element}{2}{+Stream, +Term}Hook implementation that deals with \verb$ansi(+Attr, +Fmt, +Args)$ in
message specifications.

    \predicate[det]{ansi_hyperlink}{2}{+Stream, +Location}
\nodescription
    \predicate[det]{ansi_hyperlink}{3}{+Stream, +URL, +Label}
Create a hyperlink for a terminal emulator. The file is fairly easy,
but getting the line and column across is not as there seems to be
no established standard. The current implementation emits, i.e.,
inserting a capital \verb$L$ before the line.

\begin{code}
``file://AbsFileName[#LLine[:Column]]``
\end{code}

\begin{tags}
    \tag{See also}
\url{https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda}
\end{tags}

    \predicate[semidet]{ansi_get_color}{2}{+Which, -RGB}
Obtain the \arg{RGB} color for an ANSI color parameter. \arg{Which} is either a
color alias or an integer ANSI color id. Defined aliases are
\const{foreground} and \const{background}. This predicate sends a request to the
console (\verb$user_output$) and reads the reply. This assumes an \const{xterm}
compatible terminal.

\begin{arguments}
\arg{RGB} & is a term \verb$rgb(Red,Green,Blue)$. The color components are
integers in the range 0..65535. \\
\end{arguments}
\end{description}