/ 
Lisp-Fmt-0.01
River stage zero No dependents
/ Lisp::Fmt

NAME

Lisp::Fmt - Perl module for Common Lisp like formatting

SYNOPSIS

use Lisp::Fmt;
$str = fmt("~{~a ~5,,,'*a~}", $a,$b,$c,$d);  # store result in $str
pfmt("~{ ~a~5,,,'*a~}", $a,$b,$c,$d);	 # print to stdout

DESCRIPTION

The Common Lisp "format" function provides an extremely rich set of formatting directives. This module brings this to Perl.

The formatting directives all begin with a ~ and take the form: ~[N]{,N}[@][:]X

where N is a number, X is a formatting directive, and @ and : are optional modifiers. Recognized directives are: A, S, W, D, O, B, X, R, C, P, T, ~, %, |, _, ?, *, \n, {, }, (, ), [, ], <, >, ^

examples:

   C<~A>		- simplest format spec, prints the arg
   C<~D>		- prints a number in base 10
   C<~X>		- prints a number in base 16
   C<~12R>		- prints a number in base 12
   C<~@R>		- prints a number in roman numerals
   C<~#[ none~; ~a~; ~a and ~a~:;~!{~#[~; and~] ~a~^,~}~].">
		- prints a list in nice readable english

FORMAT SPEC

as a param, a v will read the param from the arglist
a # will interpolate to the number of remaining args

     the directive can be one of:

A  print the arg
S  print the arg in a readable form (strings are quotes,...)
        @ will pad on left
        params are: mincols (maxcols if <0), colinc, minpad, padchar, overflowchar

~ print a ~ [N ~s]
% print a newline [N newlines]
| print a formfeed [N formfeeds]
_ print a space [N spaces]
& print a newline unless already at the beginning of a line
T tabulate
     @ relative
	 params are: colnum, colinc

n ignore the newline and any following whitespace
     : newline is ignored, whitespace is left
     @ newline is printed, following whitespce is ignored
* next arg is ignored, with param, next N args are ignored
     : back up in arg list, with param, backup N args
     @ goto 0th arg, or with a param, Nth arg 
? indirect - 2 args are a format string and list of args
     @ - 1 arg - is a format string, use args from current arglist

P pluralize
     @ use y/ies
     : use previous arg

D a number in base 10
O a number in base 8
X a number in base 16
B a number in base 2
R a number in specified radix (ie. ~7R)
    @ print leading sign
    : print with commas
    params are: mincol, padchar, commachar, commawidth, overflowchar

 without a radix specifier:
      in english "four"
   :  in english, ordinal "fourth"
   @  in roman "IV"
   :@ in old roman "IIII"


C a character
    @ as with write
    : spell out control chars

( downcase until ~)    - hello world
    @  capitalize the first word  - Hello world
    :  capitalize  - Hello World
    :@ uppercase  - HELLO WORLD

{ iteration spec until ~}
    @  use remaining args
    :  arg is list of sublists
    :@ use remaining args, which are sublists

[ conditional spec, separated with ~; ending with ~]
    choose item specified by arg  ~:; is default item
    with a param, chhose with it instead of arg
    @ choose if not false
    : use first item if false, second otherwise

^ abort ? {} or <> if no args remain,
    or if a param is given, it is 0
    or if 2 params are given, they are equal
    or if 3 params are given, the 1st is <= 2nd <= 3rd
    : terminate an entire :{ or :@{, not just this iteration

For a more complete description of the various formatting directives, parameters, etc. see your favorite lisp reference, such as http://www.harlequin.com/education/books/HyperSpec/Body/sec_22-3.html.

NOTES

! is a synonym for @

Often used format strings can be pre-compiled: $f = Fmt::compile("~{ ~a ~5,,,'*a~}"); $str = fmt( $f, ...);

when lisp says an arg is a "list", we translate that as a reference to a list (or hash)

lisp: (format () "~{ ~A~}\n" '(a b c d e))
perl: fmt( "~{ ~A~}\n", ["a", "b", "c", "d"])
      fmt( "~{ key ~A value ~A\n~}", {foo=>1, bar=>2, baz=>3})

BUGS

Floating-point output is not yet supported.

the <> formatting support is incomplete.

the radix for ~R is restricted to the range 1-36

no test is performed to detect circular data structures

many other bugs not listed here

CHANGES

none.

TO DO

see BUGS.

SEE ALSO

Common Lisp - The Language 2nd. ed.
L<http://www.harlequin.com/education/books/HyperSpec/Body/sec_22-3.html>
Yellowstone National Park.

AUTHOR

Jeff Weisberg - http://www.tcp4me.com/code/

COPYRIGHT

   This software is Copyright (c) 1998 Jeff Weisberg
   Permission is granted to use, copy and distribute this software
   under the following conditions:
   -   This license covers the original software, as well as
	modified or derived works.
   -   All modified or derived works must contain this notice
       unmodified and in its entirety.
   -   This software is not to be used for any purpose which
	may be considered illegal, immoral, or unethical.
   -   This software is provided as is and without warranty.