1String::Errf(3) User Contributed Perl Documentation String::Errf(3)
2
6 String::Errf - a simple sprintf-like dialect
7
9 version 0.006
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.
26
28 The data passed to "errf" should be organized in a single hashref, not
29 a list.
30 Formatting codes require named parameters, and the available codes are
32 different. See "FORMATTING CODES" below.
33 As with most String::Formatter formatters, "%" is not a format code.
35 If you want a literal "%", do not put anything between the two percent
36 signs, just write "%%".
37 FORMATTING CODES
39 "errf" formatting codes require a set of arguments between the "%" and
40 the formatting code letter. These arguments are placed in curly braces
41 and separated by semicolons. The first argument is the name of the
42 data to look for in the format data. For example, this is a valid use
43 of "errf":
44 errf "The current time in %{tz}s is %{now;local}t.", {
46 tz => $ENV{TZ},
47 now => time,
48 };
49 The second argument, if present, may be a compact form for multiple
51 named arguments. The rest of the arguments will be named values in the
52 form "name=value". The examples below should help clarify how
53 arguments are passed. When an argument appears in both a compact and
54 named form, the named form trumps the compact form.
55 The specific codes and their arguments are:
57 s for string
59 The "s" format code is for any string, and takes no arguments. It just
61 includes the named item from the input data.
62 errf "%{name}s", { name => 'John Smith' }; # returns "John Smith"
64 Remember, "errf" does not have any of the left- or right-padding
66 formatting that "sprintf" provides. It is not meant for building
67 tables, only strings.
68 i for integer
70 The "i" format code is used for integers. It takes one optional
72 argument, "prefix", which defaults to the empty string. "prefix" may
73 be given as the compact argument, standing alone. "prefix" is used to
74 prefix non-negative integers. It may only be a plus sign.
75 errf "%{x}i", { x => 10 }; # returns "10"
77 errf "%{x;+}i", { x => 10 }; # returns "+10"
78 errf "%{x;prefix=+}i", { x => 10 }; # returns "+10"
80 The rounding behavior for non-integer values is not currently
82 specified.
83 f for float (or fractional)
85 The "f" format code is for numbers with sub-integer precision. It
87 works just like "i", but adds a "precision" argument which specifies
88 how many decimal places of precision to display. The compact argument
89 may be just the prefix or the prefix followed by a period followed by
90 the precision.
91 errf "%{x}f", { x => 10.1234 }; # returns "10";
93 errf "%{x;+}f", { x => 10.1234 }; # returns "+10";
94 errf "%{x;.2}f", { x => 10.1234 }; # returns "10.12";
96 errf "%{x;+.2}f", { x => 10.1234 }; # returns "+10.12";
97 errf "%{x;precision=.2}f", { x => 10.1234 }; # returns "10.12";
99 errf "%{x;prefix=+;precision=.2}f", { x => 10.1234 }; # returns "+10.12";
100 t for time
102 The "t" format code is used to format timestamps provided in epoch
104 seconds. It can be given two arguments: "type" and "tz".
105 "type" can be either date, time, or datetime, and indicates what part
107 of the timestamp should be displayed. The default is datetime. "tz"
108 requests that the timestamp be displayed in either UTC or the local
109 time zone. The default is local.
110 The compact form is just "type" alone.
112 # Assuming our local time zone is America/New_York...
114 errf "%{x}t", { x => 1280530906 }; # "2010-07-30 19:01:46"
116 errf "%{x;type=date}t", { x => 1280530906 }; # "2010-07-30"
117 errf "%{x;type=time}t", { x => 1280530906 }; # "19:01:46"
118 errf "%{x;type=datetime}t", { x => 1280530906 }; # "2010-07-30 19:01:46"
119 errf "%{x;tz=UTC}t", { x => 1280530906 }; # "2010-07-30 23:01:46 UTC"
121 errf "%{x;tz=UTC;type=date}t", { x => 1280530906 }; # "2010-07-30 UTC"
122 errf "%{x;tz=UTC;type=time}t", { x => 1280530906 }; # "23:01:46 UTC"
123 errf "%{x;tz=UTC;type=datetime}t", { x => 1280530906 }; # "2010-07-30 23:01:46 UTC"
124 n and N for numbered
126 The "n" and "N" format codes are for picking words based on number. It
128 takes two of its own arguments, "singular" and "plural", as well as
129 "prefix" and "precision" which may be used for formatting the number
130 itself.
131 If the value being formatted is 1, the singular word is used.
133 Otherwise, the plural form is used.
134 errf "%{x;singular=dog;plural=dogs}n", { x => 0 }; # 0 dogs
136 errf "%{x;singular=dog;plural=dogs}n", { x => 1 }; # 1 dog
137 errf "%{x;singular=dog;plural=dogs}n", { x => 2 }; # 2 dogs
138 errf "%{x;singular=dog;plural=dogs}n", { x => 1.4 }; # 1.4 dogs
140 errf "%{x;singular=dog;plural=dogs;precision=1}n", { x => 1.4 }; # 1.4 dogs
141 errf "%{x;singular=dog;plural=dogs;precision=0}n", { x => 1.4 }; # 1 dog
142 If "N" is used instead of "n", the number will not be included, only
144 the chosen word.
145 errf "%{x;singular=is;plural=are}N", { x => 0 }; # are
147 errf "%{x;singular=is;plural=are}N", { x => 1 }; # is
148 errf "%{x;singular=is;plural=are}N", { x => 2 }; # are
149 errf "%{x;singular=is;plural=are}N", { x => 1.4 }; # 1.4 are
151 errf "%{x;singular=is;plural=are;precision=1}N", { x => 1.4 }; # 1.4 are
152 errf "%{x;singular=is;plural=are;precision=0}N", { x => 1.4 }; # 1 is
153 The compact form may take any of the following forms:
155 word - equivalent to singular=word
157 word+suffix - equivalent to singular=word;plural=wordsuffix
159 word1/word2 - equivalent to singular=word;plural=word2
161 If no singular form is given, an exception is thrown. If no plural
163 form is given, one will be generated according to some basic rules of
164 English noun orthography.
165
169 Ricardo Signes <rjbs@cpan.org>
170
172 This software is copyright (c) 2010 by Ricardo Signes.
173 This is free software; you can redistribute it and/or modify it under
175 the same terms as the Perl 5 programming language system itself.
176perl v5.12.3 2010-10-29 String::Errf(3)