Symbol(3perl)

💖 Symbol — manipulate Perl symbols and their names 💖

okay bestie, we're in Symbol(3perl) territory — that's the Perl Programmers Reference Guide btw, she's iconic, she's part of perl, and she is literally about wrangling Perl symbols and their names 🎀

No cap, this module is the one you call when you need to make globs out of thin air, qualify names, or just. delete an entire package like it's nothing. main character energy fr fr. Let's go ✨

---

🌸 SYNOPSIS 🌸

use Symbol;

$sym = gensym;
open($sym, '<', "filename");
$_ = <$sym>;
# etc.

ungensym $sym;      # no effect

# replace *FOO{IO} handle but not $FOO, %FOO, etc.
*FOO = geniosym;

print qualify("x"), "\n";              # "main::x"
print qualify("x", "FOO"), "\n";       # "FOO::x"
print qualify("BAR::x"), "\n";         # "BAR::x"
print qualify("BAR::x", "FOO"), "\n";  # "BAR::x"
print qualify("STDOUT", "FOO"), "\n";  # "main::STDOUT" (global)
print qualify(\*x), "\n";              # returns \*x
print qualify(\*x, "FOO"), "\n";       # returns \*x

use strict refs;
print { qualify_to_ref $fh } "foo!\n";
$ref = qualify_to_ref $name, $pkg;

use Symbol qw(delete_package);
delete_package('Foo::Bar');
print "deleted\n" unless exists $Foo::{'Bar::'};

look at her. the comments say everything. 💅

---

✨ DESCRIPTION ✨

Symbol::gensym creates an anonymous glob and returns a reference to it 🦋. And like, a glob reference like that can totally be used as a file handle or a directory handle. so handy.

For backward compat with the olden-days implementations that didn't support anonymous globs, Symbol::ungensym is also provided. But bestie… it doesn't do anything. not a single thing. it's giving decorative. 😭 It's still there, it's just vibing. (See: ungensym $sym; # no effect up in the synopsis. no effect!! i told you!!)

Symbol::geniosym creates an anonymous IO handle 🌈. The glow-up here is that you can assign it into an existing glob without affecting the non-IO portions of that glob. so *FOO{IO} gets replaced but $FOO, %FOO and friends stay exactly where they were. obsessed. 🫶

Symbol::qualify turns unqualified symbol names into qualified variable names — like "myvar" becomes "MyPackage::myvar", slay ✨. Give it a second parameter and qualify uses that as the default package; otherwise it just uses the package of its caller. Either way, global variable names (think "STDOUT", "ENV", "SIG") are always qualified with "main::". no exceptions, periodt. 👑

Also, real talk: qualification applies only to symbol names (strings) 💖. References are left completely unchanged, on the assumption that they're glob references — which are already qualified by their very nature. she said i don't need to do anything, they came out the womb qualified. 🧚

Symbol::qualify_to_ref is just like Symbol::qualify, except it hands you back a glob ref instead of a symbol name 🌸. Which means you can actually use the result even when use strict 'refs' is in effect. chef's kiss, no notes.

Symbol::delete_package wipes out a whole package namespace 💀. Heads up though: this routine is not exported by default — you may want to import it explicitly. so write use Symbol qw(delete_package); like the synopsis does, or you'll be standing there like ??? 🙈

---

💀 BUGS 💀

ngl, Symbol::delete_package is a bit too powerful. Like, main-character-with-a-nuke energy. It undefines every symbol that lives in the specified package 😭.

Here's the tea: since perl, for performance reasons, does not perform a symbol table lookup each time a function is called or a global variable is accessed, some code that has already been loaded — and that makes use of symbols in package Foo — may just… stop working after you delete Foo. Even if you reload the Foo module afterwards. yeah. even then. 🫠 So be careful with this one, bestie, it's not playing.

---

👑 SEE ALSO 👑

there are no SEE ALSO references in this page, and honestly? she doesn't need them. she's self-sufficient. 🌈

---

mwah 💖 written by the Perl maintainers, perl v5.44.0, dated 2026-10-17 — that's the version and date bestie, go off, this page is iconic and you're gonna qualify names like a legend ⭐🧚💜