1String::Interpolate::NaUmseedr(3C)ontributed Perl DocumeSnttraitnigo:n:Interpolate::Named(3)
2
6 String::Interpolate::Named - Interpolated named arguments in string
7
9 use String::Interpolate::Named;
10 my $ctl = { args => { fn => "Johan", ln => "Bach" } };
12 say interpolate( $ctl, "The famous %{fn} %{ln}." );
13 # If you like object orientation.
15 my $int = String::Interpolate::Named->new( { args => { ... } } );
16 say $int->interpolate("The famous %{fn} %{ln}.");
17
19 String::Interpolate::Named provides a function to interpolate named
20 arguments by target texts in a template string. The target texts are
21 provided to the function via a hash, where the keys correspond to the
22 named argument to be replaced.
23 Named Arguments
25 The arguments to be replaced are marked in the template by enclosing
26 them between "%{" and "}". For example, the string "The famous %{fn}
27 %{ln}." contains two named arguments, "fn" and "ln".
28 Basic Interpolation
30 When interpolated, the keys "fn" and "ln" are looked up in the hash,
31 and the corresponding values are substituted. If no value was found for
32 a named argument, nothing is substituted and the "%{...}" is removed.
33 You can precede "%", "{", "}" (and "|", see below) with a backslash "\"
35 to hide their special meanings. For example, "\}" will not be
36 considered closing an argument but yield a plain "}" in the text.
37 Conditional Interpolation
39 It is possible to select replacement values depending on whether the
40 named argument has a value or not:
41 "This book has %{title|title %{title}}"
43 "This book has %{title|title %{title}|no title}"
44 These are considered "%{if|then}" and "%{if|then|else}" cases.
46 Assuming argument "title" has the value "My Book", in the first example
48 the text "title My Book", the 'then' text, will be substituted,
49 resulting in
50 "This book has title My Title"
52 If "title" does not have a value, the empty string is substituted. In
54 the second example, the string "no title", the 'else' text, will be
55 substituted.
56 As can be seen, the replacement texts may contain interpolations as
58 well. For convenience, you can use "%{}" to refer to the value of the
59 named argument currently being examinated. The last example above can
60 be written more shortly and elegantly as:
61 "This book has %{title|title %{}|no title}"
63 Testing Values
65 Instead of testing for named variables to have a value, you can also
66 test for specific values:
67 "This takes %{days=1|%{} day|%{} days}"
69 List Values
71 The replacement values hash may be scalar (in general: strings and
72 numbers) or lists of scalars. If a value is a list of scalars, it is
73 possible to select a particular value from the list by appending an
74 index (period and a number) to the named argument.
75 Assume "customer" has value "[ "Jones", "Smith" ]", then:
77 "%{customer.1} will be Smith"
79 "%{customer.2} will be Jones"
80 "%{customer} will be Jones Smith"
81 When no element is selected the values are concatenated.
83 The Control Hash
85 The interpolation process requires two parameters: a hash with settings
86 and values for the named arguments, and the string to be used as a
87 template for interpolation. The hash will be further referred to as the
88 control hash.
89 The hash can have the following keys:
91 vars
93 This is the hash that contains replacement texts for the named
94 variables.
95 This element should be considered mandatory.
97 separator
99 The separator used to concatenate list values, see "List Values"
100 above.
101 It defaults to Perl variable $" that, on its turn, defaults to a
103 single space.
104 maxiter
106 To enable nested substitutions and recursive replacement, the
107 interpolation process is repeated until there are no more
108 interpolations to be made. The maximun number of iterations is
109 limited to the value of "maxiter".
110 By default maxiter is 16.
112 An example of a control hash:
114 my %ctl =
116 ( args => {
117 customer => [ "Jones", "Smith" ],
118 days => 2,
119 title => "My Title",
120 },
121 separator => ", ",
122 );
123 Object Oriented API
125 my $ii = String::Interpolate::Named->new;
126 $ii->ctl(\%ctl);
127 $result = $ii->interpolate($template);
128 For convenience, the control hash may be passed to the constructor:
130 my $ii = String::Interpolate::Named->new(\%ctl);
132 $result = $ii->interpolate($template);
133 Functional API
135 String::Interpolate::Named privides a single function, "interpolate",
136 which is exported by default.
137 The subroutine takes two arguments: a reference to a control hash and
139 the template string.
140 $result = interpolate( \%ctl, $template );
142
144 new
145 Constructs a new String::Interpolate::Named object.
146 my $ii = String::Interpolate::Named->new;
148 or
150 my $ii = String::Interpolate::Named->new(\%ctl);
152 ctl
154 Associates a control has with an existing object.
155 $ii->ctl(\%ctl);
157 interpolate
159 This routine performs the actual interpolations. It can be used as a
160 method:
161 $ii->interpolate($template);
163 and functional:
165 interpolate( \%ctl, $template );
167
169 Minimal Perl version 5.10.1.
170
172 Johan Vromans, "<JV at CPAN dot org>"
173
175 Development of this module takes place on GitHub:
176 <https://github.com/sciurius/perl-String-Interpolate-Named>.
177 You can find documentation for this module with the perldoc command.
179 perldoc String::Interpolate::Named
181 Please report any bugs or feature requests using the issue tracker on
183 GitHub.
184
186 Many of the existing template / interpolate / substitute modules.
187
189 Copyright 2018,2019 Johan Vromans, all rights reserved.
190 This program is free software; you can redistribute it and/or modify it
192 under the same terms as Perl itself.
193perl v5.32.0 2020-07-28 String::Interpolate::Named(3)