NAME
    String::Format - printf-like string formatting capabilities with
    arbitrary format definitions

ABSTRACT
    String::Format allows for printf-style formatting capabilities with
    arbitrary format definitions

SYNOPSIS
      # In a script invoked as:
      # script.pl -f "I like %a, %b, and %g, but not %m or %w."

      use String::Format;
      use Getopt::Std;

      my %fruit = (
            'a' => "apples",
            'b' => "bannanas",
            'g' => "grapefruits",
            'm' => "melons",
            'w' => "watermelons",
      );

      use vars qw($opt_f);
      getopt("f");

      print stringf($opt_f, %fruit);
  
      # prints:
      # I like apples, bannanas, and grapefruits, but not melons or watermelons.

DESCRIPTION
    String::Format lets you define arbitrary printf-like format sequences to
    be expanded. This module would be most useful in configuration files and
    reporting tools, where the results of a query need to be formatted in a
    particular way. It was inspired by mutt's index_format and related
    directives (see
    http://www.mutt.org/doc/manual/manual-6.html#index_format).

FUNCTIONS
  stringf

    String::Format exports a single function called stringf. stringf takes
    two arguments: a format string (see FORMAT STRINGS, below) and a hash
    (or reference to a hash) of name => value pairs. These name => value
    pairs are what will be expanded in the format string.

FORMAT STRINGS
    Format strings must match the following regular expression:

        /(%              # leading '%'
           ([+-])?       # optional alignment specifier
           (\d*)?        # optional field width
           ({.*?})?      # optional stuff inside
           ([$chars])    # actual format character
         )/

    where $chars is:

        join '', keys %args;

    where %args is the hash passed as the second parameter to stringf. If
    the escape character specified does not exist in %args, then the
    original string is used. The alignment and field width options function
    identically to how they are defined in sprintf(3) (any variation is a
    bug, and should be reported).

    The value attached to the key can be a scalar value or a subroutine
    reference; if it is a subroutine reference, then anything between the
    '{' and '}' ($4 in the above regex) will be passed as $_[0] to the
    subroutine reference. This allows for entries such as this:

      %args = (
          d => sub { POSIX::strftime($_[0], localtime) }, 
      );

    Which can be invoked with this format string:

      "It is %{%M:%S}d right now, on %{%A, %B %e}d."

    And result in (for example):

      It is 17:45 right now, on Monday, February 4.

    Note that since the string is passed unmolested to the subroutine
    reference, and strftime would Do The Right Thing with this data, the
    above format string could be written as:

      "It is %{%M:%S right now, on %A, %B %e}d."

    By default, the formats 'n' and 't' are defined to be a newline and tab,
    respectively, if they are not already defined in the hash of arguments
    that gets passed it. So we can add carriage returns simply:

      "It is %{%M:%S right now, on %A, %B %e}d.%n"

    Because of how the string is parsed, the normal "\n" and "\t" are turned
    into two characters each, and are not treated as a newline and tab. This
    is a bug.

TODO
    *   Make sure that the handling of formatting, such as the alignment and
        field width pieces, are consistent with sprintf.

AUTHOR
    darren chamberlain <darren@cpan.org>