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 "stash" and "fetch_glob" functions gets stash or glob without need to
35 use "no strict 'refs'".
36 "delete_glob" function allows to delete specific slot of symbol name
38 without deleting others.
39 "delete_sub" removes the symbol from class API. This symbol won't be
41 available as an object method.
42 "export_package" works like Exporter module and allows to export
44 symbols from one package to other.
45 "unexport_package" allows to delete previously exported symbols.
47
49 By default, the class does not export its symbols.
50 use Symbol::Util ':all';
52 Imports all available symbols.
53 no Symbol::Util;
55 Deletes all imported symbols from caller name space.
56
58 stash( name : Str ) : HashRef
59 Returns a refernce to the stash for the specified name. If the
60 stash does not already exists it will be created. The name of the
61 stash does not include the "::" at the end. It is safe to use this
62 function with "use strict 'refs'".
63 This function is taken from Kurila, a dialect of Perl.
65 print join "\n", keys %{ Symbol::stash("main") };
67 fetch_glob( name : Str ) : GlobRef
69 fetch_glob( name : Str, slot : Str ) : Ref
70 Returns a reference to the glob for the specified symbol name. If
71 the symbol does not already exists it will be created. If the
72 symbol name is unqualified it will be looked up in the calling
73 package. It is safe to use this function with "use strict 'refs'".
74 If slot argument is defined and this slot has defined value,
76 reference to its value is returned. The slot argument can be one
77 of the following strings: "SCALAR", "ARRAY", "HASH", "CODE", "IO",
78 "FORMAT").
79 This function is taken from Kurila, a dialect of Perl.
81 my $caller = caller;
83 *{ fetch_glob("${caller}::foo") } = sub { "this is foo" };
84 my $coderef = fetch_glob("${caller}::foo", "CODE");
85 list_glob_slots( name ) : Maybe[Array]
87 Returns a list of slot names for glob with specified name which
88 have defined value. If the glob is undefined, the "undef" value is
89 returned. If the glob is defined and has no defined slots, the
90 empty list is returned.
91 The "SCALAR" slot is used only if it contains defined value.
93 print join ",", list_glob_slots("foo");
95 export_glob( target, name : Str ) : GlobRef
97 export_glob( target, name : Str, slots : Array ) : Ref
98 Exports a glob name to the target package. Optionally exports only
99 specified slots of the glob.
100 sub my_function { ... };
102 sub import {
103 my $caller = caller;
104 export_glob($caller, "my_function");
105 }
106 delete_glob( name : Str, slots : Array[Str] ) : Maybe[GlobRef]
108 Deletes the specified symbol name if slots are not specified, or
109 deletes the specified slots in the symbol name (could be one or
110 more of the following strings: "SCALAR", "ARRAY", "HASH", "CODE",
111 "IO", "FORMAT").
112 Function returns the glob reference if there are any slots defined.
114 our $FOO = 1;
116 sub FOO { "bar" };
117 delete_glob("FOO", "CODE");
119 print $FOO; # prints "1"
121 FOO(); # error: sub not found
122 delete_sub( name : Str ) : Maybe[GlobRef]
124 Deletes (or hides) the specified subroutine name from class API.
125 It means that this subroutine will be no longer available as the
126 class method. The purpose of this function is the same as
127 namespace::clean pragma has.
128 Function returns the glob reference if there are any other slots
130 still defined than <CODE> slot.
131 package My::Class;
133 use constant PI => 3.14159265;
135 use Symbol::Util 'delete_sub';
137 delete_sub "PI"; # remove constant from public API
138 no Symbol::Util; # remove also Symbol::Util::* from public API
139 sub area {
141 my ($self, $r) = @_;
142 return PI * $r ** 2
143 }
144 print My::Class->area(2); # prints 12.5663706
146 print My::Class->PI; # can't locate object method
147 export_package( target : Str, package : Str, names : Array[Str] ) :
149 Bool
150 export_package( target : Str, package : Str, spec : HashRef, names :
151 Array[Str] ) : Bool
152 Exports symbols from package to target. If spec is defined as hash
153 reference, it contains the specification for exporter. Otherwise
154 the standard global variables of package are used (@EXPORT,
155 @EXPORT_OK and %EXPORT_TAGS) to build the specification for
156 exporter. The optional list of names defines an import list.
157 The spec is a reference to hash with following keys:
159 EXPORT
161 Contains the list of default imports. It is the same as
162 @EXPORT variable.
163 OK Contains the list of allowed imports. It is the same as
165 @EXPORT_OK variable.
166 TAGS
168 Contains the hash with tags. It is the same as %EXPORT_TAGS
169 variable.
170 See Exporter documentation for explanation of these global
172 variables and list of names.
173 The "export_package" function can export symbols from an external
175 package to an external package. This function can also be used as
176 a helper in "import" method.
177 package My::Package;
179 sub myfunc { };
180 sub import {
181 my ($package, @names) = @_;
182 my $caller = caller();
183 return export_package($caller, $package, {
184 OK => [ qw( myfunc ) ],
185 }, @names);
186 };
187 All exported symbols are tracked and later can be removed with
189 "unexport_package" function.
190 The function returns true value if there were no errors.
192 unexport_package( target, package ) : Bool
194 Deletes symbols previously exported from package to target with
195 "export_package" function. If the symbol was "CODE" reference it
196 is deleted with "delete_sub" function. Otherwise it is deleted
197 with "delete_glob" function with proper slot as an argument.
198 Deleting with "delete_sub" function means that this symbol is not
200 available via class API as an object method.
201 require YAML;
203 export_package(__PACKAGE__, "YAML", "dump");
204 unexport_package(__PACKAGE__, "YAML");
205 This function can be used as a helper in "unimport" method.
207 package My::Package;
209 sub unimport {
210 my ($package, @names) = @_;
211 my $caller = caller();
212 return unexport_package($caller, $package);
213 };
214 package main;
216 use My::Package qw(something);
217 no My::Package;
218 main->something; # Can't locate object method
219 The function returns true value if there were no errors.
221
223 Symbol, Sub::Delete, namespace::clean, Exporter.
224
226 "fetch_glob" returns "undef" value if "SCALAR" slot contains "undef"
227 value.
228 "delete_glob" deletes "SCALAR" slot if it exists and contains "undef"
230 value.
231 "delete_glob" always deletes "FORMAT" slot.
233 If you find the bug or want to implement new features, please report it
235 at http://rt.cpan.org/NoAuth/Bugs.html?Dist=Symbol-Util
236 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Symbol-Util>
237
239 Piotr Roszatycki <dexter@cpan.org>
240
242 Copyright (C) 2009 by Piotr Roszatycki <dexter@cpan.org>.
243 This program is free software; you can redistribute it and/or modify it
245 under the same terms as Perl itself.
246 See <http://www.perl.com/perl/misc/Artistic.html>
248perl v5.12.1 2010-06-22 Symbol::Util(3)