Formatted output

Author(s): The CLIP Group.

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.
Imports:
- System library modules:
  write, system, assertions/doc_props.
- Packages:
  prelude, nonpure, dcg, assertions, isomodes.

Documentation on exports

PREDICATE

format/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.

General properties:

True:format(C,A)

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

PREDICATE

format/3:

Usage:format(Stream,Format,Arguments)

Print Arguments onto Stream according to format Format.

The following properties should hold at call time:
(streams_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.

General properties:

True: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).

PREDICATE

sformat/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).

PREDICATE

format_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).

REGTYPE

format_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.

Known bugs and planned improvements

format_to_string/3 is extremelly slow in its current implementation. If possible, it writes the output to an intermediate file, reads the string, and removes the file. This is not very fast. In case there are no permissions, writing is attempted through an internal pipe, which may hang if the string is too long (this is O.S. dependant).
Until strings as streams are implemented in Ciao, please consider (the incomplete) format_to_string.

Formatted output

Usage and interface

Documentation on exports

Known bugs and planned improvements

Module Sections

Global Links

Indices