Named Arguments

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

Basic Interpolation

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.

Conditional Interpolation

    "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}"

Testing Values

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

List Values

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.

The Control Hash

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 => ", ",
      );

Object Oriented API

    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);

Functional API

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

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

new

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

or

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

ctl

    $ii->ctl(\%ctl);

interpolate

    $ii->interpolate($template);

and functional:

    interpolate( \%ctl, $template );