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.

cpanm Lisp::Fmt

perl -MCPAN -e shell
install Lisp::Fmt