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.01 (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.