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(, ), 58 with_output_to_chars(, , ), 59 with_output_to_chars(, , , ). 60 61:- predicate_options(read_term_from_chars/3, 3, 62 [pass_to(system:read_term/3, 3)]). 63 64/** <module> I/O on Lists of Character Codes 65 66This module emulates the Quintus/SICStus library charsio.pl for reading 67and writing from/to lists of character codes. Most of these predicates 68are straight calls into similar SWI-Prolog primitives. Some can even be 69replaced by ISO standard predicates. 70 71@compat The naming of this library is not in line with the ISO standard. 72We believe that the SWI-Prolog native predicates form a more elegant 73alternative for this library. 74*/ 75 76%! format_to_chars(+Format, +Args, -Codes) is det. 77% 78% Use format/2 to write to a list of character codes. 79 80format_to_chars(Format, Args, Codes) :- 81 format(codes(Codes), Format, Args). 82 83%! format_to_chars(+Format, +Args, -Codes, ?Tail) is det. 84% 85% Use format/2 to write to a difference list of character codes. 86 87format_to_chars(Format, Args, Codes, Tail) :- 88 format(codes(Codes, Tail), Format, Args). 89 90%! write_to_chars(+Term, -Codes) 91% 92% Write a term to a code list. True when Codes is a list of 93% character codes written by write/1 on Term. 94 95write_to_chars(Term, Codes) :- 96 format(codes(Codes), '~w', [Term]). 97 98%! write_to_chars(+Term, -Codes, ?Tail) 99% 100% Write a term to a code list. Codes\Tail is a difference list of 101% character codes produced by write/1 on Term. 102 103write_to_chars(Term, Codes, Tail) :- 104 format(codes(Codes, Tail), '~w', [Term]). 105 106%! atom_to_chars(+Atom, -Codes) is det. 107% 108% Convert Atom into a list of character codes. 109% 110% @deprecated Use ISO atom_codes/2. 111 112atom_to_chars(Atom, Codes) :- 113 atom_codes(Atom, Codes). 114 115%! atom_to_chars(+Atom, -Codes, ?Tail) is det. 116% 117% Convert Atom into a difference list of character codes. 118 119atom_to_chars(Atom, Codes, Tail) :- 120 format(codes(Codes, Tail), '~a', [Atom]). 121 122%! number_to_chars(+Number, -Codes) is det. 123% 124% Convert Atom into a list of character codes. 125% 126% @deprecated Use ISO number_codes/2. 127 128number_to_chars(Number, Codes) :- 129 number_codes(Number, Codes). 130 131%! number_to_chars(+Number, -Codes, ?Tail) is det. 132% 133% Convert Number into a difference list of character codes. 134 135number_to_chars(Number, Codes, Tail) :- 136 must_be(number, Number), 137 format(codes(Codes, Tail), '~w', [Number]). 138 139%! read_from_chars(+Codes, -Term) is det. 140% 141% Read Codes into Term. 142% 143% @compat The SWI-Prolog version does not require Codes to end 144% in a full-stop. 145 146read_from_chars([], end_of_file) :- !. 147read_from_chars(List, Term) :- 148 atom_to_term(List, Term, _). 149 150%! read_term_from_chars(+Codes, -Term, +Options) is det. 151% 152% Read Codes into Term. Options are processed by read_term/3. 153% 154% @compat sicstus 155 156read_term_from_chars(Codes, Term, Options) :- 157 read_term_from_atom(Codes, Term, Options). 158 159%! open_chars_stream(+Codes, -Stream) is det. 160% 161% Open Codes as an input stream. 162% 163% @see open_string/2. 164 165open_chars_stream(Codes, Stream) :- 166 open_string(Codes, Stream). 167 168%! with_output_to_chars(:Goal, -Codes) is det. 169% 170% Run Goal as with once/1. Output written to =current_output= 171% is collected in Codes. 172 173with_output_to_chars(Goal, Codes) :- 174 with_output_to(codes(Codes), Goal). 175 176%! with_output_to_chars(:Goal, -Codes, ?Tail) is det. 177% 178% Run Goal as with once/1. Output written to =current_output= 179% is collected in Codes\Tail. 180 181with_output_to_chars(Goal, Codes, Tail) :- 182 with_output_to(codes(Codes, Tail), Goal). 183 184%! with_output_to_chars(:Goal, -Stream, -Codes, ?Tail) is det. 185% 186% Same as with_output_to_chars/3 using an explicit stream. The 187% difference list Codes\Tail contains the character codes that 188% Goal has written to Stream. 189 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)