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 0.102084
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

BASIC RECIPES

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

AUTHORS

158       ·   Ricardo Signes <rjbs@cpan.org>
159
160       ·   Darren Chamberlain <darren@cpan.org>
161

163       This software is Copyright (c) 2013 by Ricardo Signes <rjbs@cpan.org>.
164
165       This is free software, licensed under:
166
167         The GNU General Public License, Version 2, June 1991
168
169
170
171perl v5.30.0                      2019-07-26    String::Formatter::Cookbook(3)
Impressum