String::Print - printf alternatives
### Functional interface use String::Print qw/printi printp/, %config; # interpolation of arrays and hashes printi 'age {years}', years => 12; printi 'price-list: {prices%.2f}', prices => \@prices; printi 'dump: {hash}', hash => \%config; # same with positional parameters printp 'age %d", 12; printp 'price-list: %.2f', \@prices; printp 'dump: %s', \%settings; ### Object Oriented interface use String::Print 'oo'; # import nothing my $f = String::Print->new(%config); # same, called directly $f->printi('age {years}', years => 12); $f->printp('age %d', 12); ### via Log::Report's __* functions use Log::Report::Optional; print __x"age {years}", years => 12;
This module inserts values into (translated) strings. It provides printf and sprintf alternatives via both an object oriented and a functional interface.
printf
sprintf
Read in the DETAILS chapter below, why this module provides a better alternative for printf(). Also, some extended examples can be found there. Take a look at them first!
printf()
See functions printi(), sprinti(), printp(), and sprintp(): you can also call them as method.
use String::Print 'oo'; my $f = String::Print->new(%config); $f->printi($format, @params); # exactly the same functionality: use String::Print 'printi', %config; printi $format, @params;
The Object Oriented interface wins when you need the same configuration in multiple source files, or when you need different configurations within one program. In these cases, the hassle of explicitly using the object has some benefits.
-Option --Default modifiers [ qr/^%\S+/ = \&format_printf]> serializers <useful defaults>
Add one or more modifier handlers to power of the formatter. They will get preference over the predefined modifiers, but lower than the modifiers passed to print[ip] itself.
print[ip]
How to serialize data elements.
example:
my $f = String::Print->new ( modifiers => [ EUR => sub {sprintf "%5.2f e", $_[0]} ] , serializers => [ UNDEF => sub {'-'} ] ); $f->printi("price: {p EUR}", p => 3.1415); # price: ␣␣3.14 e $f->printi("count: {c}", c => undef); # count: -
The functional interface creates a hidden object. You may import any of these functions explicitly, or all together by not specifying the names.
Calls sprinti() to fill the data in PAIRS or HASH in FORMAT, and then sends it to the FILEHANDLE (by default the selected file)
open my $fh, '>', $file; printi $fh, ... printi \*STDERR, ...
Calls sprintp() to fill the data in PAIRS or HASH in FORMAT, and then sends it to the FILEHANDLE (by default the selected file)
The FORMAT refers to some string, maybe the result of a translation.
The PAIRS (which may be passed as LIST or HASH) contains a mixture of special and normal variables to be filled in. The names of the special variables (the options) start with an underscore (_).
_
-Option --Default _append undef _count undef _join ', ' _prepend undef
Text as STRING appended after FORMAT, without interpolation.
Result of the translation process: when Log::Report subroutine __xn is are used for count-sensitive translation. Those function may add more specials to the parameter list.
Which STRING to be used when an ARRAY is being filled-in.
Text as STRING prepended before FORMAT, without interpolation.
Where sprinti() uses named parameters --especially useful when the strings need translation-- this function stays close to the standard sprintf(). All features of POSIX formats are supported. This should say enough: you can use %3$0#5.*d, if you like.
sprintf()
%3$0#5.*d
It may be useful to know that the positional FORMAT is rewritten and then fed into sprinti(). Be careful with the length of the LIST: superfluous parameter PAIRS are passed along to sprinti(), and should only contain "specials".
sprinti()
# positional parameters my $x = sprintp "dumpfiles: %s\n", \@dumpfiles , _join => ':'; # rewriten and processed as my $x = sprinti "dumpfiles: {filenames}\n" , filenames => \@dumpfiles, _join => ':';
printi()
The printf() function is provided by Perl's CORE; you do not need to install any module to use it. Why would you use consider using this module?
printf() uses positional values, where printi() uses names to refer to the values to be filled-in. Especially in a set-up with translations, where the format strings get extracted into PO-files, it is much clearer to use names. This is also a disadvantage of printp()
printi() supports serialization for specific data-types: how to interpolate undef, HASHes, etc.
undef
Especially useful in context of translations, the FORMAT string may contain (language specific) helpers to insert the values correctly.
Sized string formatting in printf() is broken: it takes your string as bytes, not Perl strings (maybe utf8). In utf8 encoded unicode, one character may use many bytes. Also, some characters are double wide, for instance in Chinese. The printi() implementation will use Unicode::GCString for correct behavior.
To fill-in a FORMAT, three clearly separated components play a role.
How to change the provided values, for instance to hide locale differences.
How to represent (modified) the values correctly, for instance undef and ARRAYs.
The standard UNIX conversion rules, like %d. One conversion rule has been added 'S', for unicode correct behavior.
%d
Simplified:
# sprinti() replaces {$key$modifiers$conversion} by $conversion->($serializer->($modifiers->($arg{$key}))) # sprintp() replaces %pos{$modifiers}$conversion by $conversion->($serializer->($modifiers->($arg[$pos])))
The 'interpolation' functions have named VARIABLES to be filled-in, but also additional OPTIONS. To distinguish between the OPTIONS and VARIABLES (both a list of key-value pairs), the keys of the OPTIONS start with an underscore _. As result of this, please avoid the use of keys which start with an underscore in variable names. On the other hand, you are allowed to interpolate OPTION values in your strings.
There is no way of checking beforehand whether you have provided all values to be interpolated in the translated string. When you refer to value which is missing, it will be interpreted as undef.
When a value is passed as CODE reference, that function will get called to return the value to be filled in. For interpolating, the following rules apply:
Simple scalar values are interpolated "as is"
All members will be interpolated with ,␣ between the elements. Alternatively (maybe nicer), you can pass an interpolation parameter via the _join OPTION.
,␣
_join
By default, HASHes are interpolated with sorted keys,
$key => $value, $key2 => $value2, ...
There is no quoting on the keys or values (yet). Usually, this will produce an ugly result anyway.
With the serialization parameter, you can overrule the interpolation of above defaults, but also add rules for your own objects. By default, objects get stringified.
serialization
serialization => [ $myclass => \&name_in_reverse ] sub name_in_reverse($$$) { my ($formatter, $object, $args) = @_; # the $args are all parameters to be filled-in scalar reverse $object->name; }
Modifiers are used to change the value to be inserted, before the characters get interpolated in the line.
Next to the name, you can specify a format code. With (gnu) gettext(), you often see this:
gettext()
printf gettext("approx pi: %.6f\n"), PI;
Locale::TextDomain has two ways:
printf __"approx pi: %.6f\n", PI; print __x"approx pi: {approx}\n", approx => sprintf("%.6f", PI);
The first does not respect the wish to be able to reorder the arguments during translation (although there are ways to work around that) The second version is quite long. The content of the translation table differs between the examples.
With Log::Report, above syntaxes do work, but you can also do:
Log::Report
# with optional translations print __x"approx pi: {pi%.6f}\n", pi => PI;
The base for __x() is the printi() provided by this module. Internally, it will call printi to fill in parameters:
__x()
printi
printi "approx pi: {pi%.6f}\n", pi => PI;
Another example:
printi "{perms} {links%2d} {user%-8s} {size%10d} {fn%S}\n" , perms => '-rw-r--r--', links => 7, user => 'me' , size => '12345', fn => $filename;
An additional advantage is the fact that not all languages produce comparable length strings. Now, the translators can take care that the layout of tables is optimal.
Above example in printp() syntax, shorter but less maintainable:
printp "%s %2d %-8s 10d %s\n" , '-rw-r--r--', 7, 'me', '12345', $filename;
The POSIX printf() does not handle unicode strings. Perl does understand that the 's' modifier may need to insert utf8 so does not count bytes but characters. printi() does not use characters but "grapheme clusters" via Unicode::GCString. Now, also composed characters do work correctly.
Additionally, you can use the new 'S' conversion to count in columns. In fixed-width fonts, graphemes can have width 0, 1 or 2. For instance, Chinese characters have width 2. When printing in fixed-width, this 'S' is probably the better choice over 's'.
You may pass your own modifiers. In Object Oriented syntax:
my $f = String::Print->new ( modifiers => [ qr/[€₤]/ => \&money ] );
In function syntax
use String::Print 'printi', 'sprinti' , modifiers => [ qr/[€₤]/ => \&money ]; sub money$$$$) { my ($formatter, $modif, $value, $args) = @_; $modif eq '€' ? sprintf("%.2f EUR", $value+0.0001) : $modif eq '₤' ? sprintf("%.2f GBP", $value/1.23+0.0001) : 'ERROR'; }
Now:
printi "price: {p€}", p => $pi; # price: 3.14 EUR printi "price: {p₤}", p => $pi; # price: 2.55 GBP
This is very useful in the translation context, where the translator can specify abstract formatting. Using printp() makes it a little shorter, but will become quite complex when there are more parameter in one string:
printp "price: %{€}s", $pi; # price: 3.14 EUR printp "price: %{₤}s", $pi; # price: 2.55 GBP
Another example. Now, we want to add timestamps. In this case, we decide for modifier names in \w, so we need a blank to separate the paramter from the modifer.
\w
use POSIX qw/strftime/; use String::Print modifiers => [ qr/T|DT|D/ => \&_timestamp ]; sub _timestamp($$$$) { my ($formatter, $modif, $value, $args) = @_; my $time_format = $modif eq 'T' ? '%T' : $modif eq 'D' ? '%F' : $modif eq 'DT' ? '%FT%TZ' : 'ERROR'; strftime $time_format, gmtime($value); }; printi "time: {t T}", t => $now; # time: 10:59:17 printi "date: {t D }", t => $now; # date: 2013-04-13 printi "both: {t DT}", t => $now; # both: 2013-04-13T10:59:17Z printp "time: %{T}s", $now; # time: 10:59:17 printp "date: %{D}s", $now; # date: 2013-04-13 printp "both: %{DT}s", $now; # both: 2013-04-13T10:59:17Z
You can add more than one modifier. The modifiers detect the extend of their own information (via a regular expression), and therefore the formatter understands where one ends and the next begins.
The modifiers are called in order:
printi "price: {p€%9s}\n", p => $p; # price: ␣␣␣123.45 printi ">{t T%10s}<", t => $now; # >␣␣12:59:17< printp "price: %9{€}s\n", $p; # price: ␣␣␣123.45 printp ">%10{T}s<", $now; # >␣␣12:59:17<
There are a few more modules on CPAN which extend the functionality of printf(). To name a few: String::Format, String::Errf, String::Formatter, Text::Sprintf::Named, Acme::StringFormat, Text::sprintf, Log::Sprintf, and String::Sprintf. They are all slightly different.
When the String::Print module got created, none of the mentioned above natively handled unicode correctly. Global configuration of serializers, and modifiers is usually not possible, but only provided per function call. Only String::Print cleanly separates the roles of serializers, modifiers, and conversions.
String::Print
This module is part of String-Print distribution version 0.12, built on April 29, 2013. Website: http://perl.overmeer.net/log-report/
Copyrights 2013 by [Mark Overmeer]. For other contributors see ChangeLog.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html
To install String::Print, copy and paste the appropriate command in to your terminal.
cpanm
cpanm String::Print
CPAN shell
perl -MCPAN -e shell install String::Print
For more information on module installation, please visit the detailed CPAN module installation guide.