5 Symbol - manipulate Perl symbols and their names
12 open($sym, "filename");
16 ungensym $sym; # no effect
18 # replace *FOO{IO} handle but not $FOO, %FOO, etc.
21 print qualify("x"), "\n"; # "Test::x"
22 print qualify("x", "FOO"), "\n" # "FOO::x"
23 print qualify("BAR::x"), "\n"; # "BAR::x"
24 print qualify("BAR::x", "FOO"), "\n"; # "BAR::x"
25 print qualify("STDOUT", "FOO"), "\n"; # "main::STDOUT" (global)
26 print qualify(\*x), "\n"; # returns \*x
27 print qualify(\*x, "FOO"), "\n"; # returns \*x
30 print { qualify_to_ref $fh } "foo!\n";
31 $ref = qualify_to_ref $name, $pkg;
33 use Symbol qw(delete_package);
34 delete_package('Foo::Bar');
35 print "deleted\n" unless exists $Foo::{'Bar::'};
39 C<Symbol::gensym> creates an anonymous glob and returns a reference
40 to it. Such a glob reference can be used as a file or directory
43 For backward compatibility with older implementations that didn't
44 support anonymous globs, C<Symbol::ungensym> is also provided.
45 But it doesn't do anything.
47 C<Symbol::geniosym> creates an anonymous IO handle. This can be
48 assigned into an existing glob without affecting the non-IO portions
51 C<Symbol::qualify> turns unqualified symbol names into qualified
52 variable names (e.g. "myvar" -E<gt> "MyPackage::myvar"). If it is given a
53 second parameter, C<qualify> uses it as the default package;
54 otherwise, it uses the package of its caller. Regardless, global
55 variable names (e.g. "STDOUT", "ENV", "SIG") are always qualified with
58 Qualification applies only to symbol names (strings). References are
59 left unchanged under the assumption that they are glob references,
60 which are qualified by their nature.
62 C<Symbol::qualify_to_ref> is just like C<Symbol::qualify> except that it
63 returns a glob ref rather than a symbol name, so you can use the result
64 even if C<use strict 'refs'> is in effect.
66 C<Symbol::delete_package> wipes out a whole package namespace. Note
67 this routine is not exported by default--you may want to import it
72 C<Symbol::delete_package> is a bit too powerful. It undefines every symbol
73 that lives in the specified package and in its sub-packages. Since perl,
74 for performance reasons, does not perform a symbol table lookup each time
75 a function is called or a global variable is accessed, some code that has
76 already been loaded and that makes use of symbols in package C<Foo> may
77 stop working after you delete C<Foo>, even if you reload the C<Foo> module
82 BEGIN { require 5.005; }
86 @EXPORT = qw(gensym ungensym qualify qualify_to_ref);
87 @EXPORT_OK = qw(delete_package geniosym);
91 my $genpkg = "Symbol::";
94 my %global = map {$_ => 1} qw(ARGV ARGVOUT ENV INC SIG STDERR STDIN STDOUT);
97 # Note that we never _copy_ the glob; we just make a ref to it.
98 # If we did copy it, then SVf_FAKE would be set on the copy, and
99 # glob-specific behaviors (e.g. C<*$ref = \&func>) wouldn't work.
102 my $name = "GEN" . $genseq++;
103 my $ref = \*{$genpkg . $name};
104 delete $$genpkg{$name};
110 # force the IO slot to be filled
119 if (!ref($name) && index($name, '::') == -1 && index($name, "'") == -1) {
121 # Global names: special character, "^xyz", or other.
122 if ($name =~ /^(([^a-z])|(\^[a-z_]+))\z/i || $global{$name}) {
123 # RGS 2001-11-05 : translate leading ^X to control-char
124 $name =~ s/^\^([a-z_])/'qq(\c'.$1.')'/eei;
128 $pkg = (@_ > 1) ? $_[1] : caller;
130 $name = $pkg . "::" . $name;
135 sub qualify_to_ref ($;$) {
136 return \*{ qualify $_[0], @_ > 1 ? $_[1] : caller };
142 sub delete_package ($) {
145 # expand to full symbol table name if needed
147 unless ($pkg =~ /^main::.*::$/) {
148 $pkg = "main$pkg" if $pkg =~ /^::/;
149 $pkg = "main::$pkg" unless $pkg =~ /^main::/;
150 $pkg .= '::' unless $pkg =~ /::$/;
153 my($stem, $leaf) = $pkg =~ m/(.*::)(\w+::)$/;
154 my $stem_symtab = *{$stem}{HASH};
155 return unless defined $stem_symtab and exists $stem_symtab->{$leaf};
158 # free all the symbols in the package
160 my $leaf_symtab = *{$stem_symtab->{$leaf}}{HASH};
161 foreach my $name (keys %$leaf_symtab) {
162 undef *{$pkg . $name};
165 # delete the symbol table
168 delete $stem_symtab->{$leaf};