1String::Errf(3) User Contributed Perl Documentation String::Errf(3)
2
6 String::Errf - a simple sprintf-like dialect
7
9 version 0.009
10
12 use String::Errf qw(errf);
13 print errf "This process was started at %{start}t with %{args;argument}n.\n",
15 { start => $^T, args => 0 + @ARGV };
16 ...might print something like:
18 This process was started at 2010-10-17 14:05:29 with 0 arguments.
20
22 String::Errf provides "errf", a simple string formatter that works
23 something like "sprintf". It is implemented using String::Formatter
24 and Sub::Exporter. Their documentation may be useful in understanding
25 or extending String::Errf. The "errf" subroutine is only available
26 when imported. Calling String::Errf::errf will not do what you want.
27
29 This library should run on perls released even a long time ago. It
30 should work on any version of perl released in the last five years.
31 Although it may work on older versions of perl, no guarantee is made
33 that the minimum required version will not be increased. The version
34 may be increased for any reason, and there is no promise that patches
35 will be accepted to lower the minimum required perl.
36
38 The data passed to "errf" should be organized in a single hashref, not
39 a list.
40 Formatting codes require named parameters, and the available codes are
42 different. See "FORMATTING CODES" below.
43 As with most String::Formatter formatters, "%" is not a format code.
45 If you want a literal "%", do not put anything between the two percent
46 signs, just write "%%".
47 UNDEF HANDLING
49 By default, formatting codes tend to treat "undef" like Perl does:
50 coercing it to an empty string or zero. This was a bad initial
51 decision and will probably change. A "on_undef" handler can be
52 provided when importing "errf" to setup a callback for how undefs
53 should be handled. These two possibilities seem useful:
54 # Very lax; undefs always turn into the same string:
56 use String::Errf errf => { on_undef => sub { '(undef)' } };
57 # Strict; undefs are never valid:
59 use String::Errf errf => { on_undef => sub {
60 Carp::croak("undef passed to $_[1]{literal}") } };
61 } };
62 FORMATTING CODES
64 "errf" formatting codes require a set of arguments between the "%" and
65 the formatting code letter. These arguments are placed in curly braces
66 and separated by semicolons. The first argument is the name of the
67 data to look for in the format data. For example, this is a valid use
68 of "errf":
69 errf "The current time in %{tz}s is %{now;local}t.", {
71 tz => $ENV{TZ},
72 now => time,
73 };
74 The second argument, if present, may be a compact form for multiple
76 named arguments. The rest of the arguments will be named values in the
77 form "name=value". The examples below should help clarify how
78 arguments are passed. When an argument appears in both a compact and
79 named form, the named form trumps the compact form.
80 The specific codes and their arguments are:
82 s for string
84 The "s" format code is for any string, and takes no arguments. It just
86 includes the named item from the input data.
87 errf "%{name}s", { name => 'John Smith' }; # returns "John Smith"
89 Remember, "errf" does not have any of the left- or right-padding
91 formatting that "sprintf" provides. It is not meant for building
92 tables, only strings.
93 i for integer
95 The "i" format code is used for integers. It takes one optional
97 argument, "prefix", which defaults to the empty string. "prefix" may
98 be given as the compact argument, standing alone. "prefix" is used to
99 prefix non-negative integers. It may only be a plus sign.
100 errf "%{x}i", { x => 10 }; # returns "10"
102 errf "%{x;+}i", { x => 10 }; # returns "+10"
103 errf "%{x;prefix=+}i", { x => 10 }; # returns "+10"
105 The rounding behavior for non-integer values is not currently
107 specified.
108 f for float (or fractional)
110 The "f" format code is for numbers with sub-integer precision. It
112 works just like "i", but adds a "precision" argument which specifies
113 how many decimal places of precision to display. The compact argument
114 may be just the prefix or the prefix followed by a period followed by
115 the precision.
116 errf "%{x}f", { x => 10.1234 }; # returns "10";
118 errf "%{x;+}f", { x => 10.1234 }; # returns "+10";
119 errf "%{x;.2}f", { x => 10.1234 }; # returns "10.12";
121 errf "%{x;+.2}f", { x => 10.1234 }; # returns "+10.12";
122 errf "%{x;precision=.2}f", { x => 10.1234 }; # returns "10.12";
124 errf "%{x;prefix=+;precision=.2}f", { x => 10.1234 }; # returns "+10.12";
125 t for time
127 The "t" format code is used to format timestamps provided in epoch
129 seconds. It can be given two arguments: "type" and "tz".
130 "type" can be either date, time, or datetime, and indicates what part
132 of the timestamp should be displayed. The default is datetime. "tz"
133 requests that the timestamp be displayed in either UTC or the local
134 time zone. The default is local.
135 The compact form is just "type" alone.
137 # Assuming our local time zone is America/New_York...
139 errf "%{x}t", { x => 1280530906 }; # "2010-07-30 19:01:46"
141 errf "%{x;type=date}t", { x => 1280530906 }; # "2010-07-30"
142 errf "%{x;type=time}t", { x => 1280530906 }; # "19:01:46"
143 errf "%{x;type=datetime}t", { x => 1280530906 }; # "2010-07-30 19:01:46"
144 errf "%{x;tz=UTC}t", { x => 1280530906 }; # "2010-07-30 23:01:46 UTC"
146 errf "%{x;tz=UTC;type=date}t", { x => 1280530906 }; # "2010-07-30 UTC"
147 errf "%{x;tz=UTC;type=time}t", { x => 1280530906 }; # "23:01:46 UTC"
148 errf "%{x;tz=UTC;type=datetime}t", { x => 1280530906 }; # "2010-07-30 23:01:46 UTC"
149 n and N for numbered
151 The "n" and "N" format codes are for picking words based on number. It
153 takes two of its own arguments, "singular" and "plural", as well as
154 "prefix" and "precision" which may be used for formatting the number
155 itself.
156 If the value being formatted is 1, the singular word is used.
158 Otherwise, the plural form is used.
159 errf "%{x;singular=dog;plural=dogs}n", { x => 0 }; # 0 dogs
161 errf "%{x;singular=dog;plural=dogs}n", { x => 1 }; # 1 dog
162 errf "%{x;singular=dog;plural=dogs}n", { x => 2 }; # 2 dogs
163 errf "%{x;singular=dog;plural=dogs}n", { x => 1.4 }; # 1.4 dogs
165 errf "%{x;singular=dog;plural=dogs;precision=1}n", { x => 1.4 }; # 1.4 dogs
166 errf "%{x;singular=dog;plural=dogs;precision=0}n", { x => 1.4 }; # 1 dog
167 If "N" is used instead of "n", the number will not be included, only
169 the chosen word.
170 errf "%{x;singular=is;plural=are}N", { x => 0 }; # are
172 errf "%{x;singular=is;plural=are}N", { x => 1 }; # is
173 errf "%{x;singular=is;plural=are}N", { x => 2 }; # are
174 errf "%{x;singular=is;plural=are}N", { x => 1.4 }; # 1.4 are
176 errf "%{x;singular=is;plural=are;precision=1}N", { x => 1.4 }; # 1.4 are
177 errf "%{x;singular=is;plural=are;precision=0}N", { x => 1.4 }; # 1 is
178 The compact form may take any of the following forms:
180 word - equivalent to singular=word
182 word+suffix - equivalent to singular=word;plural=wordsuffix
184 word1/word2 - equivalent to singular=word;plural=word2
186 If no singular form is given, an exception is thrown. If no plural
188 form is given, one will be generated according to some basic rules of
189 English noun orthography.
190
194 Ricardo Signes <cpan@semiotic.systems>
195
197 • Karen Etheridge <ether@cpan.org>
198 • Pedro Melo <melo@simplicidade.org>
200 • Ricardo Signes <rjbs@semiotic.systems>
202
204 This software is copyright (c) 2022 by Ricardo Signes.
205 This is free software; you can redistribute it and/or modify it under
207 the same terms as the Perl 5 programming language system itself.
208perl v5.36.0 2023-01-20 String::Errf(3)