<HTML>
<HEAD>
<!-- Created by texi2html 1.56k + clip patches and <A href="http://www.clip.dia.fi.upm.es/Software">lpdoc</A> from ciao.texi on 28 January 2007 -->
<LINK rel="stylesheet" href="ciao.css" type="text/css">
<TITLE>The Ciao Prolog System - Term output</TITLE>
</HEAD>
<BODY>
Go to the <A HREF="ciao_1.html">first</A>, <A HREF="ciao_38.html">previous</A>, <A HREF="ciao_40.html">next</A>, <A HREF="ciao_241.html">last</A> section, <A HREF="ciao_toc.html">table of contents</A>.
<P><HR><P>
<H1><A NAME="SEC206" HREF="ciao_toc.html#TOC206">Term output</A></H1>
<P>
<A NAME="IDX2834"></A>
<P>
<STRONG>Author(s):</STRONG> Adapted from shared code written by Richard A. O'Keefe. Changes by Mats Carlsson, Daniel Cabeza, Manuel Hermenegildo, and Manuel Carro..
<P>
<STRONG>Version:</STRONG> 1.10#7 (2006/4/26, 19:22:13 CEST)
<P>
<STRONG>Version of last change:</STRONG> 1.9#290 (2004/2/13, 20:20:3 CET)
<P>
This library provides different predicates for term output, additional to the kernel predicates
<A NAME="IDX2835"></A>
<CODE>display/1</CODE>-
<A NAME="IDX2836"></A>
<CODE>display/2</CODE> and <CODE>displayq/1</CODE>-<CODE>displayq/2</CODE>. All the predicates defined in ISO-Prolog are included, plus other traditionally provided by Prolog Implementations. Output predicates are provided in two versions: one that uses the current output stream and other in which the stream is specified explicitly, as an additional first argument.
<UL>
<LI><A HREF="ciao_39.html#SEC207">Usage and interface (write)</A>
<LI><A HREF="ciao_39.html#SEC208">Documentation on exports (write)</A>
<LI><A HREF="ciao_39.html#SEC209">Documentation on multifiles (write)</A>
</UL>
<H2><A NAME="SEC207" HREF="ciao_toc.html#TOC207">Usage and interface (<CODE>write</CODE>)</A></H2>
<div class="cartouche">
<UL>
<LI><STRONG>Library usage:</STRONG>
<CODE>:- use_module(library(write)).</CODE>
<LI><STRONG>Exports:</STRONG>
<UL>
<LI><EM>Predicates:</EM>
<A NAME="IDX2837"></A>
<CODE>write_term/3</CODE>,
<A NAME="IDX2838"></A>
<CODE>write_term/2</CODE>,
<A NAME="IDX2839"></A>
<CODE>write/2</CODE>,
<A NAME="IDX2840"></A>
<CODE>write/1</CODE>,
<A NAME="IDX2841"></A>
<CODE>writeq/2</CODE>,
<A NAME="IDX2842"></A>
<CODE>writeq/1</CODE>,
<A NAME="IDX2843"></A>
<CODE>write_canonical/2</CODE>,
<A NAME="IDX2844"></A>
<CODE>write_canonical/1</CODE>,
<A NAME="IDX2845"></A>
<CODE>print/2</CODE>,
<A NAME="IDX2846"></A>
<CODE>print/1</CODE>,
<A NAME="IDX2847"></A>
<CODE>write_list1/1</CODE>,
<A NAME="IDX2848"></A>
<CODE>portray_clause/2</CODE>,
<A NAME="IDX2849"></A>
<CODE>portray_clause/1</CODE>,
<A NAME="IDX2850"></A>
<CODE>numbervars/3</CODE>,
<A NAME="IDX2851"></A>
<CODE>prettyvars/1</CODE>,
<A NAME="IDX2852"></A>
<CODE>printable_char/1</CODE>.
<LI><EM>Properties:</EM>
<A NAME="IDX2853"></A>
<CODE>write_option/1</CODE>.
<LI><EM>Multifiles:</EM>
<A NAME="IDX2854"></A>
<CODE>define_flag/3</CODE>,
<A NAME="IDX2855"></A>
<CODE>portray_attribute/2</CODE>,
<A NAME="IDX2856"></A>
<CODE>portray/1</CODE>.
</UL>
<LI><STRONG>Other modules used:</STRONG>
<UL>
<LI><EM>System library modules:</EM>
<A NAME="IDX2857"></A>
<CODE>operators</CODE>,
<A NAME="IDX2858"></A>
<CODE>sort</CODE>.
</UL>
</UL>
</div class="cartouche">
<H2><A NAME="SEC208" HREF="ciao_toc.html#TOC208">Documentation on exports (<CODE>write</CODE>)</A></H2>
<P>
<A NAME="IDX2859"></A>
<A NAME="IDX2860"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>write_term/3:</B>
<DD><A NAME="IDX2861"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>write_term(@Stream, ?Term, +OptList)</CODE>
<KBD> * ISO * </KBD>
<UL>
<LI><EM>Description:</EM> Outputs the term <CODE>Term</CODE> to the stream <CODE>Stream</CODE>, with the list of write-options <CODE>OptList</CODE>. See
<A NAME="IDX2862"></A>
<CODE>write_option/1</CODE> type for default options.
<LI><EM>The following properties hold upon exit:</EM>
<CODE>@Stream</CODE> is an open stream.
(<CODE>streams_basic:stream/1</CODE>)
<CODE>?Term</CODE> is any term.
(<CODE>basic_props:term/1</CODE>)
<CODE>+OptList</CODE> is a list of <CODE>write_option</CODE>s.
(<CODE>basic_props:list/2</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX2863"></A>
<A NAME="IDX2864"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>write_term/2:</B>
<DD><A NAME="IDX2865"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>write_term(?Term, +OptList)</CODE>
<KBD> * ISO * </KBD>
<UL>
<LI><EM>Description:</EM> Behaves like <CODE>current_output(S), write_term(S,Term,OptList)</CODE>.
<LI><EM>The following properties hold upon exit:</EM>
<CODE>?Term</CODE> is any term.
(<CODE>basic_props:term/1</CODE>)
<CODE>+OptList</CODE> is a list of <CODE>write_option</CODE>s.
(<CODE>basic_props:list/2</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX2866"></A>
<A NAME="IDX2867"></A>
<DL>
<DT><span class="define">PROPERTY:</span> <B>write_option/1:</B>
<DD><A NAME="IDX2868"></A>
<P>
<CODE>Opt</CODE> is a valid write option which affects the predicate <CODE>write_term/3</CODE> and similar ones. Possible write_options are:
<UL>
<LI><STRONG>quoted(</STRONG><EM>bool</EM><STRONG>):</STRONG> If <EM>bool</EM> is <CODE>true</CODE>, atoms and functors that can't be read back by
<A NAME="IDX2869"></A>
<CODE>read_term/3</CODE> are quoted, if it is <CODE>false</CODE>, each atom and functor is written as its name. Default value is <CODE>false</CODE>.
<LI><STRONG>ignore_ops(</STRONG><EM>flag</EM><STRONG>):</STRONG> If <EM>flag</EM> is <CODE>true</CODE>, each compound term is output in functional notation, if it is <CODE>ops</CODE>, curly bracketed notation and list notation is enabled when outputing compound terms, if it is <CODE>false</CODE>, also operator notation is enabled when outputing compound terms. Default value is <CODE>false</CODE>.
<LI><STRONG>numbervars(</STRONG><EM>bool</EM><STRONG>):</STRONG> If <EM>bool</EM> is <CODE>true</CODE>, a term of the form <CODE>'$VAR'(N)</CODE> where <CODE>N</CODE> is an integer, is output as a variable name consisting of a capital letter possibly followed by an integer, a term of the form <CODE>'$VAR'(Atom)</CODE> where <CODE>Atom</CODE> is an atom, as this atom (without quotes), and a term of the form <CODE>'$VAR'(String)</CODE> where <CODE>String</CODE> is a character string, as the atom corresponding to this character string. See predicates <CODE>numbervars/3</CODE> and <CODE>prettyvars/1</CODE>. If <EM>bool</EM> is <CODE>false</CODE> this cases are not treated in any special way. Default value is <CODE>false</CODE>.
<LI><STRONG>portrayed(</STRONG><EM>bool</EM><STRONG>):</STRONG> If <EM>bool</EM> is <CODE>true</CODE>, then call multifile predicates
<A NAME="IDX2870"></A>
<CODE>portray/1</CODE> and
<A NAME="IDX2871"></A>
<CODE>portray_attribute/2</CODE>, to provide the user handlers for pretty printing some terms. <CODE>portray_attribute/2</CODE> is called whenever an attributed variable is to be printed, <CODE>portray/1</CODE> is called whenever a non-variable term is to be printed. If either call succeeds, then it is assumed that the term has been output, else it is printed as usual. If <EM>bool</EM> is <CODE>false</CODE>, these predicates are not called. Default value is <CODE>false</CODE>. This option is set by the toplevel when writting the final values of variables, and by the debugging package when writting the goals in the tracing messages. Thus you can vary the forms of these messages if you wish.
<LI><STRONG>max_depth(</STRONG><EM>depth</EM><STRONG>):</STRONG> <EM>depth</EM> is a positive integer or cero. If it is positive, it denotes the depth limit on printing compound terms. If it is cero, there is no limit. Default value is <CODE>0</CODE> (no limit).
<LI><STRONG>priority(</STRONG><EM>prio</EM><STRONG>):</STRONG> <EM>prio</EM> is an integer between 1 and 1200. If the term to be printed has higher priority than <EM>prio</EM>, it will be printed parenthesized. Default value is 1200 (no term parenthesized).
</UL>
<P>
.
<P>
<STRONG>Usage:</STRONG> <CODE>write_option(Opt)</CODE>
<UL>
<LI><EM>Description:</EM> <CODE>Opt</CODE> is a valid write option.
</UL>
</DL>
<P>
<A NAME="IDX2872"></A>
<A NAME="IDX2873"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>write/2:</B>
<DD><A NAME="IDX2874"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>write(@Stream, ?Term)</CODE>
<KBD> * ISO * </KBD>
<UL>
<LI><EM>Description:</EM> Behaves like <CODE>write_term(Stream, Term, [numbervars(true)])</CODE>.
<LI><EM>The following properties hold upon exit:</EM>
<CODE>@Stream</CODE> is an open stream.
(<CODE>streams_basic:stream/1</CODE>)
<CODE>?Term</CODE> is any term.
(<CODE>basic_props:term/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX2875"></A>
<A NAME="IDX2876"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>write/1:</B>
<DD><A NAME="IDX2877"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>write(?Term)</CODE>
<KBD> * ISO * </KBD>
<UL>
<LI><EM>Description:</EM> Behaves like <CODE>current_output(S), write(S,Term)</CODE>.
<LI><EM>The following properties hold upon exit:</EM>
<CODE>?Term</CODE> is any term.
(<CODE>basic_props:term/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX2878"></A>
<A NAME="IDX2879"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>writeq/2:</B>
<DD><A NAME="IDX2880"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>writeq(@Stream, ?Term)</CODE>
<KBD> * ISO * </KBD>
<UL>
<LI><EM>Description:</EM> Behaves like <CODE>write_term(Stream, Term, [quoted(true), numbervars(true)])</CODE>.
<LI><EM>The following properties hold upon exit:</EM>
<CODE>@Stream</CODE> is an open stream.
(<CODE>streams_basic:stream/1</CODE>)
<CODE>?Term</CODE> is any term.
(<CODE>basic_props:term/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX2881"></A>
<A NAME="IDX2882"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>writeq/1:</B>
<DD><A NAME="IDX2883"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>writeq(?Term)</CODE>
<KBD> * ISO * </KBD>
<UL>
<LI><EM>Description:</EM> Behaves like <CODE>current_output(S), writeq(S,Term)</CODE>.
<LI><EM>The following properties hold upon exit:</EM>
<CODE>?Term</CODE> is any term.
(<CODE>basic_props:term/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX2884"></A>
<A NAME="IDX2885"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>write_canonical/2:</B>
<DD><A NAME="IDX2886"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>write_canonical(@Stream, ?Term)</CODE>
<KBD> * ISO * </KBD>
<UL>
<LI><EM>Description:</EM> Behaves like <CODE>write_term(Stream, Term, [quoted(true), ignore_ops(true)])</CODE>. The output of this predicate can always be parsed by
<A NAME="IDX2887"></A>
<CODE>read_term/2</CODE> even if the term contains special characters or if operator declarations have changed.
<LI><EM>The following properties hold upon exit:</EM>
<CODE>@Stream</CODE> is an open stream.
(<CODE>streams_basic:stream/1</CODE>)
<CODE>?Term</CODE> is any term.
(<CODE>basic_props:term/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX2888"></A>
<A NAME="IDX2889"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>write_canonical/1:</B>
<DD><A NAME="IDX2890"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>write_canonical(?Term)</CODE>
<KBD> * ISO * </KBD>
<UL>
<LI><EM>Description:</EM> Behaves like <CODE>current_output(S), write_canonical(S,Term)</CODE>.
<LI><EM>The following properties hold upon exit:</EM>
<CODE>?Term</CODE> is any term.
(<CODE>basic_props:term/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX2891"></A>
<A NAME="IDX2892"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>print/2:</B>
<DD><A NAME="IDX2893"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>print(@Stream, ?Term)</CODE>
<UL>
<LI><EM>Description:</EM> Behaves like <CODE>write_term(Stream, Term, [numbervars(true), portrayed(true)])</CODE>.
<LI><EM>The following properties hold upon exit:</EM>
<CODE>@Stream</CODE> is an open stream.
(<CODE>streams_basic:stream/1</CODE>)
<CODE>?Term</CODE> is any term.
(<CODE>basic_props:term/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX2894"></A>
<A NAME="IDX2895"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>print/1:</B>
<DD><A NAME="IDX2896"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>print(?Term)</CODE>
<UL>
<LI><EM>Description:</EM> Behaves like <CODE>current_output(S), print(S,Term)</CODE>.
<LI><EM>The following properties hold upon exit:</EM>
<CODE>?Term</CODE> is any term.
(<CODE>basic_props:term/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX2897"></A>
<A NAME="IDX2898"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>write_list1/1:</B>
<DD><A NAME="IDX2899"></A>
<P>
<STRONG>Usage:</STRONG>
<UL>
<LI><EM>Description:</EM> Writes a list to current output one element in each line.
<LI><EM>Calls should, and exit will be compatible with:</EM>
<CODE>Arg1</CODE> is a list.
(<CODE>basic_props:list/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX2900"></A>
<A NAME="IDX2901"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>portray_clause/2:</B>
<DD><A NAME="IDX2902"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>portray_clause(@Stream, ?Clause)</CODE>
<UL>
<LI><EM>Description:</EM> Outputs the clause <CODE>Clause</CODE> onto <CODE>Stream</CODE>, pretty printing its variables and using indentation, including a period at the end. This predicate is used by <CODE>listing/0</CODE>.
<LI><EM>The following properties hold upon exit:</EM>
<CODE>@Stream</CODE> is an open stream.
(<CODE>streams_basic:stream/1</CODE>)
<CODE>?Clause</CODE> is any term.
(<CODE>basic_props:term/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX2903"></A>
<A NAME="IDX2904"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>portray_clause/1:</B>
<DD><A NAME="IDX2905"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>portray_clause(?Clause)</CODE>
<UL>
<LI><EM>Description:</EM> Behaves like <CODE>current_output(S), portray_clause(S,Term)</CODE>.
<LI><EM>The following properties hold upon exit:</EM>
<CODE>?Clause</CODE> is any term.
(<CODE>basic_props:term/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX2906"></A>
<A NAME="IDX2907"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>numbervars/3:</B>
<DD><A NAME="IDX2908"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>numbervars(?Term, +N, ?M)</CODE>
<UL>
<LI><EM>Description:</EM> Unifies each of the variables in term <CODE>Term</CODE> with a term of the form <CODE>'$VAR'(I)</CODE> where <CODE>I</CODE> is an integer from <CODE>N</CODE> onwards. <CODE>M</CODE> is unified with the last integer used plus 1. If the resulting term is output with a write option <CODE>numbervars(true)</CODE>, in the place of the variables in the original term will be printed a variable name consisting of a capital letter possibly followed by an integer. When <CODE>N</CODE> is 0 you will get the variable names A, B, ..., Z, A1, B1, etc.
<LI><EM>The following properties hold upon exit:</EM>
<CODE>?Term</CODE> is any term.
(<CODE>basic_props:term/1</CODE>)
<CODE>+N</CODE> is an integer.
(<CODE>basic_props:int/1</CODE>)
<CODE>?M</CODE> is an integer.
(<CODE>basic_props:int/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX2909"></A>
<A NAME="IDX2910"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>prettyvars/1:</B>
<DD><A NAME="IDX2911"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>prettyvars(?Term)</CODE>
<UL>
<LI><EM>Description:</EM> Similar to <CODE>numbervars(Term,0,_)</CODE>, except that singleton variables in <CODE>Term</CODE> are unified with <CODE>'$VAR'('_')</CODE>, so that when the resulting term is output with a write option <CODE>numbervars(true)</CODE>, in the place of singleton variables <CODE>_</CODE> is written. This predicate is used by
<A NAME="IDX2912"></A>
<CODE>portray_clause/2</CODE>.
<LI><EM>The following properties hold upon exit:</EM>
<CODE>?Term</CODE> is any term.
(<CODE>basic_props:term/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX2913"></A>
<A NAME="IDX2914"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>printable_char/1:</B>
<DD><A NAME="IDX2915"></A>
<P>
<STRONG>Usage:</STRONG> <CODE>printable_char(+Char)</CODE>
<UL>
<LI><EM>Description:</EM> <CODE>Char</CODE> is the code of a character which can be printed.
<LI><EM>The following properties should hold upon exit:</EM>
<CODE>+Char</CODE> is currently instantiated to a number.
(<CODE>term_typing:number/1</CODE>)
</UL>
</DL>
<H2><A NAME="SEC209" HREF="ciao_toc.html#TOC209">Documentation on multifiles (<CODE>write</CODE>)</A></H2>
<P>
<A NAME="IDX2916"></A>
<A NAME="IDX2917"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>define_flag/3:</B>
<DD><A NAME="IDX2918"></A>
<P>
Defines flags as follows:
<PRE>
define_flag(write_strings,[on,off],off).
</PRE>
<P>
(See section <A HREF="ciao_27.html#SEC163">Changing system behaviour and various flags</A>).
<P>
If flag is <CODE>on</CODE>, lists which may be written as strings are.
<P>
The predicate is <EM>multifile</EM>.
</DL>
<P>
<A NAME="IDX2919"></A>
<A NAME="IDX2920"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>portray_attribute/2:</B>
<DD><A NAME="IDX2921"></A>
<P>
The predicate is <EM>multifile</EM>.
<P>
<STRONG>Usage:</STRONG> <CODE>portray_attribute(Attr, Var)</CODE>
<UL>
<LI><EM>Description:</EM> <EM>A user defined predicate.</EM> When an attributed variable <CODE>Var</CODE> is about to be printed, this predicate receives the variable and its attribute <CODE>Attr</CODE>. The predicate should either print something based on <CODE>Attr</CODE> or <CODE>Var</CODE>, or do nothing and fail. In the latter case, the default printer (
<A NAME="IDX2922"></A>
<CODE>write/1</CODE>) will print the attributed variable like an unbound variable, e.g. <CODE>_673</CODE>.
<LI><EM>The following properties should hold at call time:</EM>
<CODE>Attr</CODE> is currently a term which is not a free variable.
(<CODE>term_typing:nonvar/1</CODE>)
<CODE>Var</CODE> is a free variable.
(<CODE>term_typing:var/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX2923"></A>
<A NAME="IDX2924"></A>
<DL>
<DT><span class="define">PREDICATE:</span> <B>portray/1:</B>
<DD><A NAME="IDX2925"></A>
<P>
The predicate is <EM>multifile</EM>.
<P>
<STRONG>Usage:</STRONG> <CODE>portray(?Term)</CODE>
<UL>
<LI><EM>Description:</EM> <EM>A user defined predicate.</EM> This should either print the <CODE>Term</CODE> and succeed, or do nothing and fail. In the latter case, the default printer (<CODE>write/1</CODE>) will print the <CODE>Term</CODE>.
</UL>
</DL>
<P><HR><P>
Go to the <A HREF="ciao_1.html">first</A>, <A HREF="ciao_38.html">previous</A>, <A HREF="ciao_40.html">next</A>, <A HREF="ciao_241.html">last</A> section, <A HREF="ciao_toc.html">table of contents</A>.
</BODY>
</HTML>
