
                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
