1Format(3)             User Contributed Perl Documentation            Format(3)
2
3
4

NAME

6       String::Format - sprintf-like string formatting capabilities with
7       arbitrary format definitions
8

ABSTRACT

10       String::Format allows for sprintf-style formatting capabilities with
11       arbitrary format definitions
12

SYNOPSIS

14         use String::Format;
15
16         my %fruit = (
17               'a' => "apples",
18               'b' => "bannanas",
19               'g' => "grapefruits",
20               'm' => "melons",
21               'w' => "watermelons",
22         );
23
24         my $format = "I like %a, %b, and %g, but not %m or %w.";
25
26         print stringf($format, %fruit);
27
28         # prints:
29         # I like apples, bannanas, and grapefruits, but not melons or watermelons.
30

DESCRIPTION

32       String::Format lets you define arbitrary printf-like format sequences
33       to be expanded.  This module would be most useful in configuration
34       files and reporting tools, where the results of a query need to be
35       formatted in a particular way.  It was inspired by mutt's index_format
36       and related directives (see
37       <URL:http://www.mutt.org/doc/manual/manual-6.html#index_format>).
38

FUNCTIONS

40   stringf
41       String::Format exports a single function called stringf.  stringf takes
42       two arguments:  a format string (see FORMAT STRINGS, below) and a
43       reference to a hash of name => value pairs.  These name => value pairs
44       are what will be expanded in the format string.
45

FORMAT STRINGS

47       Format strings must match the following regular expression:
48
49         qr/
50            (%             # leading '%'
51             (-)?          # left-align, rather than right
52             (\d*)?        # (optional) minimum field width
53             (?:\.(\d*))?  # (optional) maximum field width
54             ({.*?})?      # (optional) stuff inside
55             (\S)          # actual format character
56            )/x;
57
58       If the escape character specified does not exist in %args, then the
59       original string is used.  The alignment, minimum width, and maximum
60       width options function identically to how they are defined in
61       sprintf(3) (any variation is a bug, and should be reported).
62
63       Note that Perl's sprintf definition is a little more liberal than the
64       above regex; the deviations were intentional, and all deal with numeric
65       formatting (the #, 0, and + leaders were specifically left out).
66
67       The value attached to the key can be a scalar value or a subroutine
68       reference; if it is a subroutine reference, then anything between the
69       '{' and '}' ($5 in the above regex) will be passed as $_[0] to the
70       subroutine reference.  This allows for entries such as this:
71
72         %args = (
73             d => sub { POSIX::strftime($_[0], localtime) },
74         );
75
76       Which can be invoked with this format string:
77
78         "It is %{%M:%S}d right now, on %{%A, %B %e}d."
79
80       And result in (for example):
81
82         It is 17:45 right now, on Monday, February 4.
83
84       Note that since the string is passed unmolested to the subroutine
85       reference, and strftime would Do The Right Thing with this data, the
86       above format string could be written as:
87
88         "It is %{%M:%S right now, on %A, %B %e}d."
89
90       By default, the formats 'n', 't', and '%' are defined to be a newline,
91       tab, and '%', respectively, if they are not already defined in the
92       hashref of arguments that gets passed it.  So we can add carriage
93       returns simply:
94
95         "It is %{%M:%S right now, on %A, %B %e}d.%n"
96
97       Because of how the string is parsed, the normal "\n" and "\t" are
98       turned into two characters each, and are not treated as a newline and
99       tab.  This is a bug.
100

FACTORY METHOD

102       String::Format also supports a class method, named stringfactory, which
103       will return reference to a "primed" subroutine.  stringfatory should be
104       passed a reference to a hash of value; the returned subroutine will use
105       these values as the %args hash.
106
107         my $self = Some::Groovy::Package->new($$, $<, $^T);
108         my %formats = (
109               'i' => sub { $self->id      },
110               'd' => sub { $self->date    },
111               's' => sub { $self->subject },
112               'b' => sub { $self->body    },
113         );
114         my $index_format = String::Format->stringfactory(\%formats);
115
116         print $index_format->($format1);
117         print $index_format->($format2);
118
119       This subroutine reference can be assigned to a local symbol table
120       entry, and called normally, of course:
121
122         *reformat = String::Format->stringfactory(\%formats);
123
124         my $reformed = reformat($format_string);
125

LICENSE

127       "String::Format" is free software; you can redistribute it and/or
128       modify it under the terms of the GNU General Public License as
129       published by the Free Software Foundation; version 2.
130

AUTHOR

132       darren chamberlain <darren@cpan.org>
133
134
135
136perl v5.16.3                      2009-05-17                         Format(3)