1String::Errf(3)       User Contributed Perl Documentation      String::Errf(3)
2
3
4

NAME

6       String::Errf - a simple sprintf-like dialect
7

VERSION

9       version 0.009
10

SYNOPSIS

12         use String::Errf qw(errf);
13
14         print errf "This process was started at %{start}t with %{args;argument}n.\n",
15           { start => $^T, args => 0 + @ARGV };
16
17       ...might print something like:
18
19         This process was started at 2010-10-17 14:05:29 with 0 arguments.
20

DESCRIPTION

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

PERL VERSION

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

DIFFERENCES FROM SPRINTF

38       The data passed to "errf" should be organized in a single hashref, not
39       a list.
40
41       Formatting codes require named parameters, and the available codes are
42       different.  See "FORMATTING CODES" below.
43
44       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
48   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
55         # Very lax; undefs always turn into the same string:
56         use String::Errf errf => { on_undef => sub { '(undef)' } };
57
58         # Strict; undefs are never valid:
59         use String::Errf errf => { on_undef => sub {
60           Carp::croak("undef passed to $_[1]{literal}") } };
61         } };
62
63   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
70         errf "The current time in %{tz}s is %{now;local}t.", {
71           tz  => $ENV{TZ},
72           now => time,
73         };
74
75       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
81       The specific codes and their arguments are:
82
83       s for string
84
85       The "s" format code is for any string, and takes no arguments.  It just
86       includes the named item from the input data.
87
88         errf "%{name}s", { name => 'John Smith' }; # returns "John Smith"
89
90       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
94       i for integer
95
96       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
101         errf "%{x}i",    { x => 10 }; # returns "10"
102         errf "%{x;+}i",  { x => 10 }; # returns "+10"
103
104         errf "%{x;prefix=+}i",  { x => 10 }; # returns "+10"
105
106       The rounding behavior for non-integer values is not currently
107       specified.
108
109       f for float (or fractional)
110
111       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
117         errf "%{x}f",     { x => 10.1234 }; # returns "10";
118         errf "%{x;+}f",   { x => 10.1234 }; # returns "+10";
119
120         errf "%{x;.2}f",  { x => 10.1234 }; # returns  "10.12";
121         errf "%{x;+.2}f", { x => 10.1234 }; # returns "+10.12";
122
123         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
126       t for time
127
128       The "t" format code is used to format timestamps provided in epoch
129       seconds.  It can be given two arguments: "type" and "tz".
130
131       "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
136       The compact form is just "type" alone.
137
138         # Assuming our local time zone is America/New_York...
139
140         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
145         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
150       n and N for numbered
151
152       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
157       If the value being formatted is 1, the singular word is used.
158       Otherwise, the plural form is used.
159
160         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
164         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
168       If "N" is used instead of "n", the number will not be included, only
169       the chosen word.
170
171         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
175         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
179       The compact form may take any of the following forms:
180
181         word          - equivalent to singular=word
182
183         word+suffix   - equivalent to singular=word;plural=wordsuffix
184
185         word1/word2   - equivalent to singular=word;plural=word2
186
187       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
191
192

AUTHOR

194       Ricardo Signes <cpan@semiotic.systems>
195

CONTRIBUTORS

197       •   Karen Etheridge <ether@cpan.org>
198
199       •   Pedro Melo <melo@simplicidade.org>
200
201       •   Ricardo Signes <rjbs@semiotic.systems>
202
204       This software is copyright (c) 2022 by Ricardo Signes.
205
206       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.
208
209
210
211perl v5.38.0                      2023-07-21                   String::Errf(3)
Impressum