Formatted output

Author(s): The Ciao Development Team.

The format family of predicates is due to Quintus Prolog. They act as a Prolog interface to the C stdio function printf(), allowing formatted output.

Output is formatted according to an output pattern which can have either a format control sequence or any other character, which will appear verbatim in the output. Control sequences act as place-holders for the actual terms that will be output. Thus

    ?- format("Hello ~q!",world).

will print Hello world!.

If there is only one item to print it may be supplied alone. If there are more they have to be given as a list. If there are none then an empty list should be supplied. There has to be as many items as control characters.

The character ~ introduces a control sequence. To print a ~ verbatim just repeat it:

    ?- format("Hello ~~world!", []).

will result in Hello ~world!.

A format may be spread over several lines. The control sequence \c followed by a LFD will translate to the empty string:

?- format("Hello \c
world!", []).

will result in Hello world!.

Usage and interface

Library usage:
:- use_module(library(format)).
Exports:
- Predicates:
  format/2, format/3, sformat/3, format_to_string/3.
- Regular Types:
  format_control/1.

Documentation on exports

PREDICATEformat/2

Usage:format(Format,Arguments)

Print Arguments onto current output stream according to format Format.

The following properties should hold at call time:
(format:format_control/1)Format is an atom or string describing how the arguments should be formatted. If it is an atom it will be converted into a string with name/2.

Other properties:
format(C,A)

The following properties hold globally:
(basic_props:native/2)This predicate is understood natively by CiaoPP as format(C,A).

PREDICATEformat/3

Usage:format(Stream,Format,Arguments)

Print Arguments onto Stream according to format Format.

The following properties should hold at call time:
(stream_basic:stream/1)Stream is an open stream.
(format:format_control/1)Format is an atom or string describing how the arguments should be formatted. If it is an atom it will be converted into a string with name/2.

Other properties:
format(S,C,A)

The following properties hold globally:
(basic_props:native/2)This predicate is understood natively by CiaoPP as format(S,C,A).

PREDICATEsformat/3

Usage:sformat(String,Format,Arguments)

Same as Format, Arguments, String)">format_to_string(Format, Arguments, String) (note the different argument order).

The following properties should hold at call time:
(format:format_control/1)Format is an atom or string describing how the arguments should be formatted. If it is an atom it will be converted into a string with name/2.
The following properties should hold upon exit:
(basic_props:string/1)String is a string (a list of character codes).

PREDICATEformat_to_string/3

Usage:format_to_string(Format,Arguments,String)

Print Arguments onto current string String according to format Format. This predicate is similar to the format/2, but the result is stored in a string.

The following properties should hold at call time:
(format:format_control/1)Format is an atom or string describing how the arguments should be formatted. If it is an atom it will be converted into a string with name/2.
(basic_props:list/1)Arguments is a list.
The following properties should hold upon exit:
(basic_props:string/1)String is a string (a list of character codes).

REGTYPEformat_control/1

The general format of a control sequence is ~NC. The character C determines the type of the control sequence. N is an optional numeric argument. An alternative form of N is *. * implies that the next argument in Arguments should be used as a numeric argument in the control sequence. Example:

