Diab Jerius > String-Interpolate-RE > String::Interpolate::RE

Download:
String-Interpolate-RE-0.05.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.05   Source  

NAME ^

String::Interpolate::RE - interpolate variables into strings

SYNOPSIS ^

    use String::Interpolate::RE qw( strinterp );

    $str = strinterp( "${Var1} $Var2", $vars, \%opts );

DESCRIPTION ^

This module interpolates variables into strings using regular expression matching rather than Perl's built-in interpolation mechanism and thus hopefully does not suffer from the security problems inherent in using eval to interpolate into strings of suspect ancestry.

INTERFACE ^

strinterp
    $str = strinterp( $template );
    $str = strinterp( $template, $vars );
    $str = strinterp( $template, $vars, \%opts );

Interpolate variables into a template string, returning the resultant string. The template string is scanned for tokens of the form

    $VAR
    ${VAR}

where VAR is composed of one or more word characters (as defined by the \w Perl regular expression pattern). VAR is resolved using the optional $vars argument, which may either by a hashref (in which case VAR must be a key), or a function reference (which is passed VAR as its only argument and must return the value).

If the value returned for VAR is defined, it will be interpolated into the string at that point. By default, variables which are not defined are by default left as is in the string.

The %opts parameter may be used to modify the behavior of this function. The following (case insensitive) keys are recognized:

format boolean

If this flag is true, the template string may provide a sprintf compatible format which will be used to generate the interpolated value. The format should be appended to the variable name with an intervening : character, e.g.

    ${VAR:fmt}

For example,

    %var = ( foo => 3 );
    print strinterp( '${foo:%03d}', \%var, { format => 1 } );

would result in

    003
raiseundef boolean

If true, a variable which has not been defined will result in an exception being raised. This defaults to false.

emptyundef boolean

If true, a variable which has not been defined will be replaced with the empty string. This defaults to false.

useENV boolean

If true, the %ENV hash will be searched for variables which are not defined in the passed %var hash. This defaults to true.

recurse boolean

If true, derived values are themselves scanned for variables to interpolate. To specify a limit to the number of levels of recursions to attempt, set the recurse_limit option. Circular dependencies are caught, but just to be safe there's a limit of recursion levels specified by recurse_fail_limit, beyond which an exception is thrown.

For example,

  my %var = ( a => '$b', b => '$c', c => 'd' );
  strinterp( '$a', \%var ) => '$b'
  strinterp( '$a', \%var, { recurse => 1 } ) => 'd'
  strinterp( '$a', \%var, { recurse => 1, recurse_limit => 1 } ) => '$c'

  strinterp( '$a', { a => '$b', b => '$a' } , { recurse => 1 }
        recursive interpolation loop detected with repeated
        interpolation of $a
recurse_limit integer

The number of recursion levels to descend when recursing into a variable's value before stopping. The default is 0, which means no limit.

recurse_fail_limit integer

The number of recursion levels to descend when recursing into a variable's value before giving up and croaking. The default is 100. Setting this to 0 means no limit.

DIAGNOSTICS ^

undefined variable: %s

This string is thrown if the RaiseUndef option is set and the variable %s is not defined.

recursive interpolation loop detected with repeated interpolation of <%s>

When resolving nested interpolated values (with the recurse option true ) a circular loop was found.

recursion fail-safe limit (%d) reached at interpolation of <%s>

The recursion fail safe limit (recurse_fail_limit) was reached while interpolating nested variable values (with the recurse option true ).

BUGS AND LIMITATIONS ^

No bugs have been reported.

Please report any bugs or feature requests to bug-string-interpolate-re@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=String-Interpolate-RE.

SEE ALSO ^

Other CPAN Modules which interpolate into strings are String::Interpolate and Interpolate. This module avoids the use of eval() and presents a simpler interface.

LICENSE AND COPYRIGHT ^

Copyright (c) 2007, 2014 The Smithsonian Astrophysical Observatory

String::Interpolate::RE is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

AUTHOR ^

Diab Jerius <djerius@cpan.org>

syntax highlighting: