1NAME
2 Text::sprintfn - Drop-in replacement for sprintf(), with named parameter
3 support
4
5VERSION
6 This document describes version 0.090 of Text::sprintfn (from Perl
7 distribution Text-sprintfn), released on 2019-11-19.
8
9SYNOPSIS
10 use Text::sprintfn; # by default exports sprintfn() and printfn()
11
12 # with no hash, behaves just like printf
13 printfn '<%04d>', 1, 2; # <0001>
14
15 # named parameter
16 printfn '<%(v1)-4d>', {v1=>-2}; # <-2 >
17
18 # mixed named and positional
19 printfn '<%d> <%(v1)d> <%d>', {v1=>1}, 2, 3; # <2> <1> <3>
20
21 # named width
22 printfn "<%(v1)(v2).1f>", {v1=>3, v2=>4}; # < 3>
23
24 # named precision
25 printfn "<%(v1)(v2).(v2)f>", {v1=>3, v2=>4}; # <3.0000>
26
27DESCRIPTION
28 This module provides sprintfn() and printfn(), which are like sprintf()
29 and printf(), with the exception that they support named parameters from
30 a hash.
31
32RATIONALE
33 There exist other CPAN modules for string formatting with named
34 parameter support. Two of such modules are String::Formatter and
35 Text::Sprintf::Named. This module is far simpler to use and retains all
36 of the features of Perl's sprintf() (which we like, or perhaps hate, but
37 nevertheless are familiar with).
38
39 String::Formatter requires you to create a new formatter function first.
40 Text::Sprintf::Named also accordingly requires you to instantiate an
41 object first. There is currently no way to mix named and positional
42 parameters. And you don't get the full features of sprintf().
43
44HOW IT WORKS
45 Text::sprintfn works by converting the format string into sprintf
46 format, i.e. replacing the named parameters like "%(foo)s" to something
47 like "%11$s".
48
49DOWNSIDES
50 Currently the main downside is speed. "sprintfn()" is about 2-3 orders
51 of magnitude slower than "sprintf()". See
52 Bencher::Scenario::Textsprintfn for benchmarks.
53
54TIPS AND TRICKS
55 Common mistake 1
56 Writing
57
58 %(var)
59
60 instead of
61
62 %(var)s
63
64 Common mistake 2 (a bit more newbish)
65 Writing
66
67 sprintfn $format, %hash, ...;
68
69 instead of
70
71 sprintfn $format, \%hash, ...;
72
73 Alternative hashes
74 You have several hashes (%h1, %h2, %h3) which should be consulted for
75 values. You can either merge the hash first:
76
77 %h = (%h1, %h2, %h3); # or use some hash merging module
78 printfn $format, \%h, ...;
79
80 or create a tied hash which can consult hashes for you:
81
82 tie %h, 'Your::Module', \%h1, \%h2, \%h3;
83 printfn $format, \%h, ...;
84
85FUNCTIONS
86 sprintfn $fmt, \%hash, ...
87 If first argument after format is not a hash, sprintfn() will behave
88 exactly like sprintf().
89
90 If hash is given, sprintfn() will look for named parameters in argument
91 and supply the values from the hash. Named parameters are surrounded
92 with parentheses, i.e. "(NAME)". They can occur in format parameter
93 index:
94
95 %2$d # sprintf version, take argument at index 2
96 %(two)d # $ is optional
97 %(two)$d # same
98
99 or in width:
100
101 %-10d # sprintf version, use (minimum) width of 10
102 %-(width)d # like sprintf, but use width from hash key 'width'
103 %(var)-(width)d # format hash key 'var' with width from hash key 'width'
104
105 or in precision:
106
107 %6.2f # sprintf version, use precision of 2 decimals
108 %6.(prec)f # like sprintf, but use precision from hash key 'prec'
109 %(width).(prec)f
110 %(var)(width).(prec)f
111
112 The existence of formats using hash keys will not affect indexes of the
113 rest of the argument, example:
114
115 sprintfn "<%(v1)s> <%2$d> <%d>", {v1=>10}, 0, 1, 2; # "<10> <2> <0>"
116
117 Like sprintf(), if format is unknown/erroneous, it will be printed
118 as-is.
119
120 There is currently no way to escape ")" in named parameter, e.g.:
121
122 %(var containing ))s
123
124 printfn $fmt, ...
125 Equivalent to: print sprintfn($fmt, ...).
126
127HOMEPAGE
128 Please visit the project's homepage at
129 <https://metacpan.org/release/Text-sprintfn>.
130
131SOURCE
132 Source repository is at
133 <https://github.com/perlancar/perl-Text-sprintfn>.
134
135BUGS
136 Please report any bugs or feature requests on the bugtracker website
137 <https://rt.cpan.org/Public/Dist/Display.html?Name=Text-sprintfn>
138
139 When submitting a bug or request, please include a test-file or a patch
140 to an existing test-file that illustrates the bug or desired feature.
141
142SEE ALSO
143 sprintf() section on perlfunc
144
145 String::Formatter
146
147 Text::Sprintf::Named
148
149AUTHOR
150 perlancar <perlancar@cpan.org>
151
152COPYRIGHT AND LICENSE
153 This software is copyright (c) 2019, 2015, 2012, 2011 by
154 perlancar@cpan.org.
155
156 This is free software; you can redistribute it and/or modify it under
157 the same terms as the Perl 5 programming language system itself.
158
159