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, I); my $s = replace(I, I); 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); my $r = String::Replace->new(I); 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); my $u = String::Replace->new_unreplace(I); 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); my @l = $r->replace(I); $r->replace(I); 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 . 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.