1Symbol::Util(3)       User Contributed Perl Documentation      Symbol::Util(3)
2
3
4

NAME

6       Symbol::Util - Additional utils for Perl symbols manipulation
7

SYNOPSIS

9         use Symbol::Util ':all';
10
11         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
17         print join "\n", keys %{ stash("main") };
18
19         delete_glob("${caller}::foo", "CODE");
20
21         use constant PI => 3.14159265;
22         delete_sub "PI";   # remove constant from public API
23
24         require YAML;
25         export_package(__PACKAGE__, "YAML", "Dump");   # import YAML::Dump
26         unexport_package(__PACKAGE, "YAML");   # remove imported symbols
27
28         no Symbol::Util;   # clean all symbols imported from Symbol::Util
29

DESCRIPTION

31       This module provides a set of additional functions useful for Perl
32       symbols manipulation.
33
34       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
39       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
44       "stash" and "fetch_glob" functions gets stash or glob without need to
45       use "no strict 'refs'".
46
47       "delete_glob" function allows to delete specific slot of symbol name
48       without deleting others.
49
50       "delete_sub" removes the symbol from class API.  This symbol won't be
51       available as an object method.
52
53       "export_glob" function exports a glob to the target package.
54
55       "export_package" works like Exporter module and allows to export
56       symbols from one package to other.
57
58       "unexport_package" allows to delete previously exported symbols.
59

USAGE

61       By default, the class does not export its symbols.
62
63       use Symbol::Util ':all';
64           Imports all available symbols.
65
66       no Symbol::Util;
67           Deletes all imported symbols from caller name space.
68

FUNCTIONS

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
76             print join "\n", keys %{ stash("main") };
77
78       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
85           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
90             my $caller = caller;
91             *{ fetch_glob("${caller}::foo") } = sub { "this is foo" };
92             my $coderef = fetch_glob("${caller}::foo", "CODE");
93
94       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
100           The "SCALAR" slot is used only if it contains defined value.
101
102             my $foo = 42;
103             my @foo = (1, 2);
104             sub foo { 1; };
105             print join ",", list_glob_slots("foo");   # SCALAR,ARRAY,CODE
106
107       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
112             sub my_function { ... };
113             sub import {
114                 my $caller = caller;
115                 export_glob($caller, "my_function");
116             }
117
118       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
124           Function returns the glob reference if there are any slots defined.
125
126             our $FOO = 1;
127             sub FOO { "bar" };
128
129             delete_glob("FOO", "CODE");
130
131             print $FOO;  # prints "1"
132             FOO();       # error: sub not found
133
134       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
142           Function returns the glob reference if there are any other slots
143           still defined than <CODE> slot.
144
145             package My::Class;
146
147             use constant PI => 3.14159265;
148
149             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
153             sub area {
154                 my ($self, $r) = @_;
155                 return PI * $r ** 2;
156             }
157
158             print My::Class->area(2);   # prints 12.5663706
159             print My::Class->PI;        # Can't locate object method
160
161       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
171           The spec is a reference to hash with following keys:
172
173           EXPORT
174               Contains the list of default imports.  It is the same as
175               @EXPORT variable.
176
177           OK  Contains the list of allowed imports.  It is the same as
178               @EXPORT_OK variable.
179
180           TAGS
181               Contains the hash with tags.  It is the same as %EXPORT_TAGS
182               variable.
183
184           See Exporter documentation for explanation of these global
185           variables and list of names.
186
187           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
191             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
201           All exported symbols are tracked and later can be removed with
202           "unexport_package" function.
203
204           The function returns true value if there were no errors.
205
206       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
212           Deleting with "delete_sub" function means that this symbol is not
213           available via class API as an object method.
214
215             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
221           This function can be used as a helper in "unimport" method.
222
223             package My::Package;
224             sub unimport {
225                 my ($package, @names) = @_;
226                 my $caller = caller();
227                 return unexport_package($caller, $package);
228             };
229
230             package main;
231             use My::Package qw(something);
232             no My::Package;
233             main->something;   # Can't locate object method
234
235           The function returns true value if there were no errors.
236

SEE ALSO

238       Symbol, Sub::Delete, namespace::clean, Exporter.
239

BUGS

241       "fetch_glob" returns "undef" value if "SCALAR" slot contains "undef"
242       value.
243
244       "delete_glob" and "delete_sub" delete "SCALAR" slot if it exists and
245       contains "undef" value.
246
247       "delete_glob" and "delete_sub" always delete "FORMAT" slot.
248
249       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

AUTHOR

253       Piotr Roszatycki <dexter@cpan.org>
254

LICENSE

256       Copyright (c) 2009, 2012 Piotr Roszatycki <dexter@cpan.org>.
257
258       This is free software; you can redistribute it and/or modify it under
259       the same terms as perl itself.
260
261       See <http://dev.perl.org/licenses/artistic.html>
262
263
264
265perl v5.36.0                      2023-01-20                   Symbol::Util(3)
Impressum