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



\section{library(portray_text): Portray text}

\label{sec:portraytext}

SWI-Prolog has the special string data type. However, in Prolog, text
may be represented more traditionally as a list of character-codes, i.e.
(small) integers (in SWI-Prolog specifically, those are Unicode code
points). This results in output like the following (here using the
backquote notation which maps text to a list of codes):

\begin{code}
?- writeln(`hello`).
[104, 101, 108, 108, 111]

?- atom_codes("hello",X).
X = [104,101,108,108,111].
\end{code}

Unless you know the Unicode tables by heart, this is pretty unpleasant
for debugging. Loading \file{library(portray_text)} makes the toplevel and
debugger consider certain lists of integers as text and print them as
text. This is called "portraying". Of course, interpretation is
imperfect as there is no way to tell in general whether \verb$[65,66]$ should
written as \verb$`AB`$ or as \verb$[65,66]$. Therefore it is important that the
user be aware of the fact that this conversion is enabled. This is why
this library must be loaded explicitly.

To be able to copy the printed representation and paste it back, printed
text is enclosed in \textit{back quotes} if \predref{current_prolog_flag}{2} for the flag
\verb$back_quotes$ is \const{codes} (the default), and enclosed in \textit{double quotes}
otherwise. Certain control characters are printed out in
backslash-escaped form.

The default heuristic only considers list of codes as text if the codes
are all from the set of 7-bit ASCII without most of the control
characters. A code is classified as text by \predref{text_code}{1}, which in turn
calls \predref{is_text_code}{1}. Define \qpredref{portray_text}{is_text_code}{1} to succeed on
additional codes for more flexibility (by default, that predicate
succeeds nowhere). For example:

\begin{code}
?- maplist([C,R]>>(portray_text:text_code(C)->R=y;R=n),
           `G\u00e9n\u00e9rateur`,Results).
Results = [y,n,y,n,y,y,y,y,y,y].
\end{code}

Now make \predref{is_text_code}{1} accept anything:

\begin{code}
?- [user].
|: portray_text:is_text_code(_).
|: ^D
% user://3 compiled 0.00 sec, 1 clauses
true.
\end{code}

Then:

\begin{code}
?- maplist([C,R]>>(portray_text:text_code(C)->R=y;R=n),
           `G\u00e9n\u00e9rateur`,Results).
Results = [y,y,y,y,y,y,y,y,y,y].
\end{code}

\vspace{0.7cm}

\begin{description}
    \predicate[det]{portray_text}{1}{+OnOff:boolean}
Switch portraying on or off. If \const{true}, consider lists of integers
as list of Unicode code points and print them as corresponding text
inside quotes: \verb$`text`$ or \verb$"text"$. Quoting depends on the
value of \predref{current_prolog_flag}{2} \verb$back_quotes$. Same as

\begin{code}
?- set_portray_text(enabled, true).
\end{code}

    \predicate[det]{set_portray_text}{2}{+Key, +Value}
\nodescription
    \predicate[det]{set_portray_text}{3}{+Key, ?Old, +New}
Set options for portraying. Defined Keys are:

\begin{description}
    \termitem{enabled}{}
Enable/disable portray text
    \termitem{min_length}{}
Only consider for conversion lists of integers
that have a length of at least \arg{Value}. Default is 3.
    \termitem{ellipsis}{}
When converting a list that is longer than \arg{Value}, elide the
output at the start using ellipsis, leaving only \arg{Value} number of
non-elided characters: \verb$`...end`$
\end{description}

    \predicate[semidet,multifile]{is_text_code}{1}{+Code:nonneg}
Multifile hook that can be used to extend the set of character codes
that is recognised as likely text. By default, \predref{is_text_code}{1} fails
everywhere and internally, only non-control ASCII characters
(32-126) and the the control codes (9,10,13) are accepted.

\begin{tags}
    \tag{To be done}
we might be able to use the current locale to include the
appropriate code page. (Does that really make sense?)
\end{tags}
\end{description}