NAME

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

SYNOPSIS

    use String::Interpolate::Named;

    my $ctl = { args => { fn => "Johan", ln => "Bach" } };
    say interpolate( $ctl, "The famous %{fn} %{ln}." );

DESCRIPTION

String::Interpolate::Named exports a single function, interpolate, that takes a string and substitutes named variables by target texts.

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

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

In its basic form, the %{var} is replaced by the value of the key var in the args element of the control hash. It is also possible to specify replacement values depending on whether var has a value or not:

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

Assuming argument title has the value "My Book", in the first example the text "title My Book" will be substituted. If title does not have a value, the empty string is substituted.

In the second example, the string "no title" 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 variable currently being examinated. The last example above can be written more shortly and elegantly as:

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

You can test for specific values:

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

Finally, the values as specified in the control 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 value from the list by appending a period and a number to the key. Assume customer has value [ "Jones", "Smith" ], then:

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

The control hash contains the values for the variables in "args":

    { args => { customer => [ "Jones", "Smith" ],
                days => 2, ... },
    }

When list values need to be concatenated, a separator may be specified:

    { args => { customer => [ "Jones", "Smith" ],
                days => 2, ... },
      separator => ", ",
    }

The separator defaults to a single space.

AUTHOR

Johan Vromans, <JV at CPAN dot org>

SUPPORT

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.

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2018 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.

cpanm String::Interpolate::Named

perl -MCPAN -e shell
install String::Interpolate::Named