=encoding utf8

=head1 NAME

String::Print - printf alternatives

=head1 SYNOPSIS

 ### 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;

=head1 DESCRIPTION

This module inserts values into (translated) strings.  It provides
C<printf> and C<sprintf> alternatives via both an object oriented and a
functional interface.

Read in the L<DETAILS> chapter below, why this module provides a better
alternative for C<printf()>.  Also, some extended B<examples> can be
found there.  Take a look at them first!

=head1 METHODS

=head2 The Object Oriented interface

See functions L<printi()|String::Print/"FUNCTIONS">, L<sprinti()|String::Print/"FUNCTIONS">, L<printp()|String::Print/"FUNCTIONS">, and L<sprintp()|String::Print/"FUNCTIONS">: 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.

=head2 Constructors

=over 4

=item String::Print-E<gt>B<new>(OPTIONS)

 -Option     --Default
  modifiers    [ qr/^%\S+/ = \&format_printf]>
  serializers  <useful defaults>

=over 2

=item modifiers => ARRAY

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 C<print[ip]> itself.

=item serializers => HASH|ARRAY

How to serialize data elements.

=back

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: -

=back

=head2 Attributes

=over 4

=item $obj-E<gt>B<addModifiers>(PAIRS)

=back

=head1 FUNCTIONS

The functional interface creates a hidden object.  You may import any of
these functions explicitly, or all together by not specifying the names.

=over 4

=item B<printi>([FILEHANDLE], FORMAT, PAIRS|HASH)

Calls L<sprinti()|String::Print/"FUNCTIONS"> 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, ...

=item B<printp>([FILEHANDLE], FORMAT, PAIRS|HASH)

Calls L<sprintp()|String::Print/"FUNCTIONS"> to fill the data in PAIRS or HASH in FORMAT, and
then sends it to the FILEHANDLE (by default the selected file)

=item B<sprinti>(FORMAT, PAIRS|HASH)

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 (C<_>).

 -Option  --Default
  _append   undef
  _count    undef
  _join     ', '
  _prepend  undef

=over 2

=item _append => STRING

Text as STRING appended after FORMAT, without interpolation.

=item _count => INTEGER

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.

=item _join => STRING

Which STRING to be used when an ARRAY is being filled-in.

=item _prepend => STRING

Text as STRING prepended before FORMAT, without interpolation.

=back

=item B<sprintp>(FORMAT, LIST, PAIRS)

Where L<sprinti()|String::Print/"FUNCTIONS"> uses named parameters --especially useful when the
strings need translation-- this function stays close to the standard
C<sprintf()>.  All features of POSIX formats are supported.  This
should say enough: you can use C<%3$0#5.*d>, if you like.

It may be useful to know that the positional FORMAT is rewritten and
then fed into L<sprinti()|String::Print/"FUNCTIONS">.  Be careful with the length of the LIST:
superfluous parameter PAIRS are passed along to C<sprinti()>, and
should only contain "specials".

example: 

  # positional parameters
  my $x = sprintp "dumpfiles: %s\n", \@dumpfiles
     , _join => ':';

  # rewriten and processed as
  my $x = sprinti "dumpfiles: {filenames}\n"
     , filenames => \@dumpfiles, _join => ':';

=back

=head1 DETAILS

=head2 Why C<printi()>, not C<printf()>?

The C<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?

=over 4

=item translating

C<printf()> uses positional values, where L<printi()|String::Print/"FUNCTIONS"> 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
L<printp()|String::Print/"FUNCTIONS">

=item pluggable serializers

C<printi()> supports serialization for specific data-types: how to
interpolate C<undef>, HASHes, etc.

=item pluggable modifiers

Especially useful in context of translations, the FORMAT string may
contain (language specific) helpers to insert the values correctly.

=item correct use of utf8

Sized string formatting in C<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 L<printi()|String::Print/"FUNCTIONS"> implementation will use
Unicode::GCString for correct behavior.

=back

=head2 Three components

To fill-in a FORMAT, three clearly separated components play a role.

=over 4

=item modifiers

