Go to the first, previous, next, last section, table of contents.

Formatted output

Author(s): The CLIP Group.

Version: 1.11#222 (2004/5/24, 13:8:7 CEST)

Version of last change: 1.11#89 (2003/12/21, 2:17:58 CET)

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 (`format`)

Library usage: :- use_module(library(format)).
Exports:
- Predicates: format/2, format/3.
- Regular Types: format_control/1.
Other modules used:
- System library modules: write, assertions/doc_props.

Documentation on exports (`format`)

PREDICATE: format/2:

General properties: format(C, A)

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

Usage: format(format_control(Format), Arguments)

Description: Print Arguments onto current output stream according to format Format.

PREDICATE: format/3:

General properties: format(S, C, A)

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

Usage: format(Stream, format_control(Format), Arguments)

Description: Print Arguments onto Stream according to format Format.
The following properties should hold at call time: Stream is currently a term which is not a free variable. (term_typing:nonvar/1)

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 (section 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 (section 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 (section 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 (section 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)

Description: 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: Documentation is still incomplete: format_control(C) may not conform the functionality documented. (doc_props:doc_incomplete/1)

Go to the first, previous, next, last section, table of contents.

Formatted output

Usage and interface (format)

Documentation on exports (format)

Usage and interface (`format`)

Documentation on exports (`format`)