NAME

       "String::Expand" - string utility functions for expanding variables in self-referential
       sets

SYNOPSIS

        use String::Expand qw( expand_strings );

        my %vars = ( MESSAGE => 'My home is $HOME',
                     TEXT    => 'Message is "$MESSAGE"' );

        expand_strings( \%vars, \%ENV );

        # %vars now contains something like:
        #   MESSAGE => 'My home is /home/user',
        #   TEXT    => 'Message is "My home is /home/user"'

DESCRIPTION

       This module implements utility functions for expanding embedded variables in a string.
       Variable references are embedded in strings in a similar form to the Bourne shell, namely,
       in the form $NAME or "${NAME}". In the former case, the "NAME" must consist of a capital
       letter or underscore, and may be followed by zero or more capital letters, digits or
       underscores. In the latter case, the name can consist of any characters, but will be
       terminated by the first close brace character '}'.

       The string may also contain literal dollar marks, escaped by "\$", and literal escape
       marks, escaped by "\\". These will be converted to "$" and "\" respectively on return.

       While there are many other modules that also provide expansion such as this, this module
       provides the function "expand_strings()", which will perform variable expansions in all
       the values in a given hash, where values can refer to other values within the same hash.

FUNCTIONS

   $expanded = expand_string( $str, \%vars )
       This function expands embedded variable references in the passed string, and returns the
       expanded copy.

       $str    A string possibly containing variable expansions

       \%vars  Reference to a hash containing variable values

       Returns A string with variables expanded

   expand_strings( \%strs, \%overlay )
       This function takes a hash of strings, and expands variable names embedded in any of them,
       in the same form as the string passed to "expand_string()".  Expansions may refer to other
       strings, or to values in the "%overlay" hash. Values in the main variables hash take
       precidence over values in the overlay.

       Where values refer to other values, care must be taken to avoid cycles. If a cycle is
       detected while attempting to expand the values, then an exception is thrown.

       \%strs  Reference to a hash containing variables to expand

       \%overlay
               Reference to a hash containing other variable values

       Returns Nothing

SEE ALSO

       •   String::Interpolate - Wrapper for builtin the Perl interpolation engine

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>