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

       Many of the existing template / interpolate / substitute modules.

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

       Copyright 2018,2019 Johan Vromans, all rights reserved.

       This program is free software; you can redistribute it and/or modify it under  the  same  terms  as  Perl
       itself.

perl v5.38.2                                       2024-02-23                    String::Interpolate::Named(3pm)

       String::Interpolate::Named provides a function to interpolate named arguments by targettexts 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.

   NamedArguments
       The arguments to be replaced are marked in the template by enclosing them between "%{" and "}". For
       example, the string "The famous %{fn} %{ln}." contains two named arguments, "fn" and "ln".

       Note that the activator may be changed from "%" into something else, see below. Throughout this document
       we use the default value.

   BasicInterpolation
       When interpolated, the keys "fn" and "ln" 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 "%{...}" is
       removed.

       You can precede "%", "{", "}" (and "|", see below) with a backslash "\" to hide their special meanings.
       For example, "\}" will not be considered closing an argument but yield a plain "}" in the text.

   ConditionalInterpolation
       It is possible to select replacement values depending on whether the named argument has a value or not:

           "This book has %{title|title %{title}}"
           "This book has %{title|title %{title}|no title}"

       These are considered "%{if|then}" and "%{if|then|else}" cases.

       Assuming argument "title" has the value "My Book", in the first example the text "title My Book", the
       'then' text, will be substituted, resulting in

           "This book has title My Title"

       If "title" does not have a value, the empty string is substituted. In the second example, the string "no
       title", the 'else' text, will be substituted.

       As can be seen, the replacement texts may contain interpolations as well. For convenience, you can use
       "%{}" to refer to the value of the named argument currently being examinated. The last example above can
       be written more shortly and elegantly as:

           "This book has %{title|title %{}|no title}"

   TestingValues
       Instead of testing for named variables to have a value, you can also test for specific values:

           "This takes %{days=1|%{} day|%{} days}"

   ListValues
       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.

       Assume "customer" has value "[ "Jones", "Smith" ]", then:

           "%{customer.1} will be Smith"
           "%{customer.2} will be Jones"
           "%{customer} will be Jones Smith"

       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.

   TheControlHash
       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 controlhash.

       The hash can have the following keys:

       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.

           This element should be considered mandatory.

       separator
           The separator used to concatenate list values, see "List Values" above.

           It defaults to Perl variable $" that, on its turn, defaults to a single space.

       activator
           This is a single character  that  activates  interpolation.  By  default  this  is  the  percent  "%"
           character.

       keypattern
           The pattern to match key names. Default is "qr/\w+[-_\w.]*/".

       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 "maxiter".

           By default maxiter is 16.

       An example of a control hash:

           my %ctl =
             ( args => {
                 customer => [ "Jones", "Smith" ],
                 days     => 2,
                 title    => "My Title",
               },
               separator => ", ",
             );

   ObjectOrientedAPI
           my $ii = String::Interpolate::Named->new;
           $ii->ctl(\%ctl);
           $result = $ii->interpolate($template);

       For convenience, the control hash may be passed to the constructor:

           my $ii = String::Interpolate::Named->new(\%ctl);
           $result = $ii->interpolate($template);

   FunctionalAPI
       String::Interpolate::Named privides a single function, "interpolate", which is exported by default.

       The subroutine takes two arguments: a reference to a control hash and the template string.

          $result = interpolate( \%ctl, $template );

new
       Constructs a new String::Interpolate::Named object.

           my $ii = String::Interpolate::Named->new;

       or

           my $ii = String::Interpolate::Named->new(\%ctl);

   ctl
       Associates a control has with an existing object.

           $ii->ctl(\%ctl);

   interpolate
       This routine performs the actual interpolations. It can be used as a method:

           $ii->interpolate($template);

       and functional:

           interpolate( \%ctl, $template );

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

       Minimal Perl version 5.10.1.

       Development         of         this         module         takes         place         on         GitHub:
       <https://github.com/sciurius/perl-String-Interpolate-Named>.

       You can find documentation for this module with the perldoc command.

           perldoc String::Interpolate::Named

       Please report any bugs or feature requests using the issue tracker on GitHub.

           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}.");