.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "String::Expand 3pm"
.TH String::Expand 3pm "2015-11-29" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
"String::Expand" \- string utility functions for expanding variables in
self\-referential sets
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use String::Expand qw( expand_strings );
\&
\& my %vars = ( MESSAGE => \*(AqMy home is $HOME\*(Aq,
\&              TEXT    => \*(AqMessage is "$MESSAGE"\*(Aq );
\&
\& expand_strings( \e%vars, \e%ENV );
\&
\& # %vars now contains something like:
\& #   MESSAGE => \*(AqMy home is /home/user\*(Aq,
\& #   TEXT    => \*(AqMessage is "My home is /home/user"\*(Aq
.Ve
.SH "DESCRIPTION"
.IX Header "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 \f(CW$NAME\fR or \f(CW\*(C`${NAME}\*(C'\fR. In the former case,
the \f(CW\*(C`NAME\*(C'\fR 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 \f(CW\*(Aq}\*(Aq\fR.
.PP
The string may also contain literal dollar marks, escaped by \f(CW\*(C`\e$\*(C'\fR, and
literal escape marks, escaped by \f(CW\*(C`\e\e\*(C'\fR. These will be converted to \f(CW\*(C`$\*(C'\fR and
\&\f(CW\*(C`\e\*(C'\fR respectively on return.
.PP
While there are many other modules that also provide expansion such as this,
this module provides the function \f(CW\*(C`expand_strings()\*(C'\fR, which will perform
variable expansions in all the values in a given hash, where values can refer
to other values within the same hash.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.ie n .SS "$expanded = expand_string( $str, \e%vars )"
.el .SS "\f(CW$expanded\fP = expand_string( \f(CW$str\fP, \e%vars )"
.IX Subsection "$expanded = expand_string( $str, %vars )"
This function expands embedded variable references in the passed string, and
returns the expanded copy.
.ie n .IP "$str" 8
.el .IP "\f(CW$str\fR" 8
.IX Item "$str"
A string possibly containing variable expansions
.IP "\e%vars" 8
.IX Item "%vars"
Reference to a hash containing variable values
.IP "Returns" 8
.IX Item "Returns"
A string with variables expanded
.SS "expand_strings( \e%strs, \e%overlay )"
.IX Subsection "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 \f(CW\*(C`expand_string()\*(C'\fR.
Expansions may refer to other strings, or to values in the \f(CW\*(C`\f(CI%overlay\f(CW\*(C'\fR
hash. Values in the main variables hash take precidence over values in the
overlay.
.PP
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.
.IP "\e%strs" 8
.IX Item "%strs"
Reference to a hash containing variables to expand
.IP "\e%overlay" 8
.IX Item "%overlay"
Reference to a hash containing other variable values
.IP "Returns" 8
.IX Item "Returns"
Nothing
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
String::Interpolate \- Wrapper for builtin the Perl interpolation engine
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>