GNU Info
(slib.info)Format Specification
Format Specification (Format version 3.0)
-----------------------------------------
Please consult a Common LISP format reference manual for a detailed
description of the format string syntax. For a demonstration of the
implemented directives see `formatst.scm'.
This implementation supports directive parameters and modifiers (`:'
and `@' characters). Multiple parameters must be separated by a comma
(`,'). Parameters can be numerical parameters (positive or negative),
character parameters (prefixed by a quote character (`''), variable
parameters (`v'), number of rest arguments parameter (`#'), empty and
default parameters. Directive characters are case independent. The
general form of a directive is:
DIRECTIVE ::= ~{DIRECTIVE-PARAMETER,}[:][@]DIRECTIVE-CHARACTER
DIRECTIVE-PARAMETER ::= [ [-|+]{0-9}+ | 'CHARACTER | v | # ]
Implemented CL Format Control Directives
........................................
Documentation syntax: Uppercase characters represent the corresponding
control directive characters. Lowercase characters represent control
directive parameter descriptions.
`~A'
Any (print as `display' does).
`~@A'
left pad.
`~MINCOL,COLINC,MINPAD,PADCHARA'
full padding.
`~S'
S-expression (print as `write' does).
`~@S'
left pad.
`~MINCOL,COLINC,MINPAD,PADCHARS'
full padding.
`~D'
Decimal.
`~@D'
print number sign always.
`~:D'
print comma separated.
`~MINCOL,PADCHAR,COMMACHARD'
padding.
`~X'
Hexadecimal.
`~@X'
print number sign always.
`~:X'
print comma separated.
`~MINCOL,PADCHAR,COMMACHARX'
padding.
`~O'
Octal.
`~@O'
print number sign always.
`~:O'
print comma separated.
`~MINCOL,PADCHAR,COMMACHARO'
padding.
`~B'
Binary.
`~@B'
print number sign always.
`~:B'
print comma separated.
`~MINCOL,PADCHAR,COMMACHARB'
padding.
`~NR'
Radix N.
`~N,MINCOL,PADCHAR,COMMACHARR'
padding.
`~@R'
print a number as a Roman numeral.
`~:@R'
print a number as an "old fashioned" Roman numeral.
`~:R'
print a number as an ordinal English number.
`~R'
print a number as a cardinal English number.
`~P'
Plural.
`~@P'
prints `y' and `ies'.
`~:P'
as `~P but jumps 1 argument backward.'
`~:@P'
as `~@P but jumps 1 argument backward.'
`~C'
Character.
`~@C'
prints a character as the reader can understand it (i.e. `#\'
prefixing).
`~:C'
prints a character as emacs does (eg. `^C' for ASCII 03).
`~F'
Fixed-format floating-point (prints a flonum like MMM.NNN).
`~WIDTH,DIGITS,SCALE,OVERFLOWCHAR,PADCHARF'
`~@F'
If the number is positive a plus sign is printed.
`~E'
Exponential floating-point (prints a flonum like MMM.NNN`E'EE).
`~WIDTH,DIGITS,EXPONENTDIGITS,SCALE,OVERFLOWCHAR,PADCHAR,EXPONENTCHARE'
`~@E'
If the number is positive a plus sign is printed.
`~G'
General floating-point (prints a flonum either fixed or
exponential).
`~WIDTH,DIGITS,EXPONENTDIGITS,SCALE,OVERFLOWCHAR,PADCHAR,EXPONENTCHARG'
`~@G'
If the number is positive a plus sign is printed.
`~$'
Dollars floating-point (prints a flonum in fixed with signs
separated).
`~DIGITS,SCALE,WIDTH,PADCHAR$'
`~@$'
If the number is positive a plus sign is printed.
`~:@$'
A sign is always printed and appears before the padding.
`~:$'
The sign appears before the padding.
`~%'
Newline.
`~N%'
print N newlines.
`~&'
print newline if not at the beginning of the output line.
`~N&'
prints `~&' and then N-1 newlines.
`~|'
Page Separator.
`~N|'
print N page separators.
`~~'
Tilde.
`~N~'
print N tildes.
`~'<newline>
Continuation Line.
`~:'<newline>
newline is ignored, white space left.
`~@'<newline>
newline is left, white space ignored.
`~T'
Tabulation.
`~@T'
relative tabulation.
`~COLNUM,COLINCT'
full tabulation.
`~?'
Indirection (expects indirect arguments as a list).
`~@?'
extracts indirect arguments from format arguments.
`~(STR~)'
Case conversion (converts by `string-downcase').
`~:(STR~)'
converts by `string-capitalize'.
`~@(STR~)'
converts by `string-capitalize-first'.
`~:@(STR~)'
converts by `string-upcase'.
`~*'
Argument Jumping (jumps 1 argument forward).
`~N*'
jumps N arguments forward.
`~:*'
jumps 1 argument backward.
`~N:*'
jumps N arguments backward.
`~@*'
jumps to the 0th argument.
`~N@*'
jumps to the Nth argument (beginning from 0)
`~[STR0~;STR1~;...~;STRN~]'
Conditional Expression (numerical clause conditional).
`~N['
take argument from N.
`~@['
true test conditional.
`~:['
if-else-then conditional.
`~;'
clause separator.
`~:;'
default clause follows.
`~{STR~}'
Iteration (args come from the next argument (a list)).
`~N{'
at most N iterations.
`~:{'
args from next arg (a list of lists).
`~@{'
args from the rest of arguments.
`~:@{'
args from the rest args (lists).
`~^'
Up and out.
`~N^'
aborts if N = 0
`~N,M^'
aborts if N = M
`~N,M,K^'
aborts if N <= M <= K
Not Implemented CL Format Control Directives
............................................
`~:A'
print `#f' as an empty list (see below).
`~:S'
print `#f' as an empty list (see below).
`~<~>'
Justification.
`~:^'
(sorry I don't understand its semantics completely)
Extended, Replaced and Additional Control Directives
....................................................
`~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHD'
`~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHX'
`~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHO'
`~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHB'
`~N,MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHR'
COMMAWIDTH is the number of characters between two comma
characters.
`~I'
print a R4RS complex number as `~F~@Fi' with passed parameters for
`~F'.
`~Y'
Pretty print formatting of an argument for scheme code lists.
`~K'
Same as `~?.'
`~!'
Flushes the output if format DESTINATION is a port.
`~_'
Print a `#\space' character
`~N_'
print N `#\space' characters.
`~/'
Print a `#\tab' character
`~N/'
print N `#\tab' characters.
`~NC'
Takes N as an integer representation for a character. No arguments
are consumed. N is converted to a character by `integer->char'. N
must be a positive decimal number.
`~:S'
Print out readproof. Prints out internal objects represented as
`#<...>' as strings `"#<...>"' so that the format output can always
be processed by `read'.
`~:A'
Print out readproof. Prints out internal objects represented as
`#<...>' as strings `"#<...>"' so that the format output can always
be processed by `read'.
`~Q'
Prints information and a copyright notice on the format
implementation.
`~:Q'
prints format version.
`~F, ~E, ~G, ~$'
may also print number strings, i.e. passing a number as a string
and format it accordingly.
Configuration Variables
.......................
Format has some configuration variables at the beginning of
`format.scm' to suit the systems and users needs. There should be no
modification necessary for the configuration that comes with SLIB. If
modification is desired the variable should be set after the format
code is loaded. Format detects automatically if the running scheme
system implements floating point numbers and complex numbers.
FORMAT:SYMBOL-CASE-CONV
Symbols are converted by `symbol->string' so the case type of the
printed symbols is implementation dependent.
`format:symbol-case-conv' is a one arg closure which is either
`#f' (no conversion), `string-upcase', `string-downcase' or
`string-capitalize'. (default `#f')
FORMAT:IOBJ-CASE-CONV
As FORMAT:SYMBOL-CASE-CONV but applies for the representation of
implementation internal objects. (default `#f')
FORMAT:EXPCH
The character prefixing the exponent value in `~E' printing.
(default `#\E')
Compatibility With Other Format Implementations
...............................................
SLIB format 2.x:
See `format.doc'.
SLIB format 1.4:
Downward compatible except for padding support and `~A', `~S',
`~P', `~X' uppercase printing. SLIB format 1.4 uses C-style
`printf' padding support which is completely replaced by the CL
`format' padding style.
MIT C-Scheme 7.1:
Downward compatible except for `~', which is not documented
(ignores all characters inside the format string up to a newline
character). (7.1 implements `~a', `~s', ~NEWLINE, `~~', `~%',
numerical and variable parameters and `:/@' modifiers in the CL
sense).
Elk 1.5/2.0:
Downward compatible except for `~A' and `~S' which print in
uppercase. (Elk implements `~a', `~s', `~~', and `~%' (no
directive parameters or modifiers)).
Scheme->C 01nov91:
Downward compatible except for an optional destination parameter:
S2C accepts a format call without a destination which returns a
formatted string. This is equivalent to a #f destination in S2C.
(S2C implements `~a', `~s', `~c', `~%', and `~~' (no directive
parameters or modifiers)).
This implementation of format is solely useful in the SLIB context
because it requires other components provided by SLIB.
automatically generated by info2www version 1.2.2.9