diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3pm/Symbol.3pm')
| -rw-r--r-- | upstream/mageia-cauldron/man3pm/Symbol.3pm | 135 |
1 files changed, 135 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/Symbol.3pm b/upstream/mageia-cauldron/man3pm/Symbol.3pm new file mode 100644 index 00000000..6b283855 --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/Symbol.3pm @@ -0,0 +1,135 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "Symbol 3pm" +.TH Symbol 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +Symbol \- manipulate Perl symbols and their names +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& use Symbol; +\& +\& $sym = gensym; +\& open($sym, \*(Aq<\*(Aq, "filename"); +\& $_ = <$sym>; +\& # etc. +\& +\& ungensym $sym; # no effect +\& +\& # replace *FOO{IO} handle but not $FOO, %FOO, etc. +\& *FOO = geniosym; +\& +\& print qualify("x"), "\en"; # "main::x" +\& print qualify("x", "FOO"), "\en"; # "FOO::x" +\& print qualify("BAR::x"), "\en"; # "BAR::x" +\& print qualify("BAR::x", "FOO"), "\en"; # "BAR::x" +\& print qualify("STDOUT", "FOO"), "\en"; # "main::STDOUT" (global) +\& print qualify(\e*x), "\en"; # returns \e*x +\& print qualify(\e*x, "FOO"), "\en"; # returns \e*x +\& +\& use strict refs; +\& print { qualify_to_ref $fh } "foo!\en"; +\& $ref = qualify_to_ref $name, $pkg; +\& +\& use Symbol qw(delete_package); +\& delete_package(\*(AqFoo::Bar\*(Aq); +\& print "deleted\en" unless exists $Foo::{\*(AqBar::\*(Aq}; +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\f(CW\*(C`Symbol::gensym\*(C'\fR creates an anonymous glob and returns a reference +to it. Such a glob reference can be used as a file or directory +handle. +.PP +For backward compatibility with older implementations that didn't +support anonymous globs, \f(CW\*(C`Symbol::ungensym\*(C'\fR is also provided. +But it doesn't do anything. +.PP +\&\f(CW\*(C`Symbol::geniosym\*(C'\fR creates an anonymous IO handle. This can be +assigned into an existing glob without affecting the non-IO portions +of the glob. +.PP +\&\f(CW\*(C`Symbol::qualify\*(C'\fR turns unqualified symbol names into qualified +variable names (e.g. "myvar" \-> "MyPackage::myvar"). If it is given a +second parameter, \f(CW\*(C`qualify\*(C'\fR uses it as the default package; +otherwise, it uses the package of its caller. Regardless, global +variable names (e.g. "STDOUT", "ENV", "SIG") are always qualified with +"main::". +.PP +Qualification applies only to symbol names (strings). References are +left unchanged under the assumption that they are glob references, +which are qualified by their nature. +.PP +\&\f(CW\*(C`Symbol::qualify_to_ref\*(C'\fR is just like \f(CW\*(C`Symbol::qualify\*(C'\fR except that it +returns a glob ref rather than a symbol name, so you can use the result +even if \f(CW\*(C`use strict \*(Aqrefs\*(Aq\*(C'\fR is in effect. +.PP +\&\f(CW\*(C`Symbol::delete_package\*(C'\fR wipes out a whole package namespace. Note +this routine is not exported by default\-\-you may want to import it +explicitly. +.SH BUGS +.IX Header "BUGS" +\&\f(CW\*(C`Symbol::delete_package\*(C'\fR is a bit too powerful. It undefines every symbol that +lives in the specified package. 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 \f(CW\*(C`Foo\*(C'\fR may stop working after you delete \f(CW\*(C`Foo\*(C'\fR, even if +you reload the \f(CW\*(C`Foo\*(C'\fR module afterwards. |