GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
String::Interpolate::Named(3) User Contributed Perl Documentation String::Interpolate::Named(3)

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

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

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

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.

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.

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

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

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

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.

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

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

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

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

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

or

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

Associates a control has with an existing object.

    $ii->ctl(\%ctl);

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

    $ii->interpolate($template);

and functional:

    interpolate( \%ctl, $template );

Minimal Perl version 5.10.1.

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

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.

Many of the existing template / interpolate / substitute modules.

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.

2022-01-13 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.