SEARCH
NEW RPMS
DIRECTORIES
ABOUT
FAQ
VARIOUS
BLOG
DONATE




YUM REPOSITORY

 
 

MAN page from Mandriva 2010 perl-String-Formatter-0.100.720-1mdv2010.1.noarch.rpm

String::Formatter

Section: User Contributed Perl Documentation (3)
Updated: 2010-03-13
Index 

NAME

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

VERSION

version 0.100720 

WARNING

This module is brand new (as of today, 2009-11-16) and parts of its interfacemay 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?
 

DESCRIPTION

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

Normally, String::Formatter will be used to import a sprintf-like routinereferred to as ""stringf"", but which can be given any name you like. Thisroutine acts like sprintf in that it takes a string and some inputs and returnsa 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 byimporting 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 differentbehaviors, which are installed with different names. Since the behavior ofthese 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, and a "method_stringf" export, which defaults "method_replace" and"require_single_input". For more on these, keep reading, and check out thecookbook.

String::Formatter::Cookbook provides a number of recipes for ways to putString::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 (forfixed content) and hashrefs (for formatting code sections).

The semantics of the hashrefs returned are not yet stable enough to be worthdocumenting. 

hunk_simply

This is the default format hunker. It implements the format string semanticsdescribed above. 

input_processor

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

return_input

This input processor, the default, simply returns the input it was given withno validation or transformation. 

require_named_input

This input processor will raise an exception unless there is exactly onepost-format-string argument to the format call, and unless that argument is ahashref. It will also replace the arrayref with the given hashref sosubsequent 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 theinput itself. 

forbid_input

This input processor will raise an exception if any input is given. In otherwords, formatters with this input processor accept format strings and nothingelse. 

string_replacer

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

positional_replace

This replacer matches inputs to the hunk's position in the format string. Thisis the default replacer, used in the synopsis, above, which shouldmake its behavior clear. At present, fixed-string conversions do not affectthe 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 input2. 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 bylooking in the hashref for the brace-enclosed name on each format code. Here'san example use:

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

method_replace

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

hunk_formatter

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

format_simply

This is the default hunk formatter. It deals with minimum and maximum widthcues as well as left and right alignment. Beyond that, it does no formattingof the replacement string. 

FORMAT STRINGS

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

  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 theycan be replaced on a per-formatter basis. Right now, they're mostly a subsetof 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 inString::Formatter's default behavior.

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

This returns a new formatter. The "codes" argument contains the formattingcodes 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. Thishashref can be accessed later with the "codes" method.

The other four arguments change how the formatting occurs. Formatting happensin 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 thatisn't given. Values must be either strings (which are interpreted as methodnames) or coderefs. The semantics for each method are descibed in the methods' sections, below. 

HISTORY

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

AUTHORS

  Ricardo Signes <rjbsAATTcpan.org>  Darren Chamberlain <darrenAATTcpan.org>
 

COPYRIGHT AND LICENSE

This software is Copyright (c) 2010 by Ricardo Signes <rjbsAATTcpan.org>.

This is free software, licensed under:

  The GNU General Public License, Version 2, June 1991


 

Index

NAME
VERSION
WARNING
SYNOPSIS
DESCRIPTION
METHODS
new
format
format_hunker
hunk_simply
input_processor
return_input
require_named_input
require_single_input
forbid_input
string_replacer
positional_replace
named_replace
method_replace
hunk_formatter
format_simply
FORMAT STRINGS
HISTORY
AUTHORS
COPYRIGHT AND LICENSE

This document was created byman2html,using the manual pages.