1String::Formatter::CookUbsoeork(C3o)ntributed Perl DocumSetnrtiantgi:o:nFormatter::Cookbook(3)
2
3
4

NAME

6       String::Formatter::Cookbook - ways to put String::Formatter to use
7

VERSION

9       version 1.234
10

OVERVIEW

12       String::Formatter is a pretty simple system for building formatting
13       routines, but it can be hard to get started without an idea of the sort
14       of things that are possible.
15

PERL VERSION

17       This library should run on perls released even a long time ago.  It
18       should work on any version of perl released in the last five years.
19
20       Although it may work on older versions of perl, no guarantee is made
21       that the minimum required version will not be increased.  The version
22       may be increased for any reason, and there is no promise that patches
23       will be accepted to lower the minimum required perl.
24

BASIC RECIPES

26   constants only
27       The simplest stringf interface you can provide is one that just formats
28       constant strings, allowing the user to put them inside other fixed
29       strings with alignment:
30
31         use String::Formatter stringf => {
32           input_processor => 'forbid_input',
33           codes => {
34             a => 'apples',
35             b => 'bananas',
36             w => 'watermelon',
37           },
38         };
39
40         print stringf('I eat %a and %b but never %w.');
41
42         # Output:
43         # I eat apples and bananas but never watermelon.
44
45       If the user tries to parameterize the string by passing arguments after
46       the format string, an exception will be raised.
47
48   sprintf-like conversions
49       Another common pattern is to create a routine that behaves like Perl's
50       "sprintf", but with a different set of conversion routines.  (It will
51       also almost certainly have much simpler semantics than Perl's wildly
52       complex behavior.)
53
54         use String::Formatter stringf => {
55           codes => {
56             s => sub { $_ },     # string itself
57             l => sub { length }, # length of input string
58             e => sub { /[^\x00-\x7F]/ ? '8bit' : '7bit' }, # ascii-safeness
59           },
60         };
61
62         print stringf(
63           "My name is %s.  I am about %l feet tall.  I use an %e alphabet.\n",
64           'Ricardo',
65           'ffffff',
66           'abcchdefghijklllmnñopqrrrstuvwxyz',
67         );
68
69         # Output:
70         # My name is Ricardo.  I am about 6 feet tall.  I use an 8bit alphabet.
71
72       Warning: The behavior of positional string replacement when the
73       conversion codes mix constant strings and code references is currently
74       poorly nailed-down.  Do not rely on it yet.
75
76   named conversions
77       This recipe acts a bit like Python's format operator when given a
78       dictionary.  Rather than matching format code position with input
79       ordering, inputs can be chosen by name.
80
81         use String::Formatter stringf => {
82           input_processor => 'require_named_input',
83           string_replacer => 'named_replace',
84
85           codes => {
86             s => sub { $_ },     # string itself
87             l => sub { length }, # length of input string
88             e => sub { /[^\x00-\x7F]/ ? '8bit' : '7bit' }, # ascii-safeness
89           },
90         };
91
92         print stringf(
93           "My %{which}s name is %{name}s.  My name is %{name}l letters long.",
94           {
95             which => 'first',
96             name  => 'Marvin',
97           },
98         );
99
100         # Output:
101         # My first name is Marvin.  My name is 6 letters long.
102
103       Because this is a useful recipe, there is a shorthand for it:
104
105         use String::Formatter named_stringf => {
106           codes => {
107             s => sub { $_ },     # string itself
108             l => sub { length }, # length of input string
109             e => sub { /[^\x00-\x7F]/ ? '8bit' : '7bit' }, # ascii-safeness
110           },
111         };
112
113   method calls
114       Some objects provide methods to stringify them flexibly.  For example,
115       many objects that represent timestamps allow you to call "strftime" or
116       something similar.  The "method_replace" string replacer comes in handy
117       here:
118
119         use String::Formatter stringf => {
120           input_processor => 'require_single_input',
121           string_replacer => 'method_replace',
122
123           codes => {
124             f => 'strftime',
125             c => 'format_cldr',
126             s => sub { "$_[0]" },
127           },
128         };
129
130         print stringf(
131           "%{%Y-%m-%d}f is also %{yyyy-MM-dd}c.  Default string is %s.",
132           DateTime->now,
133         );
134
135         # Output:
136         # 2009-11-17 is also 2009-11-17.  Default string is 2009-11-17T15:35:11.
137
138       This recipe is available as the export "method_stringf":
139
140         use String::Formatter method_stringf => {
141           codes => {
142             f => 'strftime',
143             c => 'format_cldr',
144             s => sub { "$_[0]" },
145           },
146         };
147
148       You can easily use this to implement an actual stringf-like method:
149
150         package MyClass;
151
152         use String::Formatter method_stringf => {
153           -as => '_stringf',
154           codes => {
155             f => 'strftime',
156             c => 'format_cldr',
157             s => sub { "$_[0]" },
158           },
159         };
160
161         sub format {
162           my ($self, $format) = @_;
163           return _stringf($format, $self);
164         }
165

AUTHORS

167       •   Ricardo Signes <rjbs@semiotic.systems>
168
169       •   Darren Chamberlain <darren@cpan.org>
170

172       This software is Copyright (c) 2021 by Ricardo Signes <rjbs@cpan.org>.
173
174       This is free software, licensed under:
175
176         The GNU General Public License, Version 2, June 1991
177
178
179
180perl v5.36.0                      2022-07-22    String::Formatter::Cookbook(3)
Impressum