1Symbol::Util(3) User Contributed Perl Documentation Symbol::Util(3)
2
6 Symbol::Util - Additional utils for Perl symbols manipulation
7
9 use Symbol::Util ':all';
10 my $caller = caller;
12 *{ fetch_glob("${caller}::foo") } = sub { "this is foo" };
13 my $coderef = fetch_glob("${caller}::bar", "CODE");
14 sub baz { 42; }
15 export_glob($caller, "baz");
16 print join "\n", keys %{ stash("main") };
18 delete_glob("${caller}::foo", "CODE");
20 use constant PI => 3.14159265;
22 delete_sub "PI"; # remove constant from public API
23 require YAML;
25 export_package(__PACKAGE__, "YAML", "Dump"); # import YAML::Dump
26 unexport_package(__PACKAGE, "YAML"); # remove imported symbols
27 no Symbol::Util; # clean all symbols imported from Symbol::Util
29
31 This module provides a set of additional functions useful for Perl
32 symbols manipulation.
33 All Perl symbols from the same package are organized as a stash. Each
35 symbol (glob) contains one or more of following slots: "SCALAR",
36 "ARRAY", "HASH", "CODE", "IO", "FORMAT". These slots are also
37 accessible as standard variables or bare words.
38 The Perl symbols table is directly accessible with typeglob prefix but
40 it can be difficult to read and problematic if strict mode is used.
41 Also the access to stash, glob and one of its slot have different
42 syntax notation.
43 "stash" and "fetch_glob" functions gets stash or glob without need to
45 use "no strict 'refs'".
46 "delete_glob" function allows to delete specific slot of symbol name
48 without deleting others.
49 "delete_sub" removes the symbol from class API. This symbol won't be
51 available as an object method.
52 "export_glob" function exports a glob to the target package.
54 "export_package" works like Exporter module and allows to export
56 symbols from one package to other.
57 "unexport_package" allows to delete previously exported symbols.
59
61 By default, the class does not export its symbols.
62 use Symbol::Util ':all';
64 Imports all available symbols.
65 no Symbol::Util;
67 Deletes all imported symbols from caller name space.
68
70 stash( name : Str ) : HashRef
71 Returns a reference to the stash for the specified name. If the
72 stash does not already exist then it will be created. The name of
73 the stash does not include the "::" at the end. It is safe to use
74 this function with "use strict 'refs'".
75 print join "\n", keys %{ stash("main") };
77 fetch_glob( name : Str ) : GlobRef
79 fetch_glob( name : Str, slot : Str ) : Ref
80 Returns a reference to the glob for the specified symbol name. If
81 the symbol does not already exist then it will be created. If the
82 symbol name is unqualified then it will be looked up in the calling
83 package. It is safe to use this function with "use strict 'refs'".
84 If the slot argument is defined and this slot contains defined
86 value, reference to this value is returned. The slot argument can
87 be one of the following strings: "SCALAR", "ARRAY", "HASH", "CODE",
88 "IO", "FORMAT").
89 my $caller = caller;
91 *{ fetch_glob("${caller}::foo") } = sub { "this is foo" };
92 my $coderef = fetch_glob("${caller}::foo", "CODE");
93 list_glob_slots( name ) : Maybe[Array]
95 Returns a list of slot names for glob with specified name which
96 contain defined value. If the glob is undefined, the "undef" value
97 is returned. If the glob is defined and has no defined slots, the
98 empty list is returned.
99 The "SCALAR" slot is used only if it contains defined value.
101 my $foo = 42;
103 my @foo = (1, 2);
104 sub foo { 1; };
105 print join ",", list_glob_slots("foo"); # SCALAR,ARRAY,CODE
106 export_glob( target, name : Str ) : GlobRef
108 export_glob( target, name : Str, slots : Array ) : Ref
109 Exports a glob name to the target package. Optionally exports only
110 specified slots of the glob.
111 sub my_function { ... };
113 sub import {
114 my $caller = caller;
115 export_glob($caller, "my_function");
116 }
117 delete_glob( name : Str, slots : Array[Str] ) : Maybe[GlobRef]
119 Deletes the specified symbol name if slots are not specified, or
120 deletes the specified slots in the symbol name (could be one or
121 more of the following strings: "SCALAR", "ARRAY", "HASH", "CODE",
122 "IO", "FORMAT").
123 Function returns the glob reference if there are any slots defined.
125 our $FOO = 1;
127 sub FOO { "bar" };
128 delete_glob("FOO", "CODE");
130 print $FOO; # prints "1"
132 FOO(); # error: sub not found
133 delete_sub( name : Str ) : Maybe[GlobRef]
135 Deletes (or hides) the specified subroutine name from class API.
136 It means that this subroutine will be no longer available as a
137 class method. The purpose of this function is the same as
138 namespace::clean pragma has: it cleans a package's namespace from
139 unwanted subroutines. Function doesn't delete other slots than
140 "CODE" slot of the glob.
141 Function returns the glob reference if there are any other slots
143 still defined than <CODE> slot.
144 package My::Class;
146 use constant PI => 3.14159265;
148 use Symbol::Util 'delete_sub';
150 delete_sub "PI"; # remove constant from public API
151 no Symbol::Util; # remove also Symbol::Util::* from public API
152 sub area {
154 my ($self, $r) = @_;
155 return PI * $r ** 2;
156 }
157 print My::Class->area(2); # prints 12.5663706
159 print My::Class->PI; # Can't locate object method
160 export_package( target : Str, package : Str, names : Array[Str] ) :
162 Bool
163 export_package( target : Str, package : Str, spec : HashRef, names :
164 Array[Str] ) : Bool
165 Exports symbols from package to target. If spec is defined as hash
166 reference, it contains the specification for exporter. Otherwise
167 the standard global variables of package are used (@EXPORT,
168 @EXPORT_OK and %EXPORT_TAGS) to build the specification for
169 exporter. The optional list of names defines an import list.
170 The spec is a reference to hash with following keys:
172 EXPORT
174 Contains the list of default imports. It is the same as
175 @EXPORT variable.
176 OK Contains the list of allowed imports. It is the same as
178 @EXPORT_OK variable.
179 TAGS
181 Contains the hash with tags. It is the same as %EXPORT_TAGS
182 variable.
183 See Exporter documentation for explanation of these global
185 variables and list of names.
186 The "export_package" function can export symbols from an external
188 package to an external package. This function can also be used as
189 a helper in "import" method.
190 package My::Package;
192 sub myfunc { };
193 sub import {
194 my ($package, @names) = @_;
195 my $caller = caller();
196 return export_package($caller, $package, {
197 OK => [ qw( myfunc ) ],
198 }, @names);
199 };
200 All exported symbols are tracked and later can be removed with
202 "unexport_package" function.
203 The function returns true value if there were no errors.
205 unexport_package( target : Str, package : Str ) : Bool
207 Deletes symbols previously exported from package to target with
208 "export_package" function. If the symbol was "CODE" reference it
209 is deleted with "delete_sub" function. Otherwise it is deleted
210 with "delete_glob" function with proper slot as an argument.
211 Deleting with "delete_sub" function means that this symbol is not
213 available via class API as an object method.
214 require YAML;
216 export_package(__PACKAGE__, "YAML", "Dump");
217 unexport_package(__PACKAGE__, "YAML");
218 print Dump @INC; # OK
219 __PACKAGE__->Dump; # Can't locate object method
220 This function can be used as a helper in "unimport" method.
222 package My::Package;
224 sub unimport {
225 my ($package, @names) = @_;
226 my $caller = caller();
227 return unexport_package($caller, $package);
228 };
229 package main;
231 use My::Package qw(something);
232 no My::Package;
233 main->something; # Can't locate object method
234 The function returns true value if there were no errors.
236
238 Symbol, Sub::Delete, namespace::clean, Exporter.
239
241 "fetch_glob" returns "undef" value if "SCALAR" slot contains "undef"
242 value.
243 "delete_glob" and "delete_sub" delete "SCALAR" slot if it exists and
245 contains "undef" value.
246 "delete_glob" and "delete_sub" always delete "FORMAT" slot.
248 If you find the bug or want to implement new features, please report it
250 at <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Symbol-Util>
251
253 Piotr Roszatycki <dexter@cpan.org>
254
256 Copyright (c) 2009, 2012 Piotr Roszatycki <dexter@cpan.org>.
257 This is free software; you can redistribute it and/or modify it under
259 the same terms as perl itself.
260 See <http://dev.perl.org/licenses/artistic.html>
262perl v5.36.0 2023-01-20 Symbol::Util(3)