Formatted output

Author(s): The CLIP Group.

Version: 1.10#7 (2006/4/26, 19:22:13 CEST)

Version of last change: 1.9#212 (2003/12/21, 2:18:19 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)
• Documentation on exports (format)

Usage and interface (format)

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, Arguments)

• Description: Print Arguments onto current output stream according to format Format.
• Calls should, and exit will be compatible with: 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. (format:format_control/1)

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, Arguments)

• Description: Print Arguments onto Stream according to format Format.
• Calls should, and exit will be compatible with: 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. (format:format_control/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.