1Exporter::Declare(3)  User Contributed Perl Documentation Exporter::Declare(3)
2
3
4

NAME

6       Exporter::Declare - Exporting done right
7

DESCRIPTION

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

FEATURES

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

SYNOPSIS

28   EXPORTER
29           package Some::Exporter;
30           use Exporter::Declare;
31
32           default_exports qw/ do_the_thing /;
33           exports qw/ subA subB $SCALAR @ARRAY %HASH /;
34
35           # 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
39           # These are simple boolean options, pass '-optionA' to enable it.
40           import_options   qw/ optionA optionB /;
41
42           # 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
46           export anon_export => sub { ... };
47           export '@anon_var' => [...];
48
49           default_export a_default => sub { 'default!' }
50
51           our $X = "x";
52           default_export '$X';
53
54           my $iterator = 'a';
55           gen_export unique_class_id => sub {
56               my $current = $iterator++;
57               return sub { $current };
58           };
59
60           gen_default_export '$my_letter' => sub {
61               my $letter = $iterator++;
62               return \$letter;
63           };
64
65           # 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
70              # fiddle with args before importing routines are called
71              @$args = grep { !/^skip_/ } @$args
72           }
73
74           # 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
78           # Change the spec object before export occurs
79           sub before_import {
80               my $class = shift;
81               my ( $importer, $specs ) = @_;
82
83               if ($specs->config->{optionA}) {
84                   # Modify $spec attributes accordingly
85               }
86           }
87
88           # Use spec object after export occurs
89           sub after_import {
90               my $class = shift;
91               my ( $importer, $specs ) = @_;
92
93               do_option_a() if $specs->config->{optionA};
94
95               do_option_c( $specs->config->{optionC} )
96                   if $specs->config->{optionC};
97
98               print "-subs tag was used\n"
99                   if $specs->config->{subs};
100
101               print "exported 'subA'\n"
102                   if $specs->exports->{subA};
103           }
104
105           ...
106
107   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
114           subA();
115           print $SCALAR;
116           sub_b();
117           my_do_the_thing();
118
119           ...
120

IMPORT INTERFACE

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
129       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
133       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
140       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
148   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
154           use Some::Exporter qw/ somesub $somescalar %somehash @somearray /;
155
156   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
161       -all
162           This tag may be used to import everything the exporter provides.
163
164       -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
168       -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
176           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
180               use My::Long::Package::Name::Foo -alias;
181
182               my $foo = Foo()->new(...);
183
184   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
190       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
195           use Some::Exporter subA => { -as => 'DoThing' },
196                              subB => { -prefix => 'my_', -suffix => '_ok' };
197
198       The example above will import "subA()" under the name "DoThing()". It
199       will also import "subB()" under the name "my_subB_ok()".
200
201       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
205           use Some::Exporter -default => { -prefix => 'my_' };
206
207   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
212           use Some::Exporter qw/ -optionA -optionB /;
213
214   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
219           use Some::Exporter -ArgOption    => 'Value, not an export',
220                              -ArgTakesHash => { ... };
221
222       Once again available options are exporter specific.
223
224   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
229       As a hash
230
231           use Some::Exporter generated => { key => 'val', ... };
232
233       As an array
234
235           use Some::Exporter generated => [ 'Arg1', 'Arg2', ... ];
236
237       As an array in a config hash
238
239           use Some::Exporter generated => { -as => 'my_gen', -args => [ 'arg1', ... ]};
240
241       You can use all three at once, but this is really a bad idea,
242       documented for completeness:
243
244           use Some::Exporter generated => { -as => 'my_gen, key => 'value', -args => [ 'arg1', 'arg2' ]}
245                              generated => [ 'arg3', 'arg4' ];
246
247       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

PRIMARY EXPORT API

254       With the exception of import(), all the following work equally well as
255       functions or class methods.
256
257       import( @args )
258           The import() class method. This turns the @args list into an
259           Exporter::Declare::Specs object.
260
261       exports( @add_items )
262           Add items to be exported.
263
264       @list = exports()
265           Retrieve list of exports.
266
267       default_exports( @add_items )
268           Add items to be exported, and add them to the -default tag.
269
270       @list = default_exports()
271           List of exports in the -default tag
272
273       import_options(@add_items)
274           Specify boolean options that should be accepted at import time.
275
276       import_arguments(@add_items)
277           Specify options that should be accepted at import that take
278           arguments.
279
280       export_tag( $name, @add_items );
281           Define an export tag, or add items to an existing tag.
282

EXTENDED EXPORT API

284       These all work fine in function or method form, however the syntax
285       sugar will only work in function form.
286
287       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
293       export_to( $package, @args )
294           Export to the specified class.
295
296       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
303       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

MAGIC

313       Please use Exporter::Declare::Magic directly from now on.
314
315   DEPRECATED USAGE OF MAGIC
316           use Exporter::Declare '-magic';
317
318       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
322       You can also provide import arguments to Devel::Declare::Magic
323
324           # Arguments to -magic must be in an arrayref, not a hashref.
325           use Exporter::Declare -magic => [ '-default', '!export', -prefix => 'magic_' ];
326

INTERNAL API

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

META CLASS

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

AUTHORS

342       Chad Granum exodist7@gmail.com
343
345       Copyright (C) 2010 Chad Granum
346
347       Exporter-Declare is free software; Standard perl licence.
348
349       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.
353
354
355
356perl v5.34.0                      2022-01-21              Exporter::Declare(3)
Impressum