Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
String::Formatter(3)  User Contributed Perl Documentation String::Formatter(3)

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
       o   Ricardo Signes <rjbs@cpan.org>

       o   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

perl v5.24.1			  2013-11-09		  String::Formatter(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | FORMAT STRINGS | HISTORY | AUTHORS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=String::Formatter&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help