String::Formatter(3) User Contributed Perl Documentation String::Formatter(3)NAMEString::Formatter - build sprintf-like functions of your own
VERSION
version 0.102082
WARNING
This module is brand new (as of today, 2009-11-16) and parts of its
interface may change substantially before this warning goes away!
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?
DESCRIPTIONString::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.
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 modifers 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
descibed in the methods' sections, below.
HISTORYString::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) 2010 by Ricardo Signes <rjbs@cpan.org>.
This is free software, licensed under:
The GNU General Public License, Version 2, June 1991
perl v5.14.1 2010-10-19 String::Formatter(3)
