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.
23
24   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
29   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
34       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
38   Conditional Interpolation
39       It is possible to select replacement values depending on whether the
40       named argument has a value or not:
41
42           "This book has %{title|title %{title}}"
43           "This book has %{title|title %{title}|no title}"
44
45       These are considered "%{if|then}" and "%{if|then|else}" cases.
46
47       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
51           "This book has title My Title"
52
53       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
57       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
62           "This book has %{title|title %{}|no title}"
63
64   Testing Values
65       Instead of testing for named variables to have a value, you can also
66       test for specific values:
67
68           "This takes %{days=1|%{} day|%{} days}"
69
70   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
76       Assume "customer" has value "[ "Jones", "Smith" ]", then:
77
78           "%{customer.1} will be Smith"
79           "%{customer.2} will be Jones"
80           "%{customer} will be Jones Smith"
81
82       When no element is selected the values are concatenated.
83
84   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
90       The hash can have the following keys:
91
92       vars
93           This is the hash that contains replacement texts for the named
94           variables.
95
96           This element should be considered mandatory.
97
98       separator
99           The separator used to concatenate list values, see "List Values"
100           above.
101
102           It defaults to Perl variable $" that, on its turn, defaults to a
103           single space.
104
105       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
111           By default maxiter is 16.
112
113       An example of a control hash:
114
115           my %ctl =
116             ( args => {
117                 customer => [ "Jones", "Smith" ],
118                 days     => 2,
119                 title    => "My Title",
120               },
121               separator => ", ",
122             );
123
124   Object Oriented API
125           my $ii = String::Interpolate::Named->new;
126           $ii->ctl(\%ctl);
127           $result = $ii->interpolate($template);
128
129       For convenience, the control hash may be passed to the constructor:
130
131           my $ii = String::Interpolate::Named->new(\%ctl);
132           $result = $ii->interpolate($template);
133
134   Functional API
135       String::Interpolate::Named privides a single function, "interpolate",
136       which is exported by default.
137
138       The subroutine takes two arguments: a reference to a control hash and
139       the template string.
140
141          $result = interpolate( \%ctl, $template );
142

METHODS

144   new
145       Constructs a new String::Interpolate::Named object.
146
147           my $ii = String::Interpolate::Named->new;
148
149       or
150
151           my $ii = String::Interpolate::Named->new(\%ctl);
152
153   ctl
154       Associates a control has with an existing object.
155
156           $ii->ctl(\%ctl);
157
158   interpolate
159       This routine performs the actual interpolations. It can be used as a
160       method:
161
162           $ii->interpolate($template);
163
164       and functional:
165
166           interpolate( \%ctl, $template );
167

REQUIREMENTS

169       Minimal Perl version 5.10.1.
170

AUTHOR

172       Johan Vromans, "<JV at CPAN dot org>"
173

SUPPORT

175       Development of this module takes place on GitHub:
176       <https://github.com/sciurius/perl-String-Interpolate-Named>.
177
178       You can find documentation for this module with the perldoc command.
179
180           perldoc String::Interpolate::Named
181
182       Please report any bugs or feature requests using the issue tracker on
183       GitHub.
184

ACKNOWLEDGEMENTS

186       Many of the existing template / interpolate / substitute modules.
187
189       Copyright 2018,2019 Johan Vromans, all rights reserved.
190
191       This program is free software; you can redistribute it and/or modify it
192       under the same terms as Perl itself.
193
194
195
196perl v5.30.1                      2020-02-28     String::Interpolate::Named(3)
Impressum