5 Symbol - manipulate Perl symbols and their names
12 open($sym, "filename");
16 ungensym $sym; # no effect
18 print qualify("x"), "\n"; # "Test::x"
19 print qualify("x", "FOO"), "\n" # "FOO::x"
20 print qualify("BAR::x"), "\n"; # "BAR::x"
21 print qualify("BAR::x", "FOO"), "\n"; # "BAR::x"
22 print qualify("STDOUT", "FOO"), "\n"; # "main::STDOUT" (global)
23 print qualify(\*x), "\n"; # returns \*x
24 print qualify(\*x, "FOO"), "\n"; # returns \*x
27 print { qualify_to_ref $fh } "foo!\n";
28 $ref = qualify_to_ref $name, $pkg;
32 C<Symbol::gensym> creates an anonymous glob and returns a reference
33 to it. Such a glob reference can be used as a file or directory
36 For backward compatibility with older implementations that didn't
37 support anonymous globs, C<Symbol::ungensym> is also provided.
38 But it doesn't do anything.
40 C<Symbol::qualify> turns unqualified symbol names into qualified
41 variable names (e.g. "myvar" -E<gt> "MyPackage::myvar"). If it is given a
42 second parameter, C<qualify> uses it as the default package;
43 otherwise, it uses the package of its caller. Regardless, global
44 variable names (e.g. "STDOUT", "ENV", "SIG") are always qualfied with
47 Qualification applies only to symbol names (strings). References are
48 left unchanged under the assumption that they are glob references,
49 which are qualified by their nature.
51 C<Symbol::qualify_to_ref> is just like C<Symbol::qualify> except that it
52 returns a glob ref rather than a symbol name, so you can use the result
53 even if C<use strict 'refs'> is in effect.
57 BEGIN { require 5.002; }
61 @EXPORT = qw(gensym ungensym qualify qualify_to_ref);
65 my $genpkg = "Symbol::";
68 my %global = map {$_ => 1} qw(ARGV ARGVOUT ENV INC SIG STDERR STDIN STDOUT);
71 # Note that we never _copy_ the glob; we just make a ref to it.
72 # If we did copy it, then SVf_FAKE would be set on the copy, and
73 # glob-specific behaviors (e.g. C<*$ref = \&func>) wouldn't work.
76 my $name = "GEN" . $genseq++;
77 my $ref = \*{$genpkg . $name};
78 delete $$genpkg{$name};
86 if (!ref($name) && index($name, '::') == -1 && index($name, "'") == -1) {
88 # Global names: special character, "^x", or other.
89 if ($name =~ /^([^a-z])|(\^[a-z])$/i || $global{$name}) {
93 $pkg = (@_ > 1) ? $_[1] : caller;
95 $name = $pkg . "::" . $name;
100 sub qualify_to_ref ($;$) {
101 return \*{ qualify $_[0], @_ > 1 ? $_[1] : caller };