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