String::Expand(3pm)

✨ NAME ✨

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

okay so bestie, this is String::Expand, a Perl module in the 3pm section of the perl manual (user contributed perl documentation, we love a community moment 🫶). It's giving... string utils that go brrr on variables that refer to each other. iykyk.

---

🌸 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"'

see how MESSAGE used $HOME from the environment and then TEXT went and used $MESSAGE?? that's the self-referential set thing, it's iconic honestly 💅

---

🦋 DESCRIPTION 🦋

This module is literally just utility functions for expanding variables that are embedded inside a string. no cap.

Variable references live inside your strings in a form that's similar to the Bourne shell, namely $NAME or "${NAME}". Two flavors, two rules, stay with me:

• In the $NAME form, the NAME must consist of a capital letter or an underscore, and it may be followed by zero or more capital letters, digits or underscores. that's the vibe check, all caps or underscore only, periodt.
• In the "${NAME}" form, the name can consist of any characters, but it gets terminated by the first close brace character }. so brace it up if you need chaos characters 🌈

Your string can also contain literal dollar marks, escaped by "\$", and literal escape marks, escaped by "\\". These get converted to $ and \ respectively on return. cute, right? 🎀

Now. yes, there are many other modules out there that also provide expansion like this. not me being shady, it's just facts. BUT this one gives you the function expand_strings(), which will perform variable expansions in all the values in a given hash, where those values can refer to other values within the same hash. that's the whole point. that's the main character energy right there 👑

---

👑 FUNCTIONS 👑

💜 $expanded = expand_string( $str, \%vars )

This one expands the embedded variable references in the string you hand it, and returns you the expanded copy. so simple. so slay. ✨

• $str — a string possibly containing variable expansions
• \%vars — a 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 the variable names embedded in any of them, in the same form as the string you'd pass to expand_string(). The expansions may refer to other strings, or to values in the %overlay hash. and listen — values in the main variables hash take precedence over values in the overlay. main hash wins, no debate 🫶

where values refer to other values, you gotta be careful to avoid cycles, bestie. if a cycle is detected while attempting to expand the values, then an exception is thrown. 💀 so like, don't do that. respect the cycle rule.

• \%strs — a reference to a hash containing variables to expand
• \%overlay — a reference to a hash containing other variable values
• Returns — nothing

---

🌈 SEE ALSO 🌈

• String::Interpolate — a wrapper for the builtin Perl interpolation engine 🌸

---

🎀 AUTHOR 🎀

Paul Evans <leonerd@leonerd.org.uk> — absolute legend, we stan 💖

---

okay so that's the whole page, bestie. this was String::Expand(3pm) from the perl manual, part of the user contributed perl documentation, and the footer says it's from perl v5.36.0, dated 2022-10-13. go forth and expand those strings, you're gonna ate it up fr fr 💅✨🦋