format
Formatted output, Common LISP style
Documentation
[procedure] (format DESTINATION FORMAT-STRING . ARGUMENTS)An almost complete implementation of Common LISP format description according to the CL reference book Common LISP, the Language from Guy L. Steele, Digital Press. This code was originally part of SLIB. The author is Dirk Lutzebaeck.
Returns #t, #f or a string; has side effect of printing according to FORMAT-STRING. If DESTINATION is #t, the output is to the current output port and #t is returned. If DESTINATION is #f, a formatted string is returned as the result of the call. If DESTINATION is a string, DESTINATION is regarded as the format string; FORMAT-STRING is then the first argument and the output is returned as a string. If DESTINATION is a number, the output is to the value of (current-error-port). Otherwise DESTINATION must be an output port and #t is returned.
FORMAT-STRING must be a string. In case of a formatting error format returns #f and prints a message on the value of (current-error-port). Characters are output as if the string were output by the display function with the exception of those prefixed by a tilde (~). For a detailed description of the FORMAT-STRING syntax please consult a Common LISP format reference manual.
This code is not reentrant, nor is it thread-safe.
format implements SRFI-28
A list of all supported, non-supported and extended directives follows:
Format Specification (Format version 3.1)
-----------------------------------------
Please consult a Common LISP format reference manual for a detailed
description of the format string syntax.
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)). Iteration
bounding is controlled by configuration variables
format:iteration-bounded and format:max-iterations. With both variables
default, a maximum of 100 iterations will be performed.
`~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. There should be no modification
necessary for the default configuration. If modification is desired the
variable should be set after the format code is loaded.
format:floats
System has floating-point numbers. (default #t)
format:complex-numbers
System has complex numbers. (default #f)
format:fn-max
Maximum number of number digits. (default 200)
format:format:en-max
Maximum number of exponent digits. (default 10)
format:expch
The character prefixing the exponent value in ~E printing.
(default #\E)
format:radix-pref
Does number->string add a radix prefix? (default <detects upon load>)
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:iteration-bounded
When #t, a ~{...~} control will iterate no more than the number of
times specified by format:max-iterations regardless of the number
of iterations implied by modifiers and arguments. When #f, a
~{...~} control will iterate the number of times implied by
modifiers and arguments, unless termination is forced by language
or system limitations. (default #t)
format:max-iterations
The maximum number of iterations performed by a ~{...~} control.
Has effect only when format:iteration-bounded is #t. (default 100)
format:unprocessed-arguments-error?
Are superfluous arguments treated as an error. (default #f)
License
This code is in the public domain
Author
Dirk Lutzebaeck, maintained by felix winkelmann and Kon Lovett
Repository
This egg is hosted on the CHICKEN Subversion repository:
https://anonymous@code.call-cc.org/svn/chicken-eggs/release/5/format
If you want to check out the source code repository of this egg and you are not familiar with Subversion, see this page.
Version history
- 3.2.1
- fix missing dependency on srfi-13
- 3.2.0
- ported to CHICKEN 5 by Vasillij Schneidermann
- 3.1.6
- Fix for ticket #630
- 3.1.5
- 3.1.4
- Ported to CHICKEN 4
- 3.1.3
- Removed 'format feature & added srfi-13
- 3.1.2
- Exports
- 3.1
- Eggification