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         # 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
40       formatted in a particular way.  It was inspired by mutt's index_format
41       and related directives (see
42       <URL:http://www.mutt.org/doc/manual/manual-6.html#index_format>).
43

FUNCTIONS

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

FORMAT STRINGS

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

FACTORY METHOD

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

AUTHOR

132       darren chamberlain <darren@cpan.org>
133
134
135
136perl v5.10.1                      2009-03-27                         Format(3)