### Functional interface
use String::Print; # simpelest way
use String::Print qw/printi printp/, %config;
printi 'age {years}', years => 12;
# interpolation of arrays and hashes (serializers)
printi 'price-list: {prices}', prices => \@p, _join => "+";
printi 'dump: {c}', c => \%config;
# same with positional parameters
printp 'age %d", 12;
printp 'price-list: %.2f', \@prices;
printp 'dump: %s', \%settings;
# modifiers
printi 'price: {price%.2f}', price => 3.14 * EURO;
# [0.91] more complex interpolation names
printi 'filename: {c.filename}', c => \%config;
printi 'username: {user.name}', user => $user_object;
printi 'price: {product.price €}', product => $db->product(3);
### Object Oriented interface
use String::Print 'oo', %config; # import no functions
my $f = String::Print->new(%config);
$f->printi('age {years}', years => 12);
$f->printp('age %d', 12);
### via Log::Report's __* functions (optional translation)
use Log::Report; # or Log::Report::Optional
print __x"age {years}", years => 12;
### via Log::Report::Template (Template Toolkit extension)
[% SET name = 'John Doe' %]
[% loc("Dear {name},") %] # includes translation
This module inserts values into (format) strings. It provides printf()
and sprintf() alternatives via both an object oriented and a functional
interface.
Read in the DETAILS chapter below, why this module provides a better
alternative for printf(). Also, some extended examples can be
found down there. Take a look at them first, when you start using this
module!
Your manual-page reader may not support the unicode used in some of the examples below.
printi() to replace printf()?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 parameters, 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.
printf() is broken: it takes your string
as bytes, not Perl strings (which may be utf8). In unicode, one
"character" may use many bytes. Also, some characters are displayed
double wide, for instance in Chinese. The printi() implementation
will use Unicode::GCString for correct behavior.
To fill-in a FORMAT, four clearly separated components play a role:
undef
and ARRAYs.
%d. One conversion rule
has been added 'S', which provides unicode correct behavior.
Simplified:
# sprinti() replaces "{$key$modifiers$conversion}" by
$encode->($format->($serializer->($modifiers->($args{$key}))))
# sprintp() replaces "%pos{$modifiers}$conversion" by
$encode->($format->($serializer->($modifiers->($arg[$pos]))))
Example:
printi "price: {price € %-10s}", price => $cost;
printi "price: {price € %-10s}", { price => $cost };
printp "price: %-10{€}s", $cost;
$value = $cost (in €)
$modifier = convert € to local currency £
$serializer = show float as string
$format = column width %-10s
$encode = £ into £ # when encodingFor('HTML')
A key is a bareword (like a variable name) or a list of barewords separated by dots (no blanks!)
Please use explanatory key names, to help the translation process once you need that (in the future).
A simple key directly refers to a named parameter of the function or method:
printi "Username: {name}", name => 'John';
You may also pass them as HASH or CODE:
printi "Username: {name}", { name => 'John' };
printi "Username: {name}", name => sub { 'John' };
printi "Username: {name}", { name => sub { 'John' } };
printi "Username: {name}", name => sub { sub {'John'} };
The smartness of pre-processing CODE is part of serialization.
[0.91] In the previous section, we kept our addressing it simple: let's change that now. Two alternatives for the same:
my $user = { name => 'John' };
printi "Username: {name}", name => $user->{name}; # simple key
printi "Username: {user.name}", user => $user; # complex key
The way these complex keys work, is close to the flexibility of template toolkit: the only thing you cannot do, is passing parameters to called CODE.
You can pass a parameter name as HASH, which contains values. This may even be nested into multiple levels. You may also pass objects, class (package names), and code references.
In above case of user.name, when user is a HASH it will take the
value which belongs to the key name. When user is a CODE, it will
run code to get a value. When user is an object, the method name
is called to get a value back. When user is a class name, the name
refers to an instance method on that class.
More examples which do work:
# when name is a column in the database query result
printi "Username: {user.name}", user => $sth->fetchrow_hashref;
# call a sub which does the database query, returning a HASH
printi "Username: {user.name}", user => sub { $db->getUser('John') };
# using an instance method (object)
{ package User;
sub new { bless { myname => $_[1] }, $_[0] }
sub name { $_[0]->{myname} }
}
my $user = User->new('John');
printi "Username: {user.name}", user => $user;
# using a class method
sub User::count { 42 }
printi "Username: {user.count}", user => 'User';
# nesting, mixing
printi "Complain to {product.factory.address}", product => $p;
# mixed, here CODE, HASH, and Object
printi "Username: {document.author.name}", document => sub {
return +{ author => User->new('John') }
};
Limitation: you cannot pass arguments to CODE calls.
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.
,␣ between the elements.
Alternatively (maybe nicer), you can pass an interpolation parameter
via the _join OPTION.
printi "matching files: {files}", files => \@files, _join => ', '
$key => $value, $key2 => $value2, ...
There is no quoting on the keys or values (yet). Usually, this will produce an ugly result anyway.
serialization parameter, you can overrule the interpolation
of above defaults, but also add rules for your own objects. By default,
objects get stringified.
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. This is a powerful simplification. Some useful modifiers are already provided by default. They are also good examples how to write your own.
Let's discuss this with an example. In traditional (gnu) gettext, you would write:
printf(gettext("approx pi: %.6f\n"), PI);
to get PI printed with six digits in the fragment. Locale::TextDomain has two ways to achieve that:
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 string to be translated differs between the two examples.
With Log::Report, above syntaxes do work as well, but you can also do:
# 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:
printi "approx pi: {pi%.6f}\n", pi => PI;
Another example:
printi "{perms} {links%2d} {user%-8s} {size%10d} {fn}\n",
perms => '-rw-r--r--', links => 7, user => 'me',
size => 12345, fn => $filename;
An additional advantage (when you use translation) is the fact that not all languages produce comparable length strings. Now, the translators can change the format, such that the layout of tables is optimal for their language.
Above example in printp() syntax, shorter but less maintainable:
printp "%s %2d %-8s 10d %s\n",
'-rw-r--r--', 7, 'me', 12345, $filename;
As shown in the examples above, you can specify a format. This can, for instance, help you with rounding or columns:
printp "π = {pi%.3f}", pi => 3.1415;
printp "weight is {kilogram%d}", kilogram => 127*OUNCE_PER_KILO;
printp "{filename%-20.20s}\n", filename => $fn;
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'. When the field does not specify its width, then there is no performance penalty for using 'S'.
# name right aligned, commas on same position, always
printp "name: {name%20S},\n", name => $some_chinese;
[0.96] Only available when you print (big) decimals: add an underscore, comma, or dot on the thousands.
printi "{count%_d}\n", count => 1e9; # 1_000_000_000
printi "{count%,d}\n", count => 1e9; # 1,000,000,000
printi "{count%.d}\n", count => 1e9; # 1.000.000.000
printi "'{v%10.d}'", v => 10000; # ' 10.000';
printi "'{v%10_d}'", v => -10000; # ' -10_000';
printi "'{v%-10.d}'", v => 10000; # '10.000 ';
printi "'{v%-10.d}'", v => -10000; # '-10.000 ';
printi "'{v%+10,d}'", v => 10000; # ' +10,000';
printi "'{v% ,d}'", v => 10000; # ' 10,000';
printi "'{v% ,d}'", v => -10000; # '-10,000';
[0.91] Too often, you have to translate a (file) size into humanly readible
format. The BYTES modifier simplifies this a lot:
printp "{size BYTES} {fn}\n", fn => $fn, size => -s $fn;
The output will always be 6 characters. Examples are "999 B", "1.2 kB", and " 27 MB".
[0.95] interpolate the parameter with HTML entity encoding.
[0.91] A set of modifiers help displaying dates and times. They are a little flexible in values they accept, but do not expect miracles: when it get harder, you will need to process it yourself.
The actual treatment of a time value depends on the value: three different situations:
A pure numeric value is considered "seconds since epoch", unless it is smaller than 21000000, in which case it is taken as date without separators.
The same formats are understood as in the next option, but without time-zone information. The date is processed as text as if in the local time zone, and the output in the local time-zone.
By far not all possible date formats are supported, just a few common versions, like
2017-06-27 10:04:15 +02:00 2017-06-27 17:34:28.571491+02 # psql timestamp with zone 20170627100415+2 2017-06-27T10:04:15Z # iso 8601 20170627 # only for YEAR and DATE 2017-6-1 # only for YEAR and DATE 12:34 # only for TIME
The meaning of 05-04-2017 is unclear, so not supported. Milliseconds get ignored.
When the provided value has a timezone indication, it will get converted into the local timezone of the observer.
The output of YEAR is in format 'YYYY', for DATE it will always be
'YYYY-MM-DD', where TIME produces 'HH:mm:ss'.
The short form DT is an alias for DT(FT). The DT modifier can
produce different formats:
DT(ASC) : %a %b %e %T %Y asctime output DT(FT) : %F %T YYYY-MM-DD HH:MM:SS DT(ISO) : %FT%T%z iso8601 DT(RFC822) : %a, %d %b %y %T %z email old DT(RFC2822) : %a, %d %b %Y %T %z email newer DT(RFC5322) : %a, %d %b %Y %T %z email newest [0.96]
You may suggest additional formats, or add your own modifier.
[0.91] By default, an undefined value is shown as text 'undef'. Empty
strings are shown as nothing. This may not be nice. You may want to
be more specific when a value is missing.
"visitors: {count //0}"
"published: {date DT//'not yet'}"
"copyright: {year//2017 YEAR}
Modifiers will usually return undef when they are called with an
undefined or empty value. By the right order of '//', you may product
different kinds of output:
"price: {price//5 EUR}"
"price: {price EUR//unknown}"
[0.96] As (always trailing) modifier, this will show the interpolated name before the value. It might simplify debugging statements.
printi "visitors: {count=}", count => 1; # visitors: count=1
printi "v: {count %-8,d =}X", count => 10000; # v: count=10,000␣␣X
You may pass your own modifiers. A modifier consists of a selector and a CODE, which is called when the selector matches. The selector is either a string or a regular expression.
# in Object Oriented syntax:
my $f = String::Print->new(
modifiers => [ qr/[€₤]/ => \&money ],
);
# in function syntax:
use String::Print 'printi', 'sprinti',
modifiers => [ qr/[€₤]/ => \&money ];
# the implementation:
sub money$$$$)
{ my ($formatter, $modif, $value, $args) = @_;
$modif eq '€' ? sprintf("%.2f EUR", $value+0.0001)
: $modif eq '₤' ? sprintf("%.2f GBP", $value/1.16+0.0001)
: 'ERROR';
}
Using printp() makes it a little shorter, but will become quite complex when there are more parameter in one string.
printi "price: {p€}", p => $pi; # price: 3.14 EUR
printi "price: {p₤}", p => $pi; # price: 2.71 GBP
printp "price: %{€}s", $pi; # price: 3.14 EUR
printp "price: %{₤}s", $pi; # price: 2.71 GBP
This is very useful in the translation context, where the translator can specify abstract formatting rules. As example, see the (GNU) gettext files, in the translation table for Dutch into English. The translator tells us which currency to use in the display.
msgid "kostprijs: {p€}"
msgstr "price: {p₤}"
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 parameter from the modifer.
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!
[0.91] This module is also used by Log::Report::Template, which is used to insert (translated) strings with parameters into HTML templates. You can imagine that some of the parameter may need to be encoded to HTML in the template, and other not.
In pure Template Toolkit, you would write
# in your TT-template <div>Username: [% username | html %] # in your code username => $user->name,
With plain String::Print with output encoding enabled, you can do:
# in your TT-template
<div>[% show_username %]
# in your code with encodeFor('HTML')
show_username => printi("Username: {user}", user => $user->name),
# or
show_username => printp("Username: %s", $user->name),
That does not look very efficient, however it changes for the good when this is combined with Log::Report::Lexicon (translations) You can either do:
# in your TT-template
<div>[% show_username %]
# in your code with encodeFor('HTML')
show_username => __x("Username: {user}", user => $user->name),
Shorter:
# in your TT-template with encodeFor('HTML')
<div>[% loc("Username: {user}", user => username) %]
# in your code
username => $user->name,
Even shorter:
# in your TT-template with encodeFor('HTML')
<div>[% loc("Username: {user.name}", user => userobj) %]
# in your code
userobj => $user,
Shortest:
# in your TT-template with encodeFor('HTML')
<div>[% loc("Username: {user.name}") %]
# in your code
user => $user,
Shorter that the original, and translations for free! More examples in Log::Report::Template.
In some cases, the data which is inserted is already encoded in the output syntax. For instance, you already have HTML to be included.
The default exclusion rule for HTML output is qr/html$/i, which
means that all inserted named parameters, where the name ends on html
will not get html-entity encoded.
This will work by default:
# with encodeFor('HTML')
printp "Me & Co: {name}, {description_html}",
name => 'René', description_html => $descr;
This may result in:
Me & Co: René, <font color="red">new member
Better not to have HTML in your program: leave it to the template. But in some cases, you have no choice.
There are a quite a number of 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 was created, none of the modules
mentioned above handled unicode correctly. Global configuration
of serializers and modifiers is also usually not possible, sometimes
provided per explicit function call. Only String::Print cleanly
separates the roles of serializers, modifiers, and conversions.
String::Print is nicely integrated with Log::Report.