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