1String::Interpolate::NaUmseedr(3C)ontributed Perl DocumeSnttraitnigo:n:Interpolate::Named(3)
2
3
4

NAME

6       String::Interpolate::Named - Interpolated named arguments in string
7

SYNOPSIS

9           use String::Interpolate::Named;
10
11           my $ctl = { args => { fn => "Johan", ln => "Bach" } };
12           say interpolate( $ctl, "The famous %{fn} %{ln}." );
13
14           # If you like object orientation.
15           my $int = String::Interpolate::Named->new( { args => { ... } } );
16           say $int->interpolate("The famous %{fn} %{ln}.");
17

DESCRIPTION

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, or a subroutine that performs the
23       lookup.
24
25   Named Arguments
26       The arguments to be replaced are marked in the template by enclosing
27       them between "%{" and "}". For example, the string "The famous %{fn}
28       %{ln}." contains two named arguments, "fn" and "ln".
29
30       Note that the activator may be changed from "%" into something else,
31       see below. Throughout this document we use the default value.
32
33   Basic Interpolation
34       When interpolated, the keys "fn" and "ln" are looked up in the hash,
35       and the corresponding values are substituted. If no value was found for
36       a named argument, nothing is substituted and the "%{...}" is removed.
37
38       You can precede "%", "{", "}" (and "|", see below) with a backslash "\"
39       to hide their special meanings. For example, "\}" will not be
40       considered closing an argument but yield a plain "}" in the text.
41
42   Conditional Interpolation
43       It is possible to select replacement values depending on whether the
44       named argument has a value or not:
45
46           "This book has %{title|title %{title}}"
47           "This book has %{title|title %{title}|no title}"
48
49       These are considered "%{if|then}" and "%{if|then|else}" cases.
50
51       Assuming argument "title" has the value "My Book", in the first example
52       the text "title My Book", the 'then' text, will be substituted,
53       resulting in
54
55           "This book has title My Title"
56
57       If "title" does not have a value, the empty string is substituted. In
58       the second example, the string "no title", the 'else' text, will be
59       substituted.
60
61       As can be seen, the replacement texts may contain interpolations as
62       well. For convenience, you can use "%{}" to refer to the value of the
63       named argument currently being examinated. The last example above can
64       be written more shortly and elegantly as:
65
66           "This book has %{title|title %{}|no title}"
67
68   Testing Values
69       Instead of testing for named variables to have a value, you can also
70       test for specific values:
71
72           "This takes %{days=1|%{} day|%{} days}"
73
74   List Values
75       The replacement values hash may be scalar (in general: strings and
76       numbers) or lists of scalars. If a value is a list of scalars, it is
77       possible to select a particular value from the list by appending an
78       index (period and a number) to the named argument.
79
80       Assume "customer" has value "[ "Jones", "Smith" ]", then:
81
82           "%{customer.1} will be Smith"
83           "%{customer.2} will be Jones"
84           "%{customer} will be Jones Smith"
85
86       When the value exceeds the number of elements in the list, an empty
87       value is returned.  When no element is selected the values are
88       concatenated.
89
90   The Control Hash
91       The interpolation process requires two parameters: a hash with settings
92       and values for the named arguments, and the string to be used as a
93       template for interpolation. The hash will be further referred to as the
94       control hash.
95
96       The hash can have the following keys:
97
98       args
99           This is either a hash that contains replacement texts for the named
100           variables, or a subroutine that gets called with a variable as
101           argument and returns a replacement value.
102
103           This element should be considered mandatory.
104
105       separator
106           The separator used to concatenate list values, see "List Values"
107           above.
108
109           It defaults to Perl variable $" that, on its turn, defaults to a
110           single space.
111
112       activator
113           This is a single character that activates interpolation. By default
114           this is the percent "%" character.
115
116       keypattern
117           The pattern to match key names. Default is "qr/\w+[-_\w.]*/".
118
119       maxiter
120           To enable nested substitutions and recursive replacement, the
121           interpolation process is repeated until there are no more
122           interpolations to be made. The maximun number of iterations is
123           limited to the value of "maxiter".
124
125           By default maxiter is 16.
126
127       An example of a control hash:
128
129           my %ctl =
130             ( args => {
131                 customer => [ "Jones", "Smith" ],
132                 days     => 2,
133                 title    => "My Title",
134               },
135               separator => ", ",
136             );
137
138   Object Oriented API
139           my $ii = String::Interpolate::Named->new;
140           $ii->ctl(\%ctl);
141           $result = $ii->interpolate($template);
142
143       For convenience, the control hash may be passed to the constructor:
144
145           my $ii = String::Interpolate::Named->new(\%ctl);
146           $result = $ii->interpolate($template);
147
148   Functional API
149       String::Interpolate::Named privides a single function, "interpolate",
150       which is exported by default.
151
152       The subroutine takes two arguments: a reference to a control hash and
153       the template string.
154
155          $result = interpolate( \%ctl, $template );
156

METHODS

158   new
159       Constructs a new String::Interpolate::Named object.
160
161           my $ii = String::Interpolate::Named->new;
162
163       or
164
165           my $ii = String::Interpolate::Named->new(\%ctl);
166
167   ctl
168       Associates a control has with an existing object.
169
170           $ii->ctl(\%ctl);
171
172   interpolate
173       This routine performs the actual interpolations. It can be used as a
174       method:
175
176           $ii->interpolate($template);
177
178       and functional:
179
180           interpolate( \%ctl, $template );
181

REQUIREMENTS

183       Minimal Perl version 5.10.1.
184

AUTHOR

186       Johan Vromans, "<JV at CPAN dot org>"
187

SUPPORT

189       Development of this module takes place on GitHub:
190       <https://github.com/sciurius/perl-String-Interpolate-Named>.
191
192       You can find documentation for this module with the perldoc command.
193
194           perldoc String::Interpolate::Named
195
196       Please report any bugs or feature requests using the issue tracker on
197       GitHub.
198

ACKNOWLEDGEMENTS

200       Many of the existing template / interpolate / substitute modules.
201

203       Copyright 2018,2019 Johan Vromans, all rights reserved.
204
205       This program is free software; you can redistribute it and/or modify it
206       under the same terms as Perl itself.
207
208
209
210perl v5.36.0                      2023-01-20     String::Interpolate::Named(3)
Impressum