Provided by: libstring-formatter-perl_0.102084-1_all bug

NAME

       String::Formatter - build sprintf-like functions of your own

VERSION

       version 0.102084

SYNOPSIS

         use String::Formatter stringf => {
           -as   => 'str_rf',
           codes => {
             f => sub { $_ },
             b => sub { scalar reverse $_ },
             o => 'Okay?',
           },
         };

         print str_rf('This is %10f and this is %-15b, %o', 'forward', 'backward');

       ...prints...

         This is    forward and this is drawkcab       , okay?

DESCRIPTION

       String::Formatter is a tool for building sprintf-like formatting routines.  It supports
       named or positional formatting, custom conversions, fixed string interpolation, and simple
       width-matching out of the box.  It is easy to alter its behavior to write new kinds of
       format string expanders.  For most cases, it should be easy to build all sorts of
       formatters out of the options built into String::Formatter.

       Normally, String::Formatter will be used to import a sprintf-like routine referred to as
       ""stringf"", but which can be given any name you like.  This routine acts like sprintf in
       that it takes a string and some inputs and returns a new string:

         my $output = stringf "Some %a format %s for you to %u.\n", { ... };

       This routine is actually a wrapper around a String::Formatter object created by importing
       stringf.  In the following code, the entire hashref after "stringf" is passed to
       String::Formatter's constructor (the "new" method), save for the "-as" key and any other
       keys that start with a dash.

         use String::Formatter
           stringf => {
             -as => 'fmt_time',
             codes           => { ... },
             format_hunker   => ...,
             input_processor => ...,
           },
           stringf => {
             -as => 'fmt_date',
             codes           => { ... },
             string_replacer => ...,
             hunk_formatter  => ...,
           },
         ;

       As you can see, this will generate two stringf routines, with different behaviors, which
       are installed with different names.  Since the behavior of these routines is based on the
       "format" method of a String::Formatter object, the rest of the documentation will describe
       the way the object behaves.

       There's also a "named_stringf" export, which behaves just like the "stringf" export, but
       defaults to the "named_replace" and "require_named_input" arguments.  There's a
       "method_stringf" export, which defaults "method_replace" and "require_single_input".
       Finally, a "indexed_stringf", which defaults to "indexed_replaced" and
       "require_arrayref_input".  For more on these, keep reading, and check out the cookbook.

       String::Formatter::Cookbook provides a number of recipes for ways to put String::Formatter
       to use.

METHODS

   new
   format
         my $result = $formatter->format( $format_string, @input );

         print $formatter->format("My %h is full of %e.\n", 'hovercraft', 'eels');

       This does the actual formatting, calling the methods described above, under "new" and
       returning the result.

   format_hunker
       Format hunkers are passed strings and return arrayrefs containing strings (for fixed
       content) and hashrefs (for formatting code sections).

       The hashref hunks should contain at least two entries:  "conversion" for the conversion
       code (the s, d, or u in %s, %d, or %u); and "literal" for the complete original text of
       the hunk.  For example, a bare minimum hunker should turn the following:

         I would like to buy %d %s today.

       ...into...

         [
           'I would like to buy ',
           { conversion => 'd', literal => '%d' },
           ' ',
           { conversion => 's', literal => '%d' },
           ' today.',
         ]

       Another common entry is "argument".  In the format strings expected by "hunk_simply", for
       example, these are free strings inside of curly braces.  These are used extensively other
       existing helpers for things liked accessing named arguments or providing method names.

   hunk_simply
       This is the default format hunker.  It implements the format string semantics described
       above.

       This hunker will produce "argument" and "conversion" and "literal".  Its other entries are
       not yet well-defined for public consumption.

   input_processor
       The input processor is responsible for inspecting the post-format-string arguments,
       validating them, and returning them in a possibly-transformed form.  The processor is
       passed an arrayref containing the arguments and should return a scalar value to be used as
       the input going forward.

   return_input
       This input processor, the default, simply returns the input it was given with no
       validation or transformation.

   require_named_input
       This input processor will raise an exception unless there is exactly one post-format-
       string argument to the format call, and unless that argument is a hashref.  It will also
       replace the arrayref with the given hashref so subsequent phases of the format can avoid
       lots of needless array dereferencing.

   require_arrayref_input
       This input processor will raise an exception unless there is exactly one post-format-
       string argument to the format call, and unless that argument is a arrayref.  It will also
       replace the input with that single arrayref it found so subsequent phases of the format
       can avoid lots of needless array dereferencing.

   require_single_input
       This input processor will raise an exception if more than one input is given.  After input
       processing, the single element in the input will be used as the input itself.

   forbid_input
       This input processor will raise an exception if any input is given.  In other words,
       formatters with this input processor accept format strings and nothing else.

   string_replacer
       The string_replacer phase is responsible for adding a "replacement" entry to format code
       hunks.  This should be a string-value entry that will be formatted and concatenated into
       the output string.  String replacers can also replace the whole hunk with a string to
       avoid any subsequent formatting.

   positional_replace
       This replacer matches inputs to the hunk's position in the format string.  This is the
       default replacer, used in the synopsis, above, which should make its behavior clear.  At
       present, fixed-string conversions do not affect the position of arg matched, meaning that
       given the following:

         my $formatter = String::Formatter->new({
           codes => {
             f => 'fixed string',
             s => sub { ... },
           }
         });

         $formatter->format("%s %f %s", 1, 2);

       The subroutine is called twice, once for the input 1 and once for the input 2.  This
       behavior may change after some more experimental use.

   named_replace
       This replacer should be used with the "require_named_input" input processor.  It expects
       the input to be a hashref and it finds values to be interpolated by looking in the hashref
       for the brace-enclosed name on each format code.  Here's an example use:

         $formatter->format("This was the %{adj}s day in %{num}d weeks.", {
           adj => 'best',
           num => 6,
         });

   indexed_replace
       This replacer should be used with the "require_arrayref_input" input processor.  It
       expects the input to be an arrayref and it finds values to be interpolated by looking in
       the arrayref for the brace-enclosed index on each format code.  Here's an example use:

         $formatter->format("This was the %{1}s day in %{0}d weeks.", [ 6, 'best' ]);

   method_replace
       This string replacer method expects the input to be a single value on which methods can be
       called.  If a value was given in braces to the format code, it is passed as an argument.

   keyed_replace
       This string replacer method expects the input to be a single hashref.  Coderef code values
       are used as callbacks, but strings are used as hash keys.  If a value was given in braces
       to the format code, it is ignored.

       For example if the codes contain "i => 'ident'" then %i in the format string will be
       replaced with "$input->{ident}" in the output.

   hunk_formatter
       The hunk_formatter processes each the hashref hunks left after string replacement and
       returns a string.  When it is called, it is passed a hunk hashref and must return a
       string.

   format_simply
       This is the default hunk formatter.  It deals with minimum and maximum width cues as well
       as left and right alignment.  Beyond that, it does no formatting of the replacement
       string.

