gitpan / string-expand Goto Github PK

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 <[email protected]>