1Exporter::Declare(3pm)User Contributed Perl DocumentationExporter::Declare(3pm)
2
6 Exporter::Declare - Exporting done right
7
9 Exporter::Declare is a meta-driven exporting tool. Exporter::Declare
10 tries to adopt all the good features of other exporting tools, while
11 throwing away horrible interfaces. Exporter::Declare also provides
12 hooks that allow you to add options and arguments for import. Finally,
13 Exporter::Declare's meta-driven system allows for top-notch
14 introspection.
15
17 Declarative exporting (like Moose for exporting)
18 Meta-driven for introspection
19 Customizable import() method
20 Export groups (tags)
21 Export generators for subs and variables
22 Clear and concise OO API
23 Exports are blessed, allowing for more introspection
24 Import syntax based off of Sub::Exporter
25 Packages export aliases
26
28 EXPORTER
29 package Some::Exporter;
30 use Exporter::Declare;
31 default_exports qw/ do_the_thing /;
33 exports qw/ subA subB $SCALAR @ARRAY %HASH /;
34 # Create a couple tags (import lists)
36 export_tag subs => qw/ subA subB do_the_thing /;
37 export_tag vars => qw/ $SCALAR @ARRAY %HASH /;
38 # These are simple boolean options, pass '-optionA' to enable it.
40 import_options qw/ optionA optionB /;
41 # These are options which slurp in the next argument as their value, pass
43 # '-optionC' => 'foo' to give it a value.
44 import_arguments qw/ optionC optionD /;
45 export anon_export => sub { ... };
47 export '@anon_var' => [...];
48 default_export a_default => sub { 'default!' }
50 our $X = "x";
52 default_export '$X';
53 my $iterator = 'a';
55 gen_export unique_class_id => sub {
56 my $current = $iterator++;
57 return sub { $current };
58 };
59 gen_default_export '$my_letter' => sub {
61 my $letter = $iterator++;
62 return \$letter;
63 };
64 # You can create a function to mangle the arguments before they are
66 # parsed into a Exporter::Declare::Spec object.
67 sub alter_import_args {
68 my ($class, $importer, $args) = @_;
69 # fiddle with args before importing routines are called
71 @$args = grep { !/^skip_/ } @$args
72 }
73 # There is no need to fiddle with import() or do any wrapping.
75 # the $specs data structure means you generally do not need to parse
76 # arguments yourself (but you can if you want using alter_import_args())
77 # Change the spec object before export occurs
79 sub before_import {
80 my $class = shift;
81 my ( $importer, $specs ) = @_;
82 if ($specs->config->{optionA}) {
84 # Modify $spec attributes accordingly
85 }
86 }
87 # Use spec object after export occurs
89 sub after_import {
90 my $class = shift;
91 my ( $importer, $specs ) = @_;
92 do_option_a() if $specs->config->{optionA};
94 do_option_c( $specs->config->{optionC} )
96 if $specs->config->{optionC};
97 print "-subs tag was used\n"
99 if $specs->config->{subs};
100 print "exported 'subA'\n"
102 if $specs->exports->{subA};
103 }
104 ...
106 IMPORTER
108 package Some::Importer;
109 use Some::Exporter qw/ subA $SCALAR !%HASH /,
110 -default => { -prefix => 'my_' },
111 qw/ -optionA !-optionB /,
112 subB => { -as => 'sub_b' };
113 subA();
115 print $SCALAR;
116 sub_b();
117 my_do_the_thing();
118 ...
120
122 Importing from a package that uses Exporter::Declare will be familiar
123 to anyone who has imported from modules before. Arguments are all
124 assumed to be export names, unless prefixed with "-" or ":" In which
125 case they may be a tag or an option. Exports without a sigil are
126 assumed to be code exports, variable exports must be listed with their
127 sigil.
128 Items prefixed with the "!" symbol are forcefully excluded, regardless
130 of any listed item that may normally include them. Tags can also be
131 excluded, this will effectively exclude everything in the tag.
132 Tags are simply lists of exports, the exporting class may define any
134 number of tags. Exporter::Declare also has the concept of options, they
135 have the same syntax as tags. Options may be boolean or argument based.
136 Boolean options are actually 3 value, undef, false "!", or true.
137 Argument based options will grab the next value in the arguments list
138 as their own, regardless of what type of value it is.
139 When you use the module, or call import(), all the arguments are
141 transformed into an Exporter::Declare::Specs object. Arguments are
142 parsed for you into a list of imports, and a configuration hash in
143 which tags/options are keys. Tags are listed in the config hash as
144 true, false, or undef depending on if they were included, negated, or
145 unlisted. Boolean options will be treated in the same way as tags.
146 Options that take arguments will have the argument as their value.
147 SELECTING ITEMS TO IMPORT
149 Exports can be subs, or package variables (scalar, hash, array). For
150 subs simply ask for the sub by name, you may optionally prefix the subs
151 name with the sub sigil "&". For variables list the variable name along
152 with its sigil "$, %, or @".
153 use Some::Exporter qw/ somesub $somescalar %somehash @somearray /;
155 TAGS
157 Every exporter automatically has the following 3 tags, in addition they
158 may define any number of custom tags. Tags can be specified by their
159 name prefixed by either "-" or ":".
160 -all
162 This tag may be used to import everything the exporter provides.
163 -default
165 This tag is used to import the default items exported. This will be
166 used when no argument is provided to import.
167 -alias
169 Every package has an alias that it can export. This is the last
170 segment of the packages namespace. IE
171 "My::Long::Package::Name::Foo" could export the Foo() function.
172 These alias functions simply return the full package name as a
173 string, in this case 'My::Long::Package::Name::Foo'. This is
174 similar to aliased.
175 The -alias tag is a shortcut so that you do not need to think about
177 what the alias name would be when adding it to the import
178 arguments.
179 use My::Long::Package::Name::Foo -alias;
181 my $foo = Foo()->new(...);
183 RENAMING IMPORTED ITEMS
185 You can prefix, suffix, or completely rename the items you import.
186 Whenever an item is followed by a hash in the import list, that hash
187 will be used for configuration. Configuration items always start with a
188 dash "-".
189 The 3 available configuration options that effect import names are
191 "-prefix", "-suffix", and "-as". If "-as" is seen it will be used as
192 is. If prefix or suffix are seen they will be attached to the original
193 name (unless -as is present in which case they are ignored).
194 use Some::Exporter subA => { -as => 'DoThing' },
196 subB => { -prefix => 'my_', -suffix => '_ok' };
197 The example above will import subA() under the name DoThing(). It will
199 also import subB() under the name my_subB_ok().
200 You may als specify a prefix and/or suffix for tags. The following
202 example will import all the default exports with 'my_' prefixed to each
203 name.
204 use Some::Exporter -default => { -prefix => 'my_' };
206 OPTIONS
208 Some exporters will recognise options. Options look just like tags, and
209 are specified the same way. What options do, and how they effect things
210 is exporter-dependant.
211 use Some::Exporter qw/ -optionA -optionB /;
213 ARGUMENTS
215 Some options require an argument. These options are just like other
216 tags/options except that the next item in the argument list is slurped
217 in as the option value.
218 use Some::Exporter -ArgOption => 'Value, not an export',
220 -ArgTakesHash => { ... };
221 Once again available options are exporter specific.
223 PROVIDING ARGUMENTS FOR GENERATED ITEMS
225 Some items are generated at import time. These items may accept
226 arguments. There are 3 ways to provide arguments, and they may all be
227 mixed (though that is not recommended).
228 As a hash
230 use Some::Exporter generated => { key => 'val', ... };
232 As an array
234 use Some::Exporter generated => [ 'Arg1', 'Arg2', ... ];
236 As an array in a config hash
238 use Some::Exporter generated => { -as => 'my_gen', -args => [ 'arg1', ... ]};
240 You can use all three at once, but this is really a bad idea,
242 documented for completeness:
243 use Some::Exporter generated => { -as => 'my_gen, key => 'value', -args => [ 'arg1', 'arg2' ]}
245 generated => [ 'arg3', 'arg4' ];
246 The example above will work fine, all the arguments will make it into
248 the generator. The only valid reason for this to work is that you may
249 provide arguments such as "-prefix" to a tag that brings in
250 generator(), while also desiring to give arguments to generator()
251 independently.
252
254 With the exception of import(), all the following work equally well as
255 functions or class methods.
256 import( @args )
258 The import() class method. This turns the @args list into an
259 Exporter::Declare::Specs object.
260 exports( @add_items )
262 Add items to be exported.
263 @list = exports()
265 Retrieve list of exports.
266 default_exports( @add_items )
268 Add items to be exported, and add them to the -default tag.
269 @list = default_exports()
271 List of exports in the -default tag
272 import_options(@add_items)
274 Specify boolean options that should be accepted at import time.
275 import_arguments(@add_items)
277 Specify options that should be accepted at import that take
278 arguments.
279 export_tag( $name, @add_items );
281 Define an export tag, or add items to an existing tag.
282
284 These all work fine in function or method form, however the syntax
285 sugar will only work in function form.
286 reexport( $package )
288 Make this exporter inherit all the exports and tags of $package.
289 Works for Exporter::Declare or Exporter.pm based exporters. Re-
290 Exporting of Sub::Exporter based classes is not currently
291 supported.
292 export_to( $package, @args )
294 Export to the specified class.
295 export( $name )
297 export( $name, $ref )
298 export is a keyword that lets you export any 1 item at a time. The
299 item can be exported by name, or name + ref. When a ref is
300 provided, the export is created, but there is no corresponding
301 variable/sub in the packages namespace.
302 default_export( $name )
304 default_export( $name, $ref )
305 gen_export( $name )
306 gen_export( $name, $ref )
307 gen_default_export( $name )
308 gen_default_export( $name, $ref )
309 These all act just like export(), except that they add subrefs as
310 generators, and/or add exports to the -default tag.
311
313 Please use Exporter::Declare::Magic directly from now on.
314 DEPRECATED USAGE OF MAGIC
316 use Exporter::Declare '-magic';
317 This adds Devel::Declare magic to several functions. It also allows you
319 to easily create or use parsers on your own exports. See
320 Exporter::Declare::Magic for more details.
321 You can also provide import arguments to Devel::Declare::Magic
323 # Arguments to -magic must be in an arrayref, not a hashref.
325 use Exporter::Declare -magic => [ '-default', '!export', -prefix => 'magic_' ];
326
328 Exporter/Declare.pm does not have much logic to speak of. Rather
329 Exporter::Declare is sugar on top of class meta data stored in
330 Exporter::Declare::Meta objects. Arguments are parsed via
331 Exporter::Declare::Specs, and also turned into objects. Even exports
332 are blessed references to the exported item itself, and handle the
333 injection on their own (See Exporter::Declare::Export).
334
336 All exporters have a meta class, the only way to get the meta object is
337 to call the export_meta() method on the class/object that is an
338 exporter. Any class that uses Exporter::Declare gets this method, and a
339 meta-object.
340
342 Chad Granum exodist7@gmail.com
343
345 Copyright (C) 2010 Chad Granum
346 Exporter-Declare is free software; Standard perl licence.
348 Exporter-Declare is distributed in the hope that it will be useful, but
350 WITHOUT ANY WARRANTY; without even the implied warranty of
351 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the license
352 for more details.
353perl v5.38.0 2023-07-20 Exporter::Declare(3pm)