?- format("Hello~4cworld!", [0'x]).

and

?- format("Hello~*cworld!", [4,0'x]).

both produce

Helloxxxxworld!

The following control sequences are available.

~a The argument is an atom. The atom is printed without quoting.
~Nc (Print character.) The argument is a number that will be interpreted as an ASCII code. N defaults to one and is interpreted as the number of times to print the character.
~Ne
~NE
~Nf
~Ng

~NG (Print float). The argument is a float. The float and N will be passed to the C printf() function as

printf("%.Ne", Arg)
printf("%.NE", Arg)
printf("%.Nf", Arg)
printf("%.Ng", Arg)
printf("%.NG", Arg)

If N is not supplied the action defaults to

printf("%e", Arg)
printf("%E", Arg)
printf("%f", Arg)
printf("%g", Arg)
printf("%G", Arg)

~Nd (Print decimal.) The argument is an integer. N is interpreted as the number of digits after the decimal point. If N is 0 or missing, no decimal point will be printed. Example:
```
?- format("Hello ~1d world!", [42]).
?- format("Hello ~d world!", [42]).
```
will print as
```
Hello 4.2 world!
Hello 42 world!
```
respectively.
~ND (Print decimal.) The argument is an integer. Identical to ~Nd except that , will separate groups of three digits to the left of the decimal point. Example:
```
?- format("Hello ~1D world!", [12345]).
```
will print as
```
Hello 1,234.5 world!
```
~Nr (Print radix.) The argument is an integer. N is interpreted as a radix. N should be >= 2 and <= 36. If N is missing the radix defaults to 8. The letters a-z will denote digits larger than 9. Example:
```
?- format("Hello ~2r world!", [15]).
?- format("Hello ~16r world!", [15]).
```
will print as
```
Hello 1111 world!
Hello f world!
```
respectively.
~NR (Print radix.) The argument is an integer. Identical to ~Nr except that the letters A-Z will denote digits larger than 9. Example:
```
?- format("Hello ~16R world!", [15]).
```
will print as
```
Hello F world!
```
~Ns (Print string.) The argument is a list of ASCII codes. Exactly N characters will be printed. N defaults to the length of the string. Example:
```
?- format("Hello ~4s ~4s!", ["new","world"]).
?- format("Hello ~s world!", ["new"]).
```
will print as
```
Hello new  worl!
Hello new world!
```
respectively.
~i (Ignore argument.) The argument may be of any type. The argument will be ignored. Example:
```
?- format("Hello ~i~s world!", ["old","new"]).
```
will print as
```
Hello new world!
```
~k (Print canonical.) The argument may be of any type. The argument will be passed to write_canonical/2 (Term output). Example:
```
?- format("Hello ~k world!", [[a,b,c]]).
```
will print as
```
Hello .(a,.(b,.(c,[]))) world!
```
~p (print.) The argument may be of any type. The argument will be passed to print/2 (Term output). Example:
suposing the user has defined the predicate
```
:- multifile portray/1.
portray([X|Y]) :- print(cons(X,Y)).
```
then
```
?- format("Hello ~p world!", [[a,b,c]]).
```
will print as
```
Hello cons(a,cons(b,cons(c,[]))) world!
```
~q (Print quoted.) The argument may be of any type. The argument will be passed to writeq/2 (Term output). Example:
```
?- format("Hello ~q world!", [['A','B']]).
```
will print as
```
Hello ['A','B'] world!
```
~w (write.) The argument may be of any type. The argument will be passed to write/2 (Term output). Example:
```
?- format("Hello ~w world!", [['A','B']]).
```
will print as
```
Hello [A,B] world!
```
~Nn (Print newline.) Print N newlines. N defaults to 1. Example:
```
?- format("Hello ~n world!", []).
```
will print as
```
Hello
 world!
```
~N (Fresh line.) Print a newline, if not already at the beginning of a line.
~~ (Print tilde.) Prints ~

The following control sequences are also available for compatibility, but do not perform any useful functions.

~N| (Set tab.) Set a tab stop at position N, where N defaults to the current position, and advance the current position there.
~N+ (Advance tab.) Set a tab stop at N positions past the current position, where N defaults to 8, and advance the current position there.
~Nt (Set fill character.) Set the fill character to be used in the next position movement to N, where N defaults to SPC.

Usage:format_control(C)

C is an atom or string describing how the arguments should be formatted. If it is an atom it will be converted into a string with name/2.

The following properties should hold globally:
(doc_props:doc_incomplete/1)Documentation is still incomplete: format_control(C) may not conform the functionality documented.

Documentation on imports

This module has the following direct dependencies:

System library modules:
datafacts_rt, streams, write, system, doc_props.
Packages:
prelude, initial, condcomp, dcg, assertions, assertions/assertions_basic, isomodes, datafacts.