FORMAT STRINGS

       Format strings are generally assumed to look like Perl's sprintf's format strings:

         There's a bunch of normal strings and then %s format %1.4c with %% signs.

       The exact semantics of the format codes are not totally settled yet -- and they can be
       replaced on a per-formatter basis.  Right now, they're mostly a subset of Perl's
       astonishingly large and complex system.  That subset looks like this:

         %    - a percent sign to begin the format
         ...  - (optional) various modifiers to the format like "-5" or "#" or "2$"
         {..} - (optional) a string inside braces
         s    - a short string (usually one character) identifying the conversion

       Not all format modifiers found in Perl's "sprintf" are yet supported.  Currently the only
       format modifiers must match:

           (-)?          # left-align, rather than right
           (\d*)?        # (optional) minimum field width
           (?:\.(\d*))?  # (optional) maximum field width

       Some additional format semantics may be added, but probably nothing exotic.  Even things
       like "2$" and "*" are probably not going to appear in String::Formatter's default
       behavior.

       Another subtle difference, introduced intentionally, is in the handling of "%%".  With the
       default String::Formatter behavior, string "%%" is not interpreted as a formatting code.
       This is different from the behavior of Perl's "sprintf", which interprets it as a special
       formatting character that doesn't consume input and always acts like the fixed string "%".
       The upshot of this is:

         sprintf "%%";   # ==> returns "%"
         stringf "%%";   # ==> returns "%%"

         sprintf "%10%"; # ==> returns "         %"
         stringf "%10%"; # ==> dies: unknown format code %

         my $formatter = String::Formatter->new({
           codes => { ... },
           format_hunker   => ...,
           input_processor => ...,
           string_replacer => ...,
           hunk_formatter  => ...,
         });

       This returns a new formatter.  The "codes" argument contains the formatting codes for the
       formatter in the form:

         codes => {
           s => 'fixed string',
           S => 'different string',
           c => sub { ... },
         }

       Code values (or "conversions") should either be strings or coderefs.  This hashref can be
       accessed later with the "codes" method.

       The other four arguments change how the formatting occurs.  Formatting happens in five
       phases:

       1.  format_hunker - format string is broken down into fixed and %-code hunks

       2.  input_processor - the other inputs are validated and processed

       3.  string_replacer - replacement strings are generated by using conversions

       4.  hunk_formatter - replacement strings in hunks are formatted

       5.  all hunks, now strings, are recombined; this phase is just "join"

       The defaults are found by calling "default_WHATEVER" for each helper that isn't given.
       Values must be either strings (which are interpreted as method names) or coderefs.  The
       semantics for each method are described in the methods' sections, below.

HISTORY

       String::Formatter is based on String::Format, written by Darren Chamberlain.  For a
       history of the code, check the project's source code repository.  All bugs should be
       reported to Ricardo Signes and String::Formatter.  Very little of the original code
       remains.

AUTHORS

       •   Ricardo Signes <rjbs@cpan.org>

       •   Darren Chamberlain <darren@cpan.org>

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2013 by Ricardo Signes <rjbs@cpan.org>.

       This is free software, licensed under:

         The GNU General Public License, Version 2, June 1991