1/*  Part of SWI-Prolog
    2
    3    Author:        Jan Wielemaker
    4    E-mail:        J.Wielemaker@vu.nl
    5    WWW:           http://www.swi-prolog.org
    6    Copyright (c)  2009-2015, University of Amsterdam
    7                              VU University Amsterdam
    8    All rights reserved.
    9
   10    Redistribution and use in source and binary forms, with or without
   11    modification, are permitted provided that the following conditions
   12    are met:
   13
   14    1. Redistributions of source code must retain the above copyright
   15       notice, this list of conditions and the following disclaimer.
   16
   17    2. Redistributions in binary form must reproduce the above copyright
   18       notice, this list of conditions and the following disclaimer in
   19       the documentation and/or other materials provided with the
   20       distribution.
   21
   22    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   23    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   24    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
   25    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
   26    COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
   27    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
   28    BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
   29    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
   30    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
   31    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
   32    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
   33    POSSIBILITY OF SUCH DAMAGE.
   34*/
   35
   36:- module(charsio,
   37          [ format_to_chars/3,          % +Format, +Args, -Codes
   38            format_to_chars/4,          % +Format, +Args, -Codes, ?Tail
   39            write_to_chars/2,           % +Term, -Codes
   40            write_to_chars/3,           % +Term, -Codes, ?Tail
   41            atom_to_chars/2,            % +Atom, -Codes
   42            atom_to_chars/3,            % +Atom, -Codes, ?Tail
   43            number_to_chars/2,          % +Number, -Codes
   44            number_to_chars/3,          % +Number, -Codes, ?Tail
   45                                        % read predicates
   46            read_from_chars/2,          % +Codes, -Term
   47            read_term_from_chars/3,     % +Codes, -Term, +Options
   48            open_chars_stream/2,        % +Codes, -Stream
   49            with_output_to_chars/2,     % :Goal, -Codes
   50            with_output_to_chars/3,     % :Goal, -Codes, ?Tail
   51            with_output_to_chars/4      % :Goal, -Stream, -Codes, ?Tail
   52          ]).   53:- autoload(library(error),[must_be/2]).   54
   55
   56:- meta_predicate
   57    with_output_to_chars(0, -),
   58    with_output_to_chars(0, -, ?),
   59    with_output_to_chars(0, -, -, ?).   60
   61:- predicate_options(read_term_from_chars/3, 3,
   62                     [pass_to(system:read_term/3, 3)]).

 format_to_chars(+Format, +Args, -Codes) is det

Use format/2 to write to a list of character codes.

   80format_to_chars(Format, Args, Codes) :-
   81    format(codes(Codes), Format, Args).

 format_to_chars(+Format, +Args, -Codes, ?Tail) is det

Use format/2 to write to a difference list of character codes.

   87format_to_chars(Format, Args, Codes, Tail) :-
   88    format(codes(Codes, Tail), Format, Args).

 write_to_chars(+Term, -Codes)

Write a term to a code list. True when Codes is a list of character codes written by write/1 on Term.

   95write_to_chars(Term, Codes) :-
   96    format(codes(Codes), '~w', [Term]).

 write_to_chars(+Term, -Codes, ?Tail)

Write a term to a code list. Codes\Tail is a difference list of character codes produced by write/1 on Term.

  103write_to_chars(Term, Codes, Tail) :-
  104    format(codes(Codes, Tail), '~w', [Term]).

 atom_to_chars(+Atom, -Codes) is det

Convert Atom into a list of character codes.

deprecated

- Use ISO atom_codes/2.

  112atom_to_chars(Atom, Codes) :-
  113    atom_codes(Atom, Codes).

 atom_to_chars(+Atom, -Codes, ?Tail) is det

Convert Atom into a difference list of character codes.

  119atom_to_chars(Atom, Codes, Tail) :-
  120    format(codes(Codes, Tail), '~a', [Atom]).

 number_to_chars(+Number, -Codes) is det

Convert Atom into a list of character codes.

deprecated

- Use ISO number_codes/2.

  128number_to_chars(Number, Codes) :-
  129    number_codes(Number, Codes).

 number_to_chars(+Number, -Codes, ?Tail) is det

Convert Number into a difference list of character codes.

  135number_to_chars(Number, Codes, Tail) :-
  136    must_be(number, Number),
  137    format(codes(Codes, Tail), '~w', [Number]).

 read_from_chars(+Codes, -Term) is det

Read Codes into Term.

Compatibility

- The SWI-Prolog version does not require Codes to end in a full-stop.

  146read_from_chars([], end_of_file) :- !.
  147read_from_chars(List, Term) :-
  148    atom_to_term(List, Term, _).

 read_term_from_chars(+Codes, -Term, +Options) is det

Read Codes into Term. Options are processed by read_term/3.

Compatibility

- sicstus

  156read_term_from_chars(Codes, Term, Options) :-
  157    read_term_from_atom(Codes, Term, Options).

 open_chars_stream(+Codes, -Stream) is det

Open Codes as an input stream.

See also

- open_string/2.

  165open_chars_stream(Codes, Stream) :-
  166    open_string(Codes, Stream).

 with_output_to_chars(:Goal, -Codes) is det

Run Goal as with once/1. Output written to current_output is collected in Codes.

  173with_output_to_chars(Goal, Codes) :-
  174    with_output_to(codes(Codes), Goal).

 with_output_to_chars(:Goal, -Codes, ?Tail) is det

Run Goal as with once/1. Output written to current_output is collected in Codes\Tail.

  181with_output_to_chars(Goal, Codes, Tail) :-
  182    with_output_to(codes(Codes, Tail), Goal).

 with_output_to_chars(:Goal, -Stream, -Codes, ?Tail) is det

Same as with_output_to_chars/3 using an explicit stream. The difference list Codes\Tail contains the character codes that Goal has written to Stream.

  190with_output_to_chars(Goal, Stream, Codes, Tail) :-
  191    with_output_to(codes(Codes, Tail), with_stream(Stream, Goal)).
  192
  193with_stream(Stream, Goal) :-
  194    current_output(Stream),
  195    call(Goal)