.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "String::Interpolate::Named 3pm"
.TH String::Interpolate::Named 3pm 2024-02-23 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
String::Interpolate::Named \- Interpolated named arguments in string
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&    use String::Interpolate::Named;
\&
\&    my $ctl = { args => { fn => "Johan", ln => "Bach" } };
\&    say interpolate( $ctl, "The famous %{fn} %{ln}." );
\&
\&    # If you like object orientation.
\&    my $int = String::Interpolate::Named\->new( { args => { ... } } );
\&    say $int\->interpolate("The famous %{fn} %{ln}.");
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
String::Interpolate::Named provides a function to interpolate named
\&\fIarguments\fR by \fItarget texts\fR in a template string. The target texts
are provided to the function via a hash, where the keys correspond to
the named argument to be replaced, or a subroutine that performs the
lookup.
.SS "Named Arguments"
.IX Subsection "Named Arguments"
The arguments to be replaced are marked in the template by enclosing
them between \f(CW\*(C`%{\*(C'\fR and \f(CW\*(C`}\*(C'\fR. For example, the string \f(CW"The famous
%{fn} %{ln}."\fR contains two named arguments, \f(CW\*(C`fn\*(C'\fR and \f(CW\*(C`ln\*(C'\fR.
.PP
Note that the activator may be changed from \f(CW\*(C`%\*(C'\fR into something else,
see below. Throughout this document we use the default value.
.SS "Basic Interpolation"
.IX Subsection "Basic Interpolation"
When interpolated, the keys \f(CW\*(C`fn\*(C'\fR and \f(CW\*(C`ln\*(C'\fR are looked up in the hash,
and the corresponding values are substituted. If no value was found
for a named argument, nothing is substituted and the \f(CW\*(C`%{...}\*(C'\fR is
removed.
.PP
You can precede \f(CW\*(C`%\*(C'\fR, \f(CW\*(C`{\*(C'\fR, \f(CW\*(C`}\*(C'\fR (and \f(CW\*(C`|\*(C'\fR, see below) with a
backslash \f(CW\*(C`\e\*(C'\fR to hide their special meanings. For example, \f(CW\*(C`\e}\*(C'\fR will
\&\fInot\fR be considered closing an argument but yield a plain \f(CW\*(C`}\*(C'\fR in the
text.
.SS "Conditional Interpolation"
.IX Subsection "Conditional Interpolation"
It is possible to select replacement values depending on whether
the named argument has a value or not:
.PP
.Vb 2
\&    "This book has %{title|title %{title}}"
\&    "This book has %{title|title %{title}|no title}"
.Ve
.PP
These are considered \f(CW\*(C`%{if|then}\*(C'\fR and \f(CW\*(C`%{if|then|else}\*(C'\fR cases.
.PP
Assuming argument \f(CW\*(C`title\*(C'\fR has the value \f(CW"My Book"\fR, in the first
example the text \f(CW"title My Book"\fR, the 'then' text, will be
substituted, resulting in
.PP
.Vb 1
\&    "This book has title My Title"
.Ve
.PP
If \f(CW\*(C`title\*(C'\fR does not have a value, the empty string is substituted. In
the second example, the string \f(CW"no title"\fR, the 'else' text, will be
substituted.
.PP
As can be seen, the replacement texts may contain interpolations as
well. For convenience, you can use \f(CW\*(C`%{}\*(C'\fR to refer to the value of the
named argument currently being examinated. The last example above can
be written more shortly and elegantly as:
.PP
.Vb 1
\&    "This book has %{title|title %{}|no title}"
.Ve
.SS "Testing Values"
.IX Subsection "Testing Values"
Instead of testing for named variables to have a value, you can also
test for specific values:
.PP
.Vb 1
\&    "This takes %{days=1|%{} day|%{} days}"
.Ve
.SS "List Values"
.IX Subsection "List Values"
The replacement values hash may be scalar (in general: strings and
numbers) or lists of scalars. If a value is a list of scalars, it is
possible to select a particular value from the list by appending an
index (period and a number) to the named argument.
.PP
Assume \f(CW\*(C`customer\*(C'\fR has value \f(CW\*(C`[ "Jones", "Smith" ]\*(C'\fR, then:
.PP
.Vb 3
\&    "%{customer.1} will be Smith"
\&    "%{customer.2} will be Jones"
\&    "%{customer} will be Jones Smith"
.Ve
.PP
When the value exceeds the number of elements in the list, an empty
value is returned.
When no element is selected the values are concatenated.
.SS "The Control Hash"
.IX Subsection "The Control Hash"
The interpolation process requires two parameters: a hash with
settings and values for the named arguments, and the string to be used
as a template for interpolation. The hash will be further referred to
as the \fIcontrol hash\fR.
.PP
The hash can have the following keys:
.IP args 4
.IX Item "args"
This is either a hash that contains replacement texts for the named
variables, or a subroutine that gets called with a variable as
argument and returns a replacement value.
.Sp
This element should be considered mandatory.
.IP separator 4
.IX Item "separator"
The separator used to concatenate list values, see "List Values" above.
.Sp
It defaults to Perl variable \f(CW$"\fR that, on its turn, defaults to a
single space.
.IP activator 4
.IX Item "activator"
This is a single character that activates interpolation. By default
this is the percent \f(CW\*(C`%\*(C'\fR character.
.IP keypattern 4
.IX Item "keypattern"
The pattern to match key names. Default is \f(CW\*(C`qr/\ew+[\-_\ew.]*/\*(C'\fR.
.IP maxiter 4
.IX Item "maxiter"
To enable nested substitutions and recursive replacement, the
interpolation process is repeated until there are no more
interpolations to be made. The maximun number of iterations is limited
to the value of \f(CW\*(C`maxiter\*(C'\fR.
.Sp
By default maxiter is 16.
.PP
An example of a control hash:
.PP
.Vb 8
\&    my %ctl =
\&      ( args => {
\&          customer => [ "Jones", "Smith" ],
\&          days     => 2,
\&          title    => "My Title",
\&        },
\&        separator => ", ",
\&      );
.Ve
.SS "Object Oriented API"
.IX Subsection "Object Oriented API"
.Vb 3
\&    my $ii = String::Interpolate::Named\->new;
\&    $ii\->ctl(\e%ctl);
\&    $result = $ii\->interpolate($template);
.Ve
.PP
For convenience, the control hash may be passed to the constructor:
.PP
.Vb 2
\&    my $ii = String::Interpolate::Named\->new(\e%ctl);
\&    $result = $ii\->interpolate($template);
.Ve
.SS "Functional API"
.IX Subsection "Functional API"
String::Interpolate::Named privides a single function, \f(CW\*(C`interpolate\*(C'\fR,
which is exported by default.
.PP
The subroutine takes two arguments: a reference to a control hash and
the template string.
.PP
.Vb 1
\&   $result = interpolate( \e%ctl, $template );
.Ve
.SH METHODS
.IX Header "METHODS"
.SS new
.IX Subsection "new"
Constructs a new String::Interpolate::Named object.
.PP
.Vb 1
\&    my $ii = String::Interpolate::Named\->new;
.Ve
.PP
or
.PP
.Vb 1
\&    my $ii = String::Interpolate::Named\->new(\e%ctl);
.Ve
.SS ctl
.IX Subsection "ctl"
Associates a control has with an existing object.
.PP
.Vb 1
\&    $ii\->ctl(\e%ctl);
.Ve
.SS interpolate
.IX Subsection "interpolate"
This routine performs the actual interpolations. It can be used as a method:
.PP
.Vb 1
\&    $ii\->interpolate($template);
.Ve
.PP
and functional:
.PP
.Vb 1
\&    interpolate( \e%ctl, $template );
.Ve
.SH REQUIREMENTS
.IX Header "REQUIREMENTS"
Minimal Perl version 5.10.1.
.SH AUTHOR
.IX Header "AUTHOR"
Johan Vromans, \f(CW\*(C`<JV at CPAN dot org>\*(C'\fR
.SH SUPPORT
.IX Header "SUPPORT"
Development of this module takes place on GitHub:
<https://github.com/sciurius/perl\-String\-Interpolate\-Named>.
.PP
You can find documentation for this module with the perldoc command.
.PP
.Vb 1
\&    perldoc String::Interpolate::Named
.Ve
.PP
Please report any bugs or feature requests using the issue tracker on
GitHub.
.SH ACKNOWLEDGEMENTS
.IX Header "ACKNOWLEDGEMENTS"
Many of the existing template / interpolate / substitute modules.
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2018,2019 Johan Vromans, all rights reserved.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.