NAME

String::Replace - Performs arbitrary replacement in strings

SYNOPSIS

  use String::Replace ':all';
  
  print replace('hello name', 'name' => 'world');
  print unreplace('hello world', {'name' => 'world'});
  
  my $r = String::Replace->new('name' => 'world');
  print $r->replace('hello world');

DESCRIPTION

String::Replace is a small module allowing to performs arbitrary replacement in strings. Arbitrary means that there is no specific syntax to do so, you can just replace any arbitrary substring.

The real functionnality of String::Replace is its OO interface which allows you to prepare and encapsulate replacement to be performed in string. While other templating systems (all of them ?) allow you to load a template and then to perform successive series of replacement in it, String::Replace allows you to load a serie of replacement and then apply them successively to many template. If this is what you need to do, your code will be simpler to read with String::Replace and maybe slighly faster due to the preprocessing which can be done.

Standard templating systems are typically used to generate the same web page many times for different users. String::Replace is rather used to generate a lot of different content for a single user, or to provide a simple parametrisation system for code (as is done with SQL in my SQL::Exec module).

FUNCTIONS

This is a list of the public function of this library. Functions not listed here are for internal use only by this module and should not be used in any external code.

Each function of this library (that is replace and unreplace) may be exported on request. There is also a ':all' tag to get everything at once. Just do :

  use String::Replace ':all';

to have all the functions of the library imported into your current package.

replace

  my $s = replace(EXPR, LIST);
  my $s = replace(EXPR, HASH);

The replace function take a string and a list of replacement to perform in the string and return a string where all replacement have been done. the replacement can be given either as list or as a hash reference.

  replace('this is a string', 'this' => 'that', 'string' => 'chair');
  replace('this is a string', { 'this' => 'that', 'string' => 'chair' });

will both return the string 'that is a chair'.

You should not that the replacement will be executed in the order in which they appear if you give a list but in no particular order if you give a hash reference. So if a replacement creates a substring that may be replaced by an other replacement then you should use a list of replacement to be sure of what will be happening.

unreplace

  my $s = replace(I<EXPR>, I<LIST>);
  my $s = replace(I<EXPR>, I<HASH>);

Performs the opposite of the replace function.

  replace('that is a chair', 'this' => 'that', 'string' => 'chair');
  replace('that is a chair', { 'this' => 'that', 'string' => 'chair' });

will both return the string 'this is a string'. The same caveat than for the replace function will apply.

Object-Oriented interface

If you wish so, you may also use an object oriented interface to String::Replace. The object oriented interface will be (slightly) faster than the functionnal one if you have many strings on which you will perform the same replacement (as some regexp can be pre-compiled).

new

  my $r = String::Replace->new(I<LIST>);
  my $r = String::Replace->new(I<HASH>);

This constructor may be called with either a list of replacement to performs or a reference to a hash describing these replacements. The argument is treated in the same way as the second argument to the replace function. When created, the replace method may then be called on the object.

The code:

  my $r = String::Replace->new('this' => 'that', 'string' => 'chair');
  $r->replace('this is a string');

will return the same thing than the example above but the $r object might be reused.

The same caveat as for the order of the argument to the replace function apply for this constructor.

new_unreplace

  my $u = String::Replace->new_unreplace(I<LIST>);
  my $u = String::Replace->new_unreplace(I<HASH>);

This constructor may be called with either a list of replacement a reference to a hash describing replacements. The argument is treated in the same way as the second argument to the unreplace function. When created, the replace method may then be called on the object the execute this un-replacement.

The code:

  my $u = String::Replace->new_unreplace('this' => 'that', 'string' => 'chair');
  $u->replace('that is a chair');

will return the same thing than the example above but the $u object might be reused.

The same caveat as for the order of the argument to the replace function apply for this constructor.

replace

  my $s = $r->replace(I<LIST>);
  my @l = $r->replace(I<LIST>);
  $r->replace(I<LIST>);

This function performs a prepared replacement or un-replacement as described in the documentation of the new and new_unreplace constructors.

This function is context sensitive: if it is called in list context, it will apply its replacement in turn to each of its argument and returns a list with each string where the replacement has been done. If it is called in sink (void) context, then the replacement are executed in place. If called in scalar context only the first argument of the replace function is taken and replaced and the result of this replacement is returned.

The same apply if the object was prepared with new_unreplace instead of new.

unreplace

  $r->unreplace(LIST);

This method is exactly the same as the replace one and will not distinguish between object created with the new or the new_unreplace functions. It is provided only for convenience.

CAVEATS

As stated above, the order in which the arguments are provided to the functions of this library may matter. To avoid problem, you should use a non-ambiguous parametrisation scheme (like prefixing all your variable to be replaced with a given character).

If this a problem for you, there is a safe version of this library: String::Replace::Safe. This version will performs all its replacement atomically so the order of the argument does not matter. However the speed of this version will be approximately half that of the String::Replace version (according to my test, this does not depend much on the size of the string, the number of replacement that you want to perform or the number of replacement actually performed).

In an unambiguous case, the two version of this library should give back exactly the same results.

BUGS

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

SEE ALSO

There is a safer (and slower) version of this library: String::Replace::Safe.

There is also a lot of templating system on CPAN and a lot of them could let you achieve the same thing than String::Replace (with the caveat that they are all centered around the template and not around the replace operation). Some simple and efficient modules are the followings: String::Interpolate::Shell and String::Interpolate::RE.

AUTHOR

Mathias Kende (mathias@cpan.org)

VERSION

Version 0.02 (January 2013)

COPYRIGHT & LICENSE

Copyright 2013 © Mathias Kende. 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::Replace

perl -MCPAN -e shell
install String::Replace