% 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 for \predref{print_message}{2}.
\end{itemize}

\vspace{0.7cm}

\begin{description}
    \predicate[det]{ansi_format}{3}{+Attributes, +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 \arg{Attributes}.
For example, to print a text in bold cyan, do

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

\arg{Attributes} is either a single attribute or a list thereof. 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{shortlist}
    \item bold
    \item underline
    \item \verb$fg(Color)$, \verb$bg(Color)$, \verb$hfg(Color)$, \verb$hbg(Color)$
\end{shortlist}

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}{message_line_element}{2}{+Stream, +Term}Hook implementation that deals with \verb$ansi(+Attr, +Fmt, +Args)$ in
message specifications.
\end{description}

