/ 
String-MatchInterpolate-0.01
River stage zero No dependents
/ String::MatchInterpolate

NAME

String::MatchInterpolate - perform named regexp capture and variable interpolation from the same template.

SYNOPSIS

use String::MatchInterpolate;

my $smi = String::MatchInterpolate->new( 'My name is ${NAME/\w+/}' );

my $vars = $smi->match( "My name is Bob" );
my $name = $vars->{NAME};

print $smi->interpolate( { NAME => "Jim" } ) . "\n";

DESCRIPTION

This module provides an object class which represents a string matching and interpolation pattern. It contains named-variable placeholders which include a regexp pattern to match them on. An instance of this class represents a single pattern, which can be matched against or interpolated into.

Objects in this class are not modified once constructed; they do not store any runtime state other than data derived arguments passed to the constructor.

Template Format

The template consists of a string with named variable placeholders embedded in it. It looks similar to a perl or shell string with interpolation:

A string here with ${NAME/pattern/} interpolations

The embedded variable is delmited by perl-style ${ } braces, and contains a name and a pattern. The pattern is a normal perl regexp fragment that will be used by the match() method. This regexp should not contain any capture brackets ( ) as these will confuse the parsing logic.

Outside of the embedded variables, the string is interpreted literally; i.e. not as a regexp pattern. A backslash \ may be used to escape the following character, allowing literal backslashes or dollar signs to be used.

The intended use for this object class is that the template strings would come from a configuration file, or some other source of "trusted" input. In the current implementation, there is nothing to stop a carefully-crafted string from containing arbitrary perl code, which would be executed every time the match() or interpolate() methods are called. (See "SECURITY" section). This fact may be changed in a later version.

CONSTRUCTOR

$smi = String::MatchInterpolate->new( $template )

Constructs a new String::MatchInterpolate object that represents the given template and returns it.

$template

A string containing the template in the format given above

METHODS

$vars = $smi->match( $str )

Attempts to match the given string against the template. If successful, returns a HASH reference containing the values of the captures. If the string fails to match, undef is returned.

$str

The string to match

$str = $smi->interpolate( $vars )

Interpolates the given variable values into the template and returns the generated string.

$vars

Reference to a HASH containing the variable values to interpolate

@vars = $smi->vars()

Returns the list of variable names defined / used by the template.

NOTES

The template is compiled into a pair of strings containing perl code, which implement the matching and interpolation operations using normal perl regexps and string contatenation. These strings are then eval()ed into CODE references which the object stores. This makes it faster than a simple regexp that operates over the template string each time a match or interpolation needs to be performed. (See the benchmark.pl file in the module's distribution).

SECURITY CONSIDERATIONS

Because of the way the optimised match and interpolate functions are generated, it is possible to inject arbitrary perl code via the template given to the constructor. As such, this object should not be used when the source of that template is considered untrusted.

Neither the match() not interpolate() methods suffer this problem; any input into these is safe from exploit in this way.

SEE ALSO

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>