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 no element is selected the values are concatenated.
87
88   The Control Hash
89       The interpolation process requires two parameters: a hash with settings
90       and values for the named arguments, and the string to be used as a
91       template for interpolation. The hash will be further referred to as the
92       control hash.
93
94       The hash can have the following keys:
95
96       args
97           This is either a hash that contains replacement texts for the named
98           variables, or a subroutine that gets called with a variable as
99           argument and returns a replacement value.
100
101           This element should be considered mandatory.
102
103       separator
104           The separator used to concatenate list values, see "List Values"
105           above.
106
107           It defaults to Perl variable $" that, on its turn, defaults to a
108           single space.
109
110       activator
111           This is a single character that activates interpolation. By default
112           this is the percent "%" character.
113
114       keypattern
115           The pattern to match key names. Default is "qr/\w+[-_\w.]*/".
116
117       maxiter
118           To enable nested substitutions and recursive replacement, the
119           interpolation process is repeated until there are no more
120           interpolations to be made. The maximun number of iterations is
121           limited to the value of "maxiter".
122
123           By default maxiter is 16.
124
125       An example of a control hash:
126
127           my %ctl =
128             ( args => {
129                 customer => [ "Jones", "Smith" ],
130                 days     => 2,
131                 title    => "My Title",
132               },
133               separator => ", ",
134             );
135
136   Object Oriented API
137           my $ii = String::Interpolate::Named->new;
138           $ii->ctl(\%ctl);
139           $result = $ii->interpolate($template);
140
141       For convenience, the control hash may be passed to the constructor:
142
143           my $ii = String::Interpolate::Named->new(\%ctl);
144           $result = $ii->interpolate($template);
145
146   Functional API
147       String::Interpolate::Named privides a single function, "interpolate",
148       which is exported by default.
149
150       The subroutine takes two arguments: a reference to a control hash and
151       the template string.
152
153          $result = interpolate( \%ctl, $template );
154

METHODS

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

REQUIREMENTS

181       Minimal Perl version 5.10.1.
182

AUTHOR

184       Johan Vromans, "<JV at CPAN dot org>"
185

SUPPORT

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

ACKNOWLEDGEMENTS

198       Many of the existing template / interpolate / substitute modules.
199

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