\input texinfo @c -*- texinfo -*-

@c Generated by eggdoc-texinfo $Revision$ (c) 2006 Jim Ursetto

@c %**start of header

@setfilename format-modular.egg.info

@settitle format-modular egg: A generic implementation of Common LISPs @code{format} facility.

@c %**end of header

@finalout 

@dircategory The Algorithmic Language Scheme
@direntry
* format-modular.egg: (format-modular.egg).		A generic implementation of Common LISPs @code{format} facility.
@end direntry


@titlepage 

@title format-modular egg

@subtitle A generic implementation of Common LISPs @code{format} facility.

@subtitle Extension for Chicken Scheme

@subtitle Version 1.2

@author Alejandro Forero Cuervo and Alex Shinn

@end titlepage
@contents 

@syncodeindex vr fn


@ifnottex 

@node Top
@top format-modular egg


A generic implementation of Common LISPs @code{format} facility.


@noindent 
Written by Alejandro Forero Cuervo and Alex Shinn

This manual corresponds to version 1.2 of the format-modular extension library for Chicken Scheme.

@menu 
* About this egg::
* Documentation::
* License::
* Index::

@end menu

@end ifnottex
@node About this egg
@chapter About this egg

@menu 
* Version history::
* Usage::

@end menu
@node Version history
@section Version history

@table @code

@item 1.2
bugfix in formatter-jump
@item 1.1 (r4851)
Small bug fixes, more annotations to the source code
@item 1.0 (r868)
First public release
@end table


@node Usage
@section Usage

Load this egg like so: 

@code{(require-extension format-modular)}




@node Documentation
@chapter Documentation

Function that allows you to create formatter functions similar to Common Lisp's format or SRFI 28's format) in a very flexible and modular manner.  The resulting functions are reentrant (and thus thread safe).
@deffn {procedure} {make-format-function}


@lisp 
(make-format-function case-sensitive escape formatters)
@end lisp



Create and return a procedure that can be used as a format function. The resulting procedure receives a port, a format string and optional arguments. It parses the format string according to the @code{formatters} parameter and outputs a result to the port specified. If, instead of a port, @code{#t} is specified, the results will be sent to the current output port. If, on the other hand, @code{#f} is passed, the procedure will store its output on a new string and return it.

The returned procedure parses the format string looking for occurrences of the @code{escape} character (usually @code{#~}; when one is found, a function from the @code{formatters} argument is called.

@code{formatters} is a list of formatters. Each formatter is itself a list of @code{(char function)} pairs, where @code{char} is the character for the escape sequence being defined and @code{function} the function to call when the character, preceeded by @code{escape<}, is found in the format string.

To produce the functions included in the formatters, use @code{(formatter-function proc)}, where @code{proc} is a procedure that receives the following parameters:

@table @asis

@item @code{state}


A structure with internal information.  You won't normally inspect this directly but rather pass it to other functions that require it (such as @code{out-char} and @code{out-string}).
@item @code{start}


The position in the format string where the @code{escape} sequence was found.  You'll normally just ignore this.
@item @code{params}


A list with paramters that occur between @code{escape} and @code{char}(for example, in a format string such as @code{~23,33,12A}).
@item @code{colon}, @code{atsign}


Booleans indicating whether those characters occur between @code{escape} and @code{char}.
@end table

To output info at the current position, the formatter functions should use the @code{out-char} and @code{out-string} functions.  The receive the @code{state} parameter (as passed to the formatter) and a character and string respectively.
@end deffn

@deffn {procedure} {format}


@lisp 
(format port fmtstring . args)
@end lisp



This procedure is compliant to @url{http://srfi.schemers.org/srfi-28/srfi-28.html, SRFI-28}

This implementation of @code{FORMAT} supports the following escape sequences:

@verbatim
?!P{}^()%/~|_XDOB[;]?*ASCRFEQGT
@end verbatim


The following are known to be missing:

@verbatim
$&|IY
@end verbatim


If you know of another unsupported standard escape sequence, please contact the authors.

Please consult a Common LISP @url{http://www.lisp.org/HyperSpec/Body/sec_22-3.html, format reference manual} for a detailed description of the format string syntax.
@end deffn



@node License
@chapter LicenseThe Modular Format egg for Chicken Scheme is in the public domain and may be reproduced or copied without
permission from its authors.  Citation of the source is appreciated.


@node Index
@unnumbered Index

@printindex fn


@bye