1NAME
2 String::Format - sprintf-like string formatting capabilities with
3 arbitrary format definitions
4
5ABSTRACT
6 String::Format allows for sprintf-style formatting capabilities with
7 arbitrary format definitions
8
9SYNOPSIS
10 use String::Format;
11
12 my %fruit = (
13 'a' => "apples",
14 'b' => "bannanas",
15 'g' => "grapefruits",
16 'm' => "melons",
17 'w' => "watermelons",
18 );
19
20 my $format = "I like %a, %b, and %g, but not %m or %w.";
21
22 print stringf($format, %fruit);
23
24 # prints:
25 # I like apples, bannanas, and grapefruits, but not melons or watermelons.
26
27DESCRIPTION
28 String::Format lets you define arbitrary printf-like format sequences to
29 be expanded. This module would be most useful in configuration files and
30 reporting tools, where the results of a query need to be formatted in a
31 particular way. It was inspired by mutt's index_format and related
32 directives (see
33 <URL:http://www.mutt.org/doc/manual/manual-6.html#index_format>).
34
35FUNCTIONS
36 stringf
37 String::Format exports a single function called stringf. stringf takes
38 two arguments: a format string (see FORMAT STRINGS, below) and a
39 reference to a hash of name => value pairs. These name => value pairs
40 are what will be expanded in the format string.
41
42FORMAT STRINGS
43 Format strings must match the following regular expression:
44
45 qr/
46 (% # leading '%'
47 (-)? # left-align, rather than right
48 (\d*)? # (optional) minimum field width
49 (?:\.(\d*))? # (optional) maximum field width
50 ({.*?})? # (optional) stuff inside
51 (\S) # actual format character
52 )/x;
53
54 If the escape character specified does not exist in %args, then the
55 original string is used. The alignment, minimum width, and maximum width
56 options function identically to how they are defined in sprintf(3) (any
57 variation is a bug, and should be reported).
58
59 Note that Perl's sprintf definition is a little more liberal than the
60 above regex; the deviations were intentional, and all deal with numeric
61 formatting (the #, 0, and + leaders were specifically left out).
62
63 The value attached to the key can be a scalar value or a subroutine
64 reference; if it is a subroutine reference, then anything between the
65 '{' and '}' ($5 in the above regex) will be passed as $_[0] to the
66 subroutine reference. This allows for entries such as this:
67
68 %args = (
69 d => sub { POSIX::strftime($_[0], localtime) },
70 );
71
72 Which can be invoked with this format string:
73
74 "It is %{%M:%S}d right now, on %{%A, %B %e}d."
75
76 And result in (for example):
77
78 It is 17:45 right now, on Monday, February 4.
79
80 Note that since the string is passed unmolested to the subroutine
81 reference, and strftime would Do The Right Thing with this data, the
82 above format string could be written as:
83
84 "It is %{%M:%S right now, on %A, %B %e}d."
85
86 By default, the formats 'n', 't', and '%' are defined to be a newline,
87 tab, and '%', respectively, if they are not already defined in the
88 hashref of arguments that gets passed it. So we can add carriage returns
89 simply:
90
91 "It is %{%M:%S right now, on %A, %B %e}d.%n"
92
93 Because of how the string is parsed, the normal "\n" and "\t" are turned
94 into two characters each, and are not treated as a newline and tab. This
95 is a bug.
96
97FACTORY METHOD
98 String::Format also supports a class method, named stringfactory, which
99 will return reference to a "primed" subroutine. stringfatory should be
100 passed a reference to a hash of value; the returned subroutine will use
101 these values as the %args hash.
102
103 my $self = Some::Groovy::Package->new($$, $<, $^T);
104 my %formats = (
105 'i' => sub { $self->id },
106 'd' => sub { $self->date },
107 's' => sub { $self->subject },
108 'b' => sub { $self->body },
109 );
110 my $index_format = String::Format->stringfactory(\%formats);
111
112 print $index_format->($format1);
113 print $index_format->($format2);
114
115 This subroutine reference can be assigned to a local symbol table entry,
116 and called normally, of course:
117
118 *reformat = String::Format->stringfactory(\%formats);
119
120 my $reformed = reformat($format_string);
121
122LICENSE
123 "String::Format" is free software; you can redistribute it and/or modify
124 it under the terms of the GNU General Public License as published by the
125 Free Software Foundation; version 2.
126
127AUTHOR
128 darren chamberlain <darren@cpan.org>
129
130