/*  Part of SWI-Prolog

    Author:        Jan Wielemaker
    E-mail:        J.Wielemaker@vu.nl
    WWW:           http://www.swi-prolog.org
    Copyright (c)  2009-2021, University of Amsterdam
                              CWI, Amsterdam
                              SWI-Prolog Solutions b.v.
    All rights reserved.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:

    1. Redistributions of source code must retain the above copyright
       notice, this list of conditions and the following disclaimer.

    2. Redistributions in binary form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in
       the documentation and/or other materials provided with the
       distribution.

    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
    COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
    BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
    POSSIBILITY OF SUCH DAMAGE.
*/

:- module(portray_text,
          [ portray_text/1,             % +Bool
            set_portray_text/2,         % +Name, +Value
            set_portray_text/3,         % +Name, ?Old, +Value

            '$portray_text_enabled'/1
          ]).
:- autoload(library(error), [must_be/2, domain_error/2]).

:- multifile
    is_text_code/1.                     % +Integer

/** <module> Portray text

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):

```
?- writeln(`hello`).
[104, 101, 108, 108, 111]

?- atom_codes("hello",X).
X = [104,101,108,108,111].
```

Unless you know the Unicode tables by   heart, this is pretty unpleasant
for debugging. Loading 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 `[65,66]` should
written as =|`AB`|= or as `[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 _back quotes_  if current_prolog_flag/2 for the flag
`back_quotes` is `codes` (the default), and  enclosed in _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 text_code/1, which in turn
calls is_text_code/1. Define portray_text:is_text_code/1   to succeed on
additional codes for  more  flexibility   (by  default,  that  predicate
succeeds nowhere). For example:

```
?- 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].
```

Now make is_text_code/1 accept anything:

```
?- [user].
|: portray_text:is_text_code(_).
|: ^D
% user://3 compiled 0.00 sec, 1 clauses
true.
```

Then:

```
?- 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].
```
*/

:- dynamic
    portray_text_option/2.

portray_text_option(enabled, true).
portray_text_option(min_length, 3).
portray_text_option(ellipsis,  30).

pt_option(enabled,    boolean).
pt_option(min_length, nonneg).
pt_option(ellipsis,   nonneg).

%!  portray_text(+OnOff:boolean) is det.
%
%   Switch portraying on or off. If   `true`, consider lists of integers
%   as list of Unicode code points and  print them as corresponding text
%   inside quotes: =|`text`|= or  =|"text"|=.   Quoting  depends  on the
%   value of current_prolog_flag/2 `back_quotes`.  Same as
%
%       ?- set_portray_text(enabled, true).

portray_text(OnOff) :-
    set_portray_text(enabled, OnOff).

%!  set_portray_text(+Key, +Value) is det.
%!  set_portray_text(+Key, ?Old, +New) is det.
%
%   Set options for portraying.  Defined Keys are:
%
%     - enabled
%       Enable/disable portray text
%     - min_length
%       Only consider for conversion lists of integers
%       that have a length of at least Value. Default is 3.
%     - ellipsis
%       When converting a list that is longer than Value, elide the
%       output at the start using ellipsis, leaving only Value number of
%       non-elided characters: =|`...end`|=

set_portray_text(Key, New) :-
    set_portray_text(Key, _, New).
set_portray_text(Key, Old, New) :-
    nonvar(Key),
    pt_option(Key, Type),
    !,
    portray_text_option(Key, Old),
    (   Old == New
    ->  true
    ;   must_be(Type, New),
        retractall(portray_text_option(Key, _)),
        assert(portray_text_option(Key, New))
    ).
set_portray_text(Key, _, _) :-
    domain_error(portray_text_option, Key).


:- multifile
    user:portray/1.
:- dynamic
    user:portray/1.

user:portray(Codes) :-
    portray_text_option(enabled, true),
    '$skip_list'(Length, Codes, _Tail),
    portray_text_option(min_length, MinLen),
    Length >= MinLen,
    all_codes(Codes),
    portray_text_option(ellipsis, IfLonger),
    quote(C),
    put_code(C),
    (   Length > IfLonger
    ->  First is IfLonger - 5,
        Skip is Length - 5,
        skip_first(Skip, Codes, Rest),
        put_n_codes(First, Codes, C),
        format('...', [])
    ;   Rest = Codes
    ),
    put_var_codes(Rest, C),
    put_code(C).

quote(0'`) :-
    current_prolog_flag(back_quotes, codes),
    !.
quote(0'").

put_n_codes(N, [H|T], C) :-
    N > 0,
    !,
    emit_code(H, C),
    N2 is N - 1,
    put_n_codes(N2, T, C).
put_n_codes(_, _, _).

skip_first(N, [_|T0], T) :-
    succ(N2, N),
    !,
    skip_first(N2, T0, T).
skip_first(_, L, L).

put_var_codes(Var, _) :-
    var_or_numbered(Var),
    !,
    format('|~p', [Var]).
put_var_codes([], _).
put_var_codes([H|T], C) :-
    emit_code(H, C),
    put_var_codes(T, C).

emit_code(Q, Q)    :- !, format('\\~c', [Q]).
emit_code(0'\b, _) :- !, format('\\b').
emit_code(0'\r, _) :- !, format('\\r').
emit_code(0'\n, _) :- !, format('\\n').
emit_code(0'\t, _) :- !, format('\\t').
emit_code(C, _) :- put_code(C).

all_codes(Var) :-
    var_or_numbered(Var),
    !.
all_codes([]).
all_codes([H|T]) :-
    is_code(H),
    all_codes(T).

is_code(Term) :-
    integer(Term),
    Term >= 0,
    text_code(Term),
    !.

% Idea: Maybe accept anything and hex-escape anything non-printable?
%       In particular, I could imaging 0 and ESC appearing in text of interest.
%       Currently we really accept only 7-bit ASCII so even latin-1 text
%       precludes recognition.
% Bug?: emit_code/2 can emit backspace but backspace (8) is not accepted below

text_code(Code) :-
    is_text_code(Code),
    !.
text_code(9).      % horizontal tab, \t
text_code(10).     % newline \n
text_code(13).     % carriage return \r
text_code(C) :-    % space to tilde (127 is DEL)
    between(32, 126, C).

var_or_numbered(Var) :-
    var(Var),
    !.
var_or_numbered('$VAR'(_)).

%!  is_text_code(+Code:nonneg) is semidet.
%
%   Multifile hook that can be used to extend the set of character codes
%   that is recognised as likely text.  By default, 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.
%
%   @tbd we might be able  to  use   the  current  locale to include the
%   appropriate code page. (Does that really make sense?)


%   '$portray_text_enabled'(-Val)
%
%   Ask the current status of  text   portraying.  Used by the graphical
%   debugger.
%
%   @deprecated.  Use set_portray_text(enabled, Val, Val).

'$portray_text_enabled'(Val) :-
    portray_text_option(enabled, Val).