format.txt
Documentation of FORMAT Version 2.3
Please consult a Common LISP format reference manual for a detailed
description of the format string syntax. (I haven't the time to
copy the CL format standard text in here). For a demonstration of
the implemented directives see "format-test.scm".
This implementation supports directive parameters and modifiers
(`:' and `@' characters). Multiple parameters must be separated by
a `,'. 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 | # ]
Documentation syntax
--------------------
Uppercase characters represent the corresponding control directive
characters. Lowercase characters represent control directive parameter
descriptions.
Compatibility to other FORMAT implementations
---------------------------------------------
SLIB format 2.x:
see format.scm.
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:
Downward compatible except for ~A and ~S which print in uppercase.
(1.5 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)).
T 3.1:
Downward compatible. This SLIB format version does not run on T 3.1 now due
to missing R4RS essential procedures. (T 3.1 implements ~a,~b,~d,~o,~p,
~nr,~s,~t,~x,~%,~&,~_ and ~~).
Implemented control directives
------------------------------
~A Ascii (print as `display' does).
~@A left pad.
~mincol,colinc,minpad,padcharA padding (colinc is not supported).
~S S-expression (print as `write' does).
~@S left pad.
~mincol,colinc,minpad,padcharS padding (colinc is not supported).
~D Decimal.
~@D print number sign.
~:D print comma separated.
~mincol,padchar,commacharD padding.
~X Hexadecimal.
~@X print number sign.
~:X print comma separated.
~mincol,padchar,commacharX padding.
~O Octal.
~@O print number sign.
~:O print comma separated.
~mincol,padchar,commacharO padding.
~B Binary.
~@B print number sign.
~:B print comma separated.
~mincol,padchar,commacharB padding.
~nR Radix (prints number to radix n).
~n@R print number sign.
~:B print comma separated.
~n,mincol,padchar,commacharR padding.
~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 print as `write' does.
~% Newline.
~n% prints n newlines.
~| Page Separator.
~n| prints n page separators.
~~ Tilde.
~n~ prints n tildes.
~#\newline Continuation Line (#\newline stands for a newline character).
~:#\newline newline is ignored, white space left.
~@#\newline newline is left, white space ignored.
~T Tabulator.
~nT prints n tabs.
~? 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 (beg. 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 control directives of Common LISP's format
----------------------------------------------------------
~:A (different meaning in SLIB format, see below)
~:S (different meaning in SLIB format, see below)
~R
~&
~@T
~colnum,colincT
~<~>
~:^ (what is the `entire' iteration process?)
~F,~E,~G,~$
Extended, replaced and added control directives
-----------------------------------------------
~mincol,padchar,commachar,commawidthD commawidth is the number of characters
~mincol,padchar,commachar,commawidthX between two comma characters.
~mincol,padchar,commachar,commawidthO
~mincol,padchar,commachar,commawidthB
~n,mincol,padchar,commachar,commawidthR
~-mincol,colinc,minpad,padcharA negative field width specified by
~-mincol,colinc,minpad,padcharS mincol forces a field truncation to
~-mincol,padchar,commachar,commawidthD mincol characters. If the printed
~-mincol,padchar,commachar,commawidthX object exceeds the field width a `>' or
~-mincol,padchar,commachar,commawidthO a `<' character is added according to
~-mincol,padchar,commachar,commawidthB the padding direction.
~n,-mincol,padchar,commachar,commawidthR
~& Same as ~%.
~K Same as ~?.
~_ Prints a #\space character
~n_ prints n #\space 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 #<...> as strings "#<...>" so that the output can always
be processed by (read).
:A Print out readproof.
Prints out #<...> as strings "#<...>" so that the output can always
be processed by (read).
Change Log
----------
Version 2.3: [nmh]
* tested with s9fes and scheme48
* restructured code so that only FORMAT is exported and all other
symbols are local; removed format: prefix from all symbols
* fixed indentation in some places
* made ~A emit prettier pairs [(a b . c) instead of (a . (b . c))]
* removed custom types
* removed ~! (flush output), cannot be done portably
* removed ~Y (pretty-print), because it was NYI anyway
Version 2.2: [dl]
* corrected truncation for fixed fields by negative field parameters
inserted a '<' or a '>' when field length was equal to object string
length
* changed #[...] outputs to #<...> outputs to be conform to SCM's
display and write functions
* changed #[non-printable-object] output to #<unspecified>
* ~:s and ~:a print #<...> messages in strings "#<...>" so that the
output can always be processed by (read)
* changed implementation dependent part: to configure for various scheme
systems define the variable format:scheme-system (see below)
* format:version is a variable returning the format version in a string
* format:custom-types allows to use scheme system dependent predicates
to identify the type of a scheme object and its proper textual
representation
* Tested with scm4a14, Elk 2.0
Version 2.1: [dl]
* Tested with scm3c11, Elk 1.5, MIT C-Scheme 7.1, UMB Scheme 2.5,
and Scheme->C 01nov91 (see "formatst.scm" for error reports)
* ~e,~f,~g,~$ fake floating point formatting by number->string;
no directive parameters are implemented
* replaced ~g by ~y due to ~g CL floating point formatting directive
* ~{~} with modifiers implemented (nested iterations allowed)
* errors in format-string are showed by a "<--" in the format string
* `.' as a directive parameter separator is not supported anymore
* ~[ ~; ~] with modifiers implemented (nested conditionals allowed)
* ~? expects a list now (as CL does)
~@? works now as ~? in 2.0 did.
* ~*, ~n*, ~:*, ~n:*, ~@*, ~n@* implemented
* ~:p implemented
* don't strip the argument error messages anymore
* format returns now #t instead of () if destination is an output port
Version 2.0: [dl]
* Tested with scm3c11, Elk 1.5, MIT C-Scheme 7.1, UMB Scheme 2.5 and
Scheme->C 01nov91. (see "formatst.scm" for error reports)
* completely rewritten Version of SLIB format Version 1.4
* removed C-style padding support