NAME

VERSION

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

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

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

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

  I would like to buy %d %s today.

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

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

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

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

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

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

AUTHORS

• Ricardo Signes <rjbs@cpan.org>
• Darren Chamberlain <darren@cpan.org>

COPYRIGHT AND LICENSE

This is free software, licensed under:

  The GNU General Public License, Version 2, June 1991