Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Symbol.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Symbol 3pm"
61 .TH Symbol 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Symbol \- manipulate Perl symbols and their names
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use Symbol;
72 \&
73 \& $sym = gensym;
74 \& open($sym, \*(Aq<\*(Aq, "filename");
75 \& $_ = <$sym>;
76 \& # etc.
77 \&
78 \& ungensym $sym; # no effect
79 \&
80 \& # replace *FOO{IO} handle but not $FOO, %FOO, etc.
81 \& *FOO = geniosym;
82 \&
83 \& print qualify("x"), "\en"; # "main::x"
84 \& print qualify("x", "FOO"), "\en"; # "FOO::x"
85 \& print qualify("BAR::x"), "\en"; # "BAR::x"
86 \& print qualify("BAR::x", "FOO"), "\en"; # "BAR::x"
87 \& print qualify("STDOUT", "FOO"), "\en"; # "main::STDOUT" (global)
88 \& print qualify(\e*x), "\en"; # returns \e*x
89 \& print qualify(\e*x, "FOO"), "\en"; # returns \e*x
90 \&
91 \& use strict refs;
92 \& print { qualify_to_ref $fh } "foo!\en";
93 \& $ref = qualify_to_ref $name, $pkg;
94 \&
95 \& use Symbol qw(delete_package);
96 \& delete_package(\*(AqFoo::Bar\*(Aq);
97 \& print "deleted\en" unless exists $Foo::{\*(AqBar::\*(Aq};
98 .Ve
99 .SH DESCRIPTION
100 .IX Header "DESCRIPTION"
101 \&\f(CW\*(C`Symbol::gensym\*(C'\fR creates an anonymous glob and returns a reference
102 to it. Such a glob reference can be used as a file or directory
103 handle.
104 .PP
105 For backward compatibility with older implementations that didn\*(Aqt
106 support anonymous globs, \f(CW\*(C`Symbol::ungensym\*(C'\fR is also provided.
107 But it doesn\*(Aqt do anything.
108 .PP
109 \&\f(CW\*(C`Symbol::geniosym\*(C'\fR creates an anonymous IO handle. This can be
110 assigned into an existing glob without affecting the non\-IO portions
111 of the glob.
112 .PP
113 \&\f(CW\*(C`Symbol::qualify\*(C'\fR turns unqualified symbol names into qualified
114 variable names (e.g. "myvar" \-> "MyPackage::myvar"). If it is given a
115 second parameter, \f(CW\*(C`qualify\*(C'\fR uses it as the default package;
116 otherwise, it uses the package of its caller. Regardless, global
117 variable names (e.g. "STDOUT", "ENV", "SIG") are always qualified with
118 "main::".
119 .PP
120 Qualification applies only to symbol names (strings). References are
121 left unchanged under the assumption that they are glob references,
122 which are qualified by their nature.
123 .PP
124 \&\f(CW\*(C`Symbol::qualify_to_ref\*(C'\fR is just like \f(CW\*(C`Symbol::qualify\*(C'\fR except that it
125 returns a glob ref rather than a symbol name, so you can use the result
126 even if \f(CW\*(C`use strict \*(Aqrefs\*(Aq\*(C'\fR is in effect.
127 .PP
128 \&\f(CW\*(C`Symbol::delete_package\*(C'\fR wipes out a whole package namespace. Note
129 this routine is not exported by default\-\-you may want to import it
130 explicitly.
131 .SH BUGS
132 .IX Header "BUGS"
133 \&\f(CW\*(C`Symbol::delete_package\*(C'\fR is a bit too powerful. It undefines every symbol that
134 lives in the specified package. Since perl, for performance reasons, does not
135 perform a symbol table lookup each time a function is called or a global
136 variable is accessed, some code that has already been loaded and that makes use
137 of symbols in package \f(CW\*(C`Foo\*(C'\fR may stop working after you delete \f(CW\*(C`Foo\*(C'\fR, even if
138 you reload the \f(CW\*(C`Foo\*(C'\fR module afterwards.