1String::Errf(3) User Contributed Perl Documentation String::Errf(3)
2
6 String::Errf - a simple sprintf-like dialect
7
9 version 0.008
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 The data passed to "errf" should be organized in a single hashref, not
30 a list.
31 Formatting codes require named parameters, and the available codes are
33 different. See "FORMATTING CODES" below.
34 As with most String::Formatter formatters, "%" is not a format code.
36 If you want a literal "%", do not put anything between the two percent
37 signs, just write "%%".
38 UNDEF HANDLING
40 By default, formatting codes tend to treat "undef" like Perl does:
41 coercing it to an empty string or zero. This was a bad initial
42 decision and will probably change. A "on_undef" handler can be
43 provided when importing "errf" to setup a callback for how undefs
44 should be handled. These two possibilities seem useful:
45 # Very lax; undefs always turn into the same string:
47 use String::Errf errf => { on_undef => sub { '(undef)' } };
48 # Strict; undefs are never valid:
50 use String::Errf errf => { on_undef => sub {
51 Carp::croak("undef passed to $_[1]{literal}") } };
52 } };
53 FORMATTING CODES
55 "errf" formatting codes require a set of arguments between the "%" and
56 the formatting code letter. These arguments are placed in curly braces
57 and separated by semicolons. The first argument is the name of the
58 data to look for in the format data. For example, this is a valid use
59 of "errf":
60 errf "The current time in %{tz}s is %{now;local}t.", {
62 tz => $ENV{TZ},
63 now => time,
64 };
65 The second argument, if present, may be a compact form for multiple
67 named arguments. The rest of the arguments will be named values in the
68 form "name=value". The examples below should help clarify how
69 arguments are passed. When an argument appears in both a compact and
70 named form, the named form trumps the compact form.
71 The specific codes and their arguments are:
73 s for string
75 The "s" format code is for any string, and takes no arguments. It just
77 includes the named item from the input data.
78 errf "%{name}s", { name => 'John Smith' }; # returns "John Smith"
80 Remember, "errf" does not have any of the left- or right-padding
82 formatting that "sprintf" provides. It is not meant for building
83 tables, only strings.
84 i for integer
86 The "i" format code is used for integers. It takes one optional
88 argument, "prefix", which defaults to the empty string. "prefix" may
89 be given as the compact argument, standing alone. "prefix" is used to
90 prefix non-negative integers. It may only be a plus sign.
91 errf "%{x}i", { x => 10 }; # returns "10"
93 errf "%{x;+}i", { x => 10 }; # returns "+10"
94 errf "%{x;prefix=+}i", { x => 10 }; # returns "+10"
96 The rounding behavior for non-integer values is not currently
98 specified.
99 f for float (or fractional)
101 The "f" format code is for numbers with sub-integer precision. It
103 works just like "i", but adds a "precision" argument which specifies
104 how many decimal places of precision to display. The compact argument
105 may be just the prefix or the prefix followed by a period followed by
106 the precision.
107 errf "%{x}f", { x => 10.1234 }; # returns "10";
109 errf "%{x;+}f", { x => 10.1234 }; # returns "+10";
110 errf "%{x;.2}f", { x => 10.1234 }; # returns "10.12";
112 errf "%{x;+.2}f", { x => 10.1234 }; # returns "+10.12";
113 errf "%{x;precision=.2}f", { x => 10.1234 }; # returns "10.12";
115 errf "%{x;prefix=+;precision=.2}f", { x => 10.1234 }; # returns "+10.12";
116 t for time
118 The "t" format code is used to format timestamps provided in epoch
120 seconds. It can be given two arguments: "type" and "tz".
121 "type" can be either date, time, or datetime, and indicates what part
123 of the timestamp should be displayed. The default is datetime. "tz"
124 requests that the timestamp be displayed in either UTC or the local
125 time zone. The default is local.
126 The compact form is just "type" alone.
128 # Assuming our local time zone is America/New_York...
130 errf "%{x}t", { x => 1280530906 }; # "2010-07-30 19:01:46"
132 errf "%{x;type=date}t", { x => 1280530906 }; # "2010-07-30"
133 errf "%{x;type=time}t", { x => 1280530906 }; # "19:01:46"
134 errf "%{x;type=datetime}t", { x => 1280530906 }; # "2010-07-30 19:01:46"
135 errf "%{x;tz=UTC}t", { x => 1280530906 }; # "2010-07-30 23:01:46 UTC"
137 errf "%{x;tz=UTC;type=date}t", { x => 1280530906 }; # "2010-07-30 UTC"
138 errf "%{x;tz=UTC;type=time}t", { x => 1280530906 }; # "23:01:46 UTC"
139 errf "%{x;tz=UTC;type=datetime}t", { x => 1280530906 }; # "2010-07-30 23:01:46 UTC"
140 n and N for numbered
142 The "n" and "N" format codes are for picking words based on number. It
144 takes two of its own arguments, "singular" and "plural", as well as
145 "prefix" and "precision" which may be used for formatting the number
146 itself.
147 If the value being formatted is 1, the singular word is used.
149 Otherwise, the plural form is used.
150 errf "%{x;singular=dog;plural=dogs}n", { x => 0 }; # 0 dogs
152 errf "%{x;singular=dog;plural=dogs}n", { x => 1 }; # 1 dog
153 errf "%{x;singular=dog;plural=dogs}n", { x => 2 }; # 2 dogs
154 errf "%{x;singular=dog;plural=dogs}n", { x => 1.4 }; # 1.4 dogs
156 errf "%{x;singular=dog;plural=dogs;precision=1}n", { x => 1.4 }; # 1.4 dogs
157 errf "%{x;singular=dog;plural=dogs;precision=0}n", { x => 1.4 }; # 1 dog
158 If "N" is used instead of "n", the number will not be included, only
160 the chosen word.
161 errf "%{x;singular=is;plural=are}N", { x => 0 }; # are
163 errf "%{x;singular=is;plural=are}N", { x => 1 }; # is
164 errf "%{x;singular=is;plural=are}N", { x => 2 }; # are
165 errf "%{x;singular=is;plural=are}N", { x => 1.4 }; # 1.4 are
167 errf "%{x;singular=is;plural=are;precision=1}N", { x => 1.4 }; # 1.4 are
168 errf "%{x;singular=is;plural=are;precision=0}N", { x => 1.4 }; # 1 is
169 The compact form may take any of the following forms:
171 word - equivalent to singular=word
173 word+suffix - equivalent to singular=word;plural=wordsuffix
175 word1/word2 - equivalent to singular=word;plural=word2
177 If no singular form is given, an exception is thrown. If no plural
179 form is given, one will be generated according to some basic rules of
180 English noun orthography.
181
185 Ricardo Signes <rjbs@cpan.org>
186
188 • Karen Etheridge <ether@cpan.org>
189 • Pedro Melo <melo@simplicidade.org>
191
193 This software is copyright (c) 2016 by Ricardo Signes.
194 This is free software; you can redistribute it and/or modify it under
196 the same terms as the Perl 5 programming language system itself.
197perl v5.34.0 2022-01-21 String::Errf(3)