Symbol (Programming Perl)

32.39. Symbol

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

use Symbol "gensym";
$sym1 = getsym();       # Returns new, anonymous typeglob.
$sym2 = getsym();       # Yet another new, anonymous typeglob.

package Demo;
use Symbol "qualify";
$sym = qualify("x");              # "Demo::x"
$sym = qualify("x", "Foo");       # "Foo::x"
$sym = qualify("Bar::x");         # "Bar::x"
$sym = qualify("Bar::x", "Foo");  # "Bar::x"

use Symbol "qualify_to_ref";
sub pass_handle(*) {
    my $fh = qualify_to_ref(shift, caller);
    ...
}
# Now you can call pass_handle with FH, "FH", *FH, or \*FH.

The Symbol module provides functions to help manipulate global names: typeglobs, format names, filehandles, package symbol tables, and anything else you might want to name via a symbol table. The delete_package function completely clears out a package's namespace (effectively anonymizing any extra references to the symbol table's referents, including references from precompiled code). The gensym function returns an anonymous typeglob each time it is called. (This function isn't used so much these days, now that undefined scalars autovivify into proper filehandles when used as arguments to open, pipe, socket, and the like).

The qualify function takes a name that may or may not be completely package-qualified, and returns a name that is. If it needs to prepend the package name, it will use the name specified via the second argument (or if omitted, your current package name). The qualify_to_ref function works similarly, but produces a reference to the typeglob the symbol would represent. This is important in functions that accept filehandles, directory handles, or format names as arguments but don't require these to be passed by reference. For example, functions prototyped with a typeglob accept any of these forms, but don't automatically convert barewords to symbol table references. By converting that argument with qualify_to_ref, you can now use the supplied handle even with strict refs in effect. You may also bless it into objectdom, since it's a proper reference.