How to change the provided values, for instance to hide locale
differences.

=item serializer

How to represent (modified) the values correctly, for instance C<undef>
and ARRAYs.

=item conversion

The standard UNIX conversion rules, like C<%d>.  One conversion rule
has been changed 'c', for unicode correct behavior.

=back

Simplified:

  # sprinti() replaces {$key$modifiers$conversion} by
  $conversion->($serializer->($modifiers->($arg{$key})))

  # sprintp() replaces %pos{$modifiers}$conversion by
  $conversion->($serializer->($modifiers->($arg[$pos])))

=head2 Interpolation, the serialization of variables

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 C<_>.  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 C<undef>.

=over 4

=item CODE

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:

=item strings

Simple scalar values are interpolated "as is"

=item ARRAY

All members will be interpolated with C<,␣> between the elements.
Alternatively (maybe nicer), you can pass an interpolation parameter
via the C<_join> OPTION.

=item HASH

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.

=item Objects

With the C<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;
  }

=back

=head2 Interpolation: Modifiers

Modifiers are used to change the value to be inserted, before the characters
get interpolated in the line.

=head3 Modifiers: unix format

Next to the name, you can specify a format code.  With (gnu) C<gettext()>,
you often see this:

 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 C<Log::Report>, above syntaxes do work, but you can also do:

 # with optional translations
 print __x"approx pi: {pi%.6f}\n", pi => PI;

The base for C<__x()> is the L<printi()|String::Print/"FUNCTIONS"> provided by this module. Internally,
it will call C<printi> to fill in parameters:

 printi   "approx pi: {pi%.6f}\n", pi => PI;

Another example:

 printi "{perms} {links%2d} {user%-8s} {size%10d} {fn%c}\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 L<printp()|String::Print/"FUNCTIONS"> syntax, shorter but less maintainable:

 printp "%s %2d %-8s 10d %s\n"
    , '-rw-r--r--', 7, 'me', '12345', $filename;

=head3 Modifiers: unix format improvements

The POSIX C<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.  C<printi()> does not use characters but
"grapheme clusters" via Unicode::GCString.  Now, also composed
characters do work correctly.

Additionally, you can use the B<new 'c' 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
'c' is probably the better choice over 's'.

=head3 Modifiers: private modifiers

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 PND", $value/1.23+0.0001)
    :                 'ERROR';
  }

Now:

  printi "price: {p€}", p => $pi;   # price: 3.14 EUR
  printi "price: {p₤}", p => $pi;   # price: 2.55 PND

This is very useful in the translation context, where the translator
can specify abstract formatting.  Using L<printp()|String::Print/"FUNCTIONS"> 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 PND

Another example.  Now, we want to add timestamps.  In this case, we
decide for modifier names in C<\w>, so we need a blank to separate
the paramter from the modifer.

  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

=head3 Modifiers: stacking

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<

=head2 Compared to other modules on CPAN

There are a few more modules on CPAN which extend the functionality
of C<printf()>.  To name a few:
F<http://search.cpan.org/~darren/String-Format|String::Format>,
F<http://http://search.cpan.org/~rjbs/String-Errf|String::Errf>,
F<http://http://search.cpan.org/~rjbs/String-Formatter|String::Formatter>,
F<http://search.cpan.org/~shlomif/Text-Sprintf-Named|Text::Sprintf::Named>,
F<http://search.cpan.org/~gfuji/Acme-StringFormat|Acme::StringFormat>,
F<http://search.cpan.org/~sharyanto/Text-sprintfn|Text::sprintf>,
F<http://search.cpan.org/~frew/Log-Sprintf|Log::Sprintf>, and
F<http://search.cpan.org/~bartl/String-Sprintf|String::Sprintf>.
They are all slightly different.

When the C<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 C<String::Print> cleanly separates the roles of serializers,
modifiers, and conversions.

=head1 SEE ALSO

This module is part of String-Print distribution version 0.11,
built on April 16, 2013. Website: F<http://perl.overmeer.net/log-report/>

=head1 LICENSE

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 F<http://www.perl.com/perl/misc/Artistic.html>

