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

NAME

6       String::Format - sprintf-like string formatting capabilities with arbi‐
7       trary format definitions
8

ABSTRACT

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

SYNOPSIS

14         # In a script invoked as:
15         # script.pl -f "I like %a, %b, and %g, but not %m or %w."
16
17         use String::Format;
18         use Getopt::Std;
19
20         my %fruit = (
21               'a' => "apples",
22               'b' => "bannanas",
23               'g' => "grapefruits",
24               'm' => "melons",
25               'w' => "watermelons",
26         );
27
28         use vars qw($opt_f);
29         getopt("f");
30
31         print stringf($opt_f, %fruit);
32
33         # prints:
34         # I like apples, bannanas, and grapefruits, but not melons or watermelons.
35

DESCRIPTION

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

FUNCTIONS

45       stringf
46
47       String::Format exports a single function called stringf.  stringf takes
48       two arguments:  a format string (see FORMAT STRINGS, below) and a ref‐
49       erence to a hash of name => value pairs.  These name => value pairs are
50       what will be expanded in the format string.
51

FORMAT STRINGS

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

FACTORY METHOD

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

AUTHOR

133       darren chamberlain <darren@cpan.org>
134
135
136
137perl v5.8.8                       2005-12-22                         Format(3)