mirror of
https://github.com/webmin/webmin.git
synced 2025-07-23 00:30:33 +00:00
Fix to remove manual and pods
This commit is contained in:
@ -1,134 +0,0 @@
|
||||
=pod
|
||||
|
||||
=encoding utf-8
|
||||
|
||||
=for stopwords frobnicate greps regexps
|
||||
|
||||
=head1 NAME
|
||||
|
||||
Exporter::Tiny::Manual::Etc - odds and ends
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
=head2 Utility Functions
|
||||
|
||||
Exporter::Tiny is itself an exporter!
|
||||
|
||||
These functions are really for internal use, but can be exported if you
|
||||
need them:
|
||||
|
||||
=over
|
||||
|
||||
=item C<< mkopt(\@array) >>
|
||||
|
||||
Similar to C<mkopt> from L<Data::OptList>. It doesn't support all the
|
||||
fancy options that Data::OptList does (C<moniker>, C<require_unique>,
|
||||
C<must_be> and C<name_test>) but runs about 50% faster.
|
||||
|
||||
=item C<< mkopt_hash(\@array) >>
|
||||
|
||||
Similar to C<mkopt_hash> from L<Data::OptList>. See also C<mkopt>.
|
||||
|
||||
=back
|
||||
|
||||
=head2 History
|
||||
|
||||
L<Type::Library> had a bunch of custom exporting code which poked coderefs
|
||||
into its caller's stash. It needed this to be something more powerful than
|
||||
most exporters so that it could switch between exporting Moose, Mouse and
|
||||
Moo-compatible objects on request. L<Sub::Exporter> would have been capable,
|
||||
but had too many dependencies for the Type::Tiny project.
|
||||
|
||||
Meanwhile L<Type::Utils>, L<Types::TypeTiny> and L<Test::TypeTiny> each
|
||||
used the venerable L<Exporter.pm|Exporter>. However, this meant they were
|
||||
unable to use the features like L<Sub::Exporter>-style function renaming
|
||||
which I'd built into Type::Library:
|
||||
|
||||
## import "Str" but rename it to "String".
|
||||
use Types::Standard "Str" => { -as => "String" };
|
||||
|
||||
And so I decided to factor out code that could be shared by all Type-Tiny's
|
||||
exporters into a single place: Exporter::TypeTiny.
|
||||
|
||||
As of version 0.026, Exporter::TypeTiny was also made available as
|
||||
L<Exporter::Tiny>, distributed independently on CPAN. CHOCOLATEBOY had
|
||||
convinced me that it was mature enough to live a life of its own.
|
||||
|
||||
As of version 0.030, Type-Tiny depends on Exporter::Tiny and
|
||||
Exporter::TypeTiny is being phased out.
|
||||
|
||||
=head2 Obligatory Exporter Comparison
|
||||
|
||||
Exporting is unlikely to be your application's performance bottleneck, but
|
||||
nonetheless here are some comparisons.
|
||||
|
||||
B<< Comparative sizes according to L<Devel::SizeMe>: >>
|
||||
|
||||
Exporter 217.1Kb
|
||||
Sub::Exporter::Progressive 263.2Kb
|
||||
Exporter::Tiny 267.7Kb
|
||||
Exporter + Exporter::Heavy 281.5Kb
|
||||
Exporter::Renaming 406.2Kb
|
||||
Sub::Exporter 701.0Kb
|
||||
|
||||
B<< Performance exporting a single sub: >>
|
||||
|
||||
Rate SubExp ExpTiny SubExpProg ExpPM
|
||||
SubExp 2489/s -- -56% -85% -88%
|
||||
ExpTiny 5635/s 126% -- -67% -72%
|
||||
SubExpProg 16905/s 579% 200% -- -16%
|
||||
ExpPM 20097/s 707% 257% 19% --
|
||||
|
||||
(Exporter::Renaming globally changes the behaviour of Exporter.pm, so could
|
||||
not be included in the same benchmarks.)
|
||||
|
||||
B<< (Non-Core) Dependencies: >>
|
||||
|
||||
Exporter -1
|
||||
Exporter::Renaming 0
|
||||
Exporter::Tiny 0
|
||||
Sub::Exporter::Progressive 0
|
||||
Sub::Exporter 3
|
||||
|
||||
B<< Features: >>
|
||||
|
||||
ExpPM ExpTiny SubExp SubExpProg
|
||||
Can export code symbols............. Yes Yes Yes Yes
|
||||
Can export non-code symbols......... Yes Yes
|
||||
Groups/tags......................... Yes Yes Yes Yes
|
||||
Export by regexp.................... Yes Yes
|
||||
Bang prefix......................... Yes Yes
|
||||
Allows renaming of subs............. Yes Yes Maybe
|
||||
Install code into scalar refs....... Yes Yes Maybe
|
||||
Can be passed an "into" parameter... Yes Yes Maybe
|
||||
Can be passed an "installer" sub.... Yes Yes Maybe
|
||||
Config avoids package variables..... Yes
|
||||
Supports generators................. Yes Yes
|
||||
Sane API for generators............. Yes Yes
|
||||
Unimport............................ Yes
|
||||
|
||||
(Certain Sub::Exporter::Progressive features are only available if
|
||||
Sub::Exporter is installed.)
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<Exporter::Shiny>,
|
||||
L<Exporter::Tiny>.
|
||||
|
||||
=head1 AUTHOR
|
||||
|
||||
Toby Inkster E<lt>tobyink@cpan.orgE<gt>.
|
||||
|
||||
=head1 COPYRIGHT AND LICENCE
|
||||
|
||||
This software is copyright (c) 2013-2014, 2017 by Toby Inkster.
|
||||
|
||||
This is free software; you can redistribute it and/or modify it under
|
||||
the same terms as the Perl 5 programming language system itself.
|
||||
|
||||
=head1 DISCLAIMER OF WARRANTIES
|
||||
|
||||
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
|
||||
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
|
||||
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
|
||||
|
@ -1,266 +0,0 @@
|
||||
=pod
|
||||
|
||||
=encoding utf-8
|
||||
|
||||
=for stopwords frobnicate greps regexps
|
||||
|
||||
=head1 NAME
|
||||
|
||||
Exporter::Tiny::Manual::Exporting - creating an exporter using Exporter::Tiny
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<< Read L<Exporter::Tiny::Manual::QuickStart> first! >>
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
Simple configuration works the same as L<Exporter>; inherit from
|
||||
L<Exporter::Tiny>, and use the C<< @EXPORT >>, C<< @EXPORT_OK >>,
|
||||
and C<< %EXPORT_TAGS >> package variables to list subs to export.
|
||||
|
||||
Unlike Exporter, Exporter::Tiny performs most of its internal duties
|
||||
(including resolution of tag names to sub names, resolution of sub
|
||||
names to coderefs, and installation of coderefs into the target
|
||||
package) as B<method calls>, which means that your module (which is a
|
||||
subclass of Exporter::Tiny) can override them to provide interesting
|
||||
behaviour.
|
||||
|
||||
=head2 Advanced Tag Stuff
|
||||
|
||||
You can define tags using other tags:
|
||||
|
||||
use Exporter::Shiny qw(
|
||||
black white red green blue cyan magenta yellow
|
||||
);
|
||||
|
||||
our %EXPORT_TAGS = (
|
||||
rgb => [qw( red green blue )],
|
||||
cym => [qw( cyan magenta yellow )],
|
||||
cymk => [qw( black :cym )],
|
||||
monochrome => [qw( black white )],
|
||||
all => [qw( :rgb :cymk :monochrome )],
|
||||
);
|
||||
|
||||
B<< CAVEAT: >> If you create a cycle in the tags, this could put
|
||||
Exporter::Tiny into an infinite loop expanding the tags. Don't do that.
|
||||
|
||||
=head2 More on Generators
|
||||
|
||||
Exporter::Tiny has always allowed exported subs to be generated (like
|
||||
L<Sub::Exporter>), but until version 0.025 did not have an especially nice
|
||||
API for it.
|
||||
|
||||
Now, it's easy. If you want to generate a sub C<foo> to export, list it in
|
||||
C<< @EXPORT >> or C<< @EXPORT_OK >> as usual, and then simply give your
|
||||
exporter module a class method called C<< _generate_foo >>.
|
||||
|
||||
push @EXPORT_OK, 'foo';
|
||||
|
||||
sub _generate_foo {
|
||||
my $class = shift;
|
||||
my ($name, $args, $globals) = @_;
|
||||
|
||||
return sub {
|
||||
...;
|
||||
}
|
||||
}
|
||||
|
||||
We showed how to do that in L<Exporter::Tiny::Manual::QuickStart>, but
|
||||
one thing we didn't show was that C<< $globals >> gets passed in there.
|
||||
This is the global options hash, as described in
|
||||
L<Exporter::Tiny::Manual::Importing>. It can often be useful. In
|
||||
particular it will tell you what package the generated sub is destined
|
||||
to be installed into.
|
||||
|
||||
To generate non-code symbols, name your generators like this:
|
||||
|
||||
sub _generateScalar_Foo { ... } # generate a symbol $Foo
|
||||
sub _generateArray_Bar { ... } # generate a symbol @Bar
|
||||
sub _generateHash_Baz { ... } # generate a symbol %Baz
|
||||
|
||||
You can also generate tags:
|
||||
|
||||
my %constants;
|
||||
BEGIN {
|
||||
%constants = (FOO => 1, BAR => 2);
|
||||
}
|
||||
use constant \%constants;
|
||||
|
||||
$EXPORT_TAGS{constants} = sub {
|
||||
my $class = shift;
|
||||
my ($name, $args, $globals) = @_;
|
||||
|
||||
return keys(%constants);
|
||||
};
|
||||
|
||||
=head2 Hooks
|
||||
|
||||
Sometimes as well as exporting stuff, you want to do some setup or
|
||||
something.
|
||||
|
||||
You can define a couple of class methods in your package, and they'll
|
||||
get called at the appropriate time:
|
||||
|
||||
package MyUtils;
|
||||
|
||||
...;
|
||||
|
||||
sub _exporter_validate_opts {
|
||||
my $class = shift;
|
||||
my ($globals) = @_;
|
||||
|
||||
...; # do stuff here
|
||||
|
||||
$class->SUPER::_exporter_validate_opts(@_);
|
||||
}
|
||||
|
||||
sub _exporter_validate_unimport_opts {
|
||||
my $class = shift;
|
||||
my ($globals) = @_;
|
||||
|
||||
...; # do stuff here
|
||||
|
||||
$class->SUPER::_exporter_validate_unimport_opts(@_);
|
||||
}
|
||||
|
||||
The C<< $globals >> variable is that famous global options hash. In
|
||||
particular, C<< $globals->{into} >> is useful because it tells you what
|
||||
package has imported you.
|
||||
|
||||
As you might have guessed, these methods were originally intended to
|
||||
validate the global options hash, but can be used to perform any
|
||||
general duties before the real exporting work is done.
|
||||
|
||||
=head2 Overriding Internals
|
||||
|
||||
An important difference between L<Exporter> and Exporter::Tiny is that
|
||||
the latter calls all its internal functions as I<< class methods >>. This
|
||||
means that your subclass can I<< override them >> to alter their behaviour.
|
||||
|
||||
The following methods are available to be overridden. Despite being named
|
||||
with a leading underscore, they are considered public methods. (The underscore
|
||||
is there to avoid accidentally colliding with any of your own function names.)
|
||||
|
||||
=over
|
||||
|
||||
=item C<< _exporter_validate_opts($globals) >>
|
||||
|
||||
Documented above.
|
||||
|
||||
=item C<< _exporter_validate_unimport_opts($globals) >>
|
||||
|
||||
Documented above.
|
||||
|
||||
=item C<< _exporter_merge_opts($tag_opts, $globals, @exports) >>
|
||||
|
||||
Called to merge options which have been provided for a tag into the
|
||||
options provided for the exports that the tag expanded to.
|
||||
|
||||
=item C<< _exporter_expand_tag($name, $args, $globals) >>
|
||||
|
||||
This method is called to expand an import tag (e.g. C<< ":constants" >>).
|
||||
It is passed the tag name (minus the leading ":"), an optional hashref
|
||||
of options (like C<< { -prefix => "foo_" } >>), and the global options
|
||||
hashref.
|
||||
|
||||
It is expected to return a list of ($name, $args) arrayref pairs. These
|
||||
names can be sub names to export, or further tag names (which must have
|
||||
their ":"). If returning tag names, be careful to avoid creating a tag
|
||||
expansion loop!
|
||||
|
||||
The default implementation uses C<< %EXPORT_TAGS >> to expand tags, and
|
||||
provides fallbacks for the C<< :default >> and C<< :all >> tags.
|
||||
|
||||
=item C<< _exporter_expand_regexp($regexp, $args, $globals) >>
|
||||
|
||||
Like C<_exporter_expand_regexp>, but given a regexp-like string instead
|
||||
of a tag name.
|
||||
|
||||
The default implementation greps through C<< @EXPORT_OK >> for imports,
|
||||
and the list of already-imported functions for exports.
|
||||
|
||||
=item C<< _exporter_expand_sub($name, $args, $globals) >>
|
||||
|
||||
This method is called to translate a sub name to a hash of name => coderef
|
||||
pairs for exporting to the caller. In general, this would just be a hash with
|
||||
one key and one value, but, for example, L<Type::Library> overrides this
|
||||
method so that C<< "+Foo" >> gets expanded to:
|
||||
|
||||
(
|
||||
Foo => sub { $type },
|
||||
is_Foo => sub { $type->check(@_) },
|
||||
to_Foo => sub { $type->assert_coerce(@_) },
|
||||
assert_Foo => sub { $type->assert_return(@_) },
|
||||
)
|
||||
|
||||
The default implementation checks that the name is allowed to be exported
|
||||
(using the C<_exporter_permitted_regexp> method), gets the coderef using
|
||||
the generator if there is one (or by calling C<< can >> on your exporter
|
||||
otherwise) and calls C<_exporter_fail> if it's unable to generate or
|
||||
retrieve a coderef.
|
||||
|
||||
Despite the name, is also called for non-code symbols.
|
||||
|
||||
=item C<< _exporter_permitted_regexp($globals) >>
|
||||
|
||||
This method is called to retrieve a regexp for validating the names of
|
||||
exportable subs. If a sub doesn't match the regexp, then the default
|
||||
implementation of C<_exporter_expand_sub> will refuse to export it. (Of
|
||||
course, you may override the default C<_exporter_expand_sub>.)
|
||||
|
||||
The default implementation of this method assembles the regexp from
|
||||
C<< @EXPORT >> and C<< @EXPORT_OK >>.
|
||||
|
||||
=item C<< _exporter_fail($name, $args, $globals) >>
|
||||
|
||||
Called by C<_exporter_expand_sub> if it can't find a coderef to export.
|
||||
|
||||
The default implementation just throws an exception. But you could emit
|
||||
a warning instead, or just ignore the failed export.
|
||||
|
||||
If you don't throw an exception then you should be aware that this
|
||||
method is called in list context, and any list it returns will be treated
|
||||
as an C<_exporter_expand_sub>-style hash of names and coderefs for
|
||||
export.
|
||||
|
||||
=item C<< _exporter_install_sub($name, $args, $globals, $coderef) >>
|
||||
|
||||
This method actually installs the exported sub into its new destination.
|
||||
Its return value is ignored.
|
||||
|
||||
The default implementation handles sub renaming (i.e. the C<< -as >>,
|
||||
C<< -prefix >> and C<< -suffix >> functions. This method does a lot of
|
||||
stuff; if you need to override it, it's probably a good idea to just
|
||||
pre-process the arguments and then call the super method rather than
|
||||
trying to handle all of it yourself.
|
||||
|
||||
Despite the name, is also called for non-code symbols.
|
||||
|
||||
=item C<< _exporter_uninstall_sub($name, $args, $globals) >>
|
||||
|
||||
The opposite of C<_exporter_install_sub>.
|
||||
|
||||
=back
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<Exporter::Shiny>,
|
||||
L<Exporter::Tiny>.
|
||||
|
||||
=head1 AUTHOR
|
||||
|
||||
Toby Inkster E<lt>tobyink@cpan.orgE<gt>.
|
||||
|
||||
=head1 COPYRIGHT AND LICENCE
|
||||
|
||||
This software is copyright (c) 2013-2014, 2017 by Toby Inkster.
|
||||
|
||||
This is free software; you can redistribute it and/or modify it under
|
||||
the same terms as the Perl 5 programming language system itself.
|
||||
|
||||
=head1 DISCLAIMER OF WARRANTIES
|
||||
|
||||
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
|
||||
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
|
||||
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
|
||||
|
@ -1,269 +0,0 @@
|
||||
=pod
|
||||
|
||||
=encoding utf-8
|
||||
|
||||
=for stopwords frobnicate greps regexps
|
||||
|
||||
=head1 NAME
|
||||
|
||||
Exporter::Tiny::Manual::Importing - importing from Exporter::Tiny-based modules
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
For the purposes of this discussion we'll assume we have a module called
|
||||
C<< MyUtils >> which exports functions called C<frobnicate>, C<red>,
|
||||
C<blue>, and C<green>. It has a tag set up called C<:colours> which
|
||||
corresponds to C<red>, C<blue>, and C<green>.
|
||||
|
||||
Many of these tricks may seem familiar from L<Sub::Exporter>. That is
|
||||
intentional. Exporter::Tiny doesn't attempt to provide every feature of
|
||||
Sub::Exporter, but where it does it usually uses a fairly similar API.
|
||||
|
||||
=head2 Basic importing
|
||||
|
||||
It's easy to import a single function from a module:
|
||||
|
||||
use MyUtils "frobnicate";
|
||||
|
||||
Or a list of functions:
|
||||
|
||||
use MyUtils "red", "green";
|
||||
|
||||
Perl's C<< qw() >> shorthand for a list of words is pretty useful:
|
||||
|
||||
use MyUtils qw( red green );
|
||||
|
||||
If the module defines tags, you can import them like this:
|
||||
|
||||
use MyUtils qw( :colours );
|
||||
|
||||
Or with a hyphen instead of a colon:
|
||||
|
||||
use MyUtils qw( -colours );
|
||||
|
||||
Hyphens are good because Perl will autoquote a bareword that follows
|
||||
them:
|
||||
|
||||
use MyUtils -colours;
|
||||
|
||||
And it's possible to mix function names and tags in the same list:
|
||||
|
||||
use MyUtils qw( frobnicate :colours );
|
||||
|
||||
=head2 Renaming imported functions
|
||||
|
||||
It's possible to rename a function you're importing:
|
||||
|
||||
use MyUtils "frobnicate" => { -as => "frob" };
|
||||
|
||||
Or you can apply a prefix and/or suffix. The following imports the
|
||||
function and calls it C<my_frobinate_thing>.
|
||||
|
||||
use MyUtils "frobnicate" => { -prefix => "my_", -suffix => "_thing" };
|
||||
|
||||
You can apply a prefix/suffix to B<all> functions you import by
|
||||
placing the hashref B<first> in the import list. (This first hashref
|
||||
is referred to as the global options hash, and can do some special
|
||||
things.)
|
||||
|
||||
use MyUtils { prefix => "my_" }, "frobnicate";
|
||||
|
||||
Did you notice that we used C<< -prefix >> and C<< -suffix >> in the
|
||||
normal options hash, but C<< prefix >> and C<< suffix >> (no hyphen)
|
||||
in the global options hash? That's a common pattern with this module.
|
||||
|
||||
You can import the same function multiple times with different names:
|
||||
|
||||
use MyUtils
|
||||
"frobnicate" => { -as => "frob" },
|
||||
"frobnicate" => { -as => "frbnct" };
|
||||
|
||||
Tags can take the C<< -prefix >> and C<< -suffix >> options too. The
|
||||
following imports C<colour_red>, C<colour_green>, and C<colour_blue>:
|
||||
|
||||
use MyUtils -colours => { -prefix => "colour_" };
|
||||
|
||||
You can also set C<< -as >> to be a coderef to generate a function
|
||||
name. This imports functions called C<RED>, C<GREEN>, and C<BLUE>:
|
||||
|
||||
use MyUtils -colours => { -as => sub { uc($_[0]) } };
|
||||
|
||||
Note that it doesn't make sense to use C<< -as >> with a tag unless
|
||||
you're doing this coderef thing. Coderef C<< as >> also works in the
|
||||
global options hash.
|
||||
|
||||
=head2 DO NOT WANT!
|
||||
|
||||
Sometimes you want to supply a list of functions you B<< don't >> want
|
||||
to import. To do that, prefix the function with a bang. This imports
|
||||
everything except "frobnicate":
|
||||
|
||||
use MyUtils qw( -all !frobnicate );
|
||||
|
||||
You can add the bang prefix to tags too. This will import everything
|
||||
except the colours.
|
||||
|
||||
use MyUtils qw( -all !:colours );
|
||||
|
||||
Negated imports always "win", so the following will not import
|
||||
"frobnicate", no matter how many times you repeat it...
|
||||
|
||||
use MyUtils qw( !frobnicate frobnicate frobnicate frobnicate );
|
||||
|
||||
=head2 Importing by regexp
|
||||
|
||||
Here's how you could import all functions beginning with an "f":
|
||||
|
||||
use MyUtils qw( /^F/i );
|
||||
|
||||
Or import everything except functions beginning with a "z":
|
||||
|
||||
use MyUtils qw( -all !/^Z/i );
|
||||
|
||||
Note that regexps are always supplied as I<strings> starting with
|
||||
C<< "/" >>, and not as quoted regexp references (C<< qr/.../ >>).
|
||||
|
||||
=head2 Import functions into another package
|
||||
|
||||
Occasionally you need to import functions not into your own package,
|
||||
but into a different package. You can do that like this:
|
||||
|
||||
use MyUtils { into => "OtherPkg" }, "frobnicate";
|
||||
|
||||
OtherPkg::frobincate(...);
|
||||
|
||||
However, L<Import::Into> will probably provide you with a better
|
||||
approach which doesn't just work with Exporter::Tiny, but B<all>
|
||||
exporters.
|
||||
|
||||
=head2 Lexical subs on Perl 5.37.2 and above
|
||||
|
||||
Often you want to make use of an exported function, but don't want
|
||||
it to "pollute" your namespace.
|
||||
|
||||
On newer versions of Perl, Exporter::Tiny can use C<export_lexically>
|
||||
from L<builtin> to give you lexical versions of exports.
|
||||
|
||||
{
|
||||
use MyUtils -lexical, "frobnicate";
|
||||
|
||||
frobnicate(...); # ok
|
||||
}
|
||||
|
||||
frobnicate(...); # not ok
|
||||
|
||||
This functionality should be considered B<EXPERIMENTAL> until
|
||||
C<export_lexically> is included in a stable release of Perl.
|
||||
|
||||
=head2 Lexical subs on Perl older than 5.37.2
|
||||
|
||||
There is this L<Sub::Exporter::Lexical> thing that was designed as a
|
||||
plugin for L<Sub::Exporter>, but Exporter::Tiny's API is close enough
|
||||
that it will work. Do you remember that global options hash? Just
|
||||
use that to tell Exporter::Tiny to use an alternative sub installer.
|
||||
|
||||
{
|
||||
use Sub::Exporter::Lexical lexical_installer => { -as => "lex" };
|
||||
use MyUtils { installer => lex }, "frobnicate";
|
||||
|
||||
frobnicate(...); # ok
|
||||
}
|
||||
|
||||
frobnicate(...); # not ok
|
||||
|
||||
Another way to do lexical functions is to import a function into a
|
||||
scalar variable:
|
||||
|
||||
my $func;
|
||||
use MyUtils "frobnicate" => { -as => \$func };
|
||||
|
||||
$func->(...);
|
||||
|
||||
You can even provide a hashref to put all imported functions into as
|
||||
part of that global options hash I mentioned earlier.
|
||||
|
||||
my %funcs;
|
||||
use MyUtils { into => \%funcs }, "frobnicate";
|
||||
|
||||
$funcs{frobnicate}->(...);
|
||||
|
||||
=head2 Unimporting
|
||||
|
||||
You can unimport the functions that MyUtils added to your namespace:
|
||||
|
||||
no MyUtils;
|
||||
|
||||
Or just specific ones:
|
||||
|
||||
no MyUtils qw(frobnicate);
|
||||
|
||||
If you renamed a function when you imported it, you should unimport by
|
||||
the new name:
|
||||
|
||||
use MyUtils frobnicate => { -as => "frob" };
|
||||
...;
|
||||
no MyUtils "frob";
|
||||
|
||||
Unimporting using tags and regexps should mostly do what you want.
|
||||
|
||||
=head1 DIAGNOSTICS
|
||||
|
||||
=over
|
||||
|
||||
=item B<< Overwriting existing sub '%s::%s' with sub '%s' exported by %s >>
|
||||
|
||||
A warning issued if Exporter::Tiny is asked to export a symbol which
|
||||
will result in an existing sub being overwritten. This warning can be
|
||||
suppressed using either of the following:
|
||||
|
||||
use MyUtils { replace => 1 }, "frobnicate";
|
||||
use MyUtils "frobnicate" => { -replace => 1 };
|
||||
|
||||
Or can be upgraded to a fatal error:
|
||||
|
||||
use MyUtils { replace => "die" }, "frobnicate";
|
||||
use MyUtils "frobnicate" => { -replace => "die" };
|
||||
|
||||
=item B<< Refusing to overwrite existing sub '%s::%s' with sub '%s' exported by %s >>
|
||||
|
||||
The fatal version of the above warning.
|
||||
|
||||
=item B<< Could not find sub '%s' exported by %s >>
|
||||
|
||||
You requested to import a sub which the package does not provide.
|
||||
|
||||
=item B<< Cannot provide an -as option for tags >>
|
||||
|
||||
Because a tag may provide more than one function, it does not make sense
|
||||
to request a single name for it. Instead use C<< -prefix >> or C<< -suffix >>.
|
||||
|
||||
=item B<< Passing options to unimport '%s' makes no sense >>
|
||||
|
||||
When you import a sub, it occasionally makes sense to pass some options
|
||||
for it. However, when unimporting, options do nothing, so this warning
|
||||
is issued.
|
||||
|
||||
=back
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<Exporter::Shiny>,
|
||||
L<Exporter::Tiny>.
|
||||
|
||||
=head1 AUTHOR
|
||||
|
||||
Toby Inkster E<lt>tobyink@cpan.orgE<gt>.
|
||||
|
||||
=head1 COPYRIGHT AND LICENCE
|
||||
|
||||
This software is copyright (c) 2013-2014, 2017 by Toby Inkster.
|
||||
|
||||
This is free software; you can redistribute it and/or modify it under
|
||||
the same terms as the Perl 5 programming language system itself.
|
||||
|
||||
=head1 DISCLAIMER OF WARRANTIES
|
||||
|
||||
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
|
||||
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
|
||||
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
|
||||
|
@ -1,195 +0,0 @@
|
||||
=pod
|
||||
|
||||
=encoding utf-8
|
||||
|
||||
=for stopwords frobnicate greps regexps
|
||||
|
||||
=head1 NAME
|
||||
|
||||
Exporter::Tiny::Manual::QuickStart - the quickest way to get up and running with Exporter::Tiny
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
package MyUtils;
|
||||
|
||||
use Exporter::Shiny qw( frobnicate );
|
||||
|
||||
sub frobnicate {
|
||||
...; # your code here
|
||||
}
|
||||
|
||||
1;
|
||||
|
||||
Now people can use your module like this:
|
||||
|
||||
use MyUtils "frobnicate";
|
||||
|
||||
frobnicate(42);
|
||||
|
||||
Or like this:
|
||||
|
||||
use MyUtils "frobnicate" => { -as => "frob" };
|
||||
|
||||
frob(42);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
See the synopsis. Yes, it's that simple.
|
||||
|
||||
=head2 Next steps
|
||||
|
||||
=head3 Default exports
|
||||
|
||||
Note that the module in the synopsis doesn't export anything by default.
|
||||
If people load C<MyUtils> like this:
|
||||
|
||||
use MyUtils;
|
||||
|
||||
Then they haven't imported any functions. You can specify a default set
|
||||
of functions to be exported like this:
|
||||
|
||||
package MyUtils;
|
||||
|
||||
use Exporter::Shiny qw( frobnicate );
|
||||
|
||||
our @EXPORT = qw( frobnicate );
|
||||
|
||||
sub frobnicate { ... }
|
||||
|
||||
1;
|
||||
|
||||
Or, if you want to be a superstar rock god:
|
||||
|
||||
package MyUtils;
|
||||
|
||||
use Exporter::Shiny our @EXPORT = qw( frobnicate );
|
||||
|
||||
sub frobnicate { ... }
|
||||
|
||||
1;
|
||||
|
||||
=head3 Tags
|
||||
|
||||
You can provide tags for people to use:
|
||||
|
||||
package MyUtils;
|
||||
|
||||
use Exporter::Shiny qw( frobnicate red green blue );
|
||||
|
||||
our %EXPORT_TAGS = (
|
||||
utils => [qw/ frobnicate /],
|
||||
colours => [qw/ red green blue /],
|
||||
);
|
||||
|
||||
sub frobnicate { ... }
|
||||
sub red { ... }
|
||||
sub green { ... }
|
||||
sub blue { ... }
|
||||
|
||||
1;
|
||||
|
||||
And people can now import your functions like this:
|
||||
|
||||
use MyUtils ":colours";
|
||||
|
||||
Or this:
|
||||
|
||||
use MyUtils "-colours";
|
||||
|
||||
Or take advantage of the fact that Perl magically quotes barewords
|
||||
preceded by a hyphen:
|
||||
|
||||
use MyUtils -colours;
|
||||
|
||||
Two tags are automatically defined for you: C<< -default >> (which is
|
||||
just the same as C<< @EXPORT >>) and C<< -all >> (which is the union of
|
||||
C<< @EXPORT >> and C<< @EXPORT_OK >>). If you don't like them, then you
|
||||
can override them:
|
||||
|
||||
our %EXPORT_TAGS = (
|
||||
default => \@some_other_stuff,
|
||||
all => \@more_stuff,
|
||||
);
|
||||
|
||||
=head3 Generators
|
||||
|
||||
Exporting normally just works by copying a sub from your package into
|
||||
your caller's package. But sometimes it's useful instead to generate
|
||||
a I<custom> sub to insert into your caller's package. This is pretty
|
||||
easy to do.
|
||||
|
||||
package MyUtils;
|
||||
|
||||
use Exporter::Shiny qw( frobnicate );
|
||||
|
||||
sub _generate_frobnicate {
|
||||
my ( $me, $name, $args, $globals ) = @_;
|
||||
my $caller = $globals->{into};
|
||||
|
||||
return sub {
|
||||
...; # your code here
|
||||
};
|
||||
}
|
||||
|
||||
1;
|
||||
|
||||
The parameter C<< $me >> here is a string containing the package name
|
||||
which is being imported from; C<< $caller >> is the destination package;
|
||||
C<< $name >> is the name of the sub (in this case "frobnicate"); and
|
||||
C<< $args >> is a custom argument for this function. (By convention,
|
||||
C<< $args >> is normally a hashref.)
|
||||
|
||||
# The hashref { foo => 42 } is $args above.
|
||||
#
|
||||
use MyUtils "frobnicate" => { foo => 42 };
|
||||
|
||||
=head2 Avoiding Exporter::Shiny
|
||||
|
||||
Exporter::Shiny is a tiny shim around Exporter::Tiny. It should mostly
|
||||
do what you want, but you may sometimes prefer to use Exporter::Tiny
|
||||
directly.
|
||||
|
||||
The example in the synopsis could have been written as:
|
||||
|
||||
package MyUtils;
|
||||
|
||||
use parent "Exporter::Tiny";
|
||||
our @EXPORT_OK = qw( frobnicate );
|
||||
|
||||
sub frobnicate {
|
||||
...; # your code here
|
||||
}
|
||||
|
||||
1;
|
||||
|
||||
What Exporter::Shiny does is mostly just to set C<< @EXPORT_OK >> for
|
||||
you and set up inheritance from the base class (Exporter::Tiny).
|
||||
|
||||
Exporter::Shiny also sets C<< $INC{'MyUtils.pm'} >> for you, which in
|
||||
usually makes little difference, but is useful in some edge cases.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<Exporter::Shiny>,
|
||||
L<Exporter::Tiny>.
|
||||
|
||||
For more advanced information, see
|
||||
L<Exporter::Tiny::Manual::Exporting>.
|
||||
|
||||
=head1 AUTHOR
|
||||
|
||||
Toby Inkster E<lt>tobyink@cpan.orgE<gt>.
|
||||
|
||||
=head1 COPYRIGHT AND LICENCE
|
||||
|
||||
This software is copyright (c) 2013-2014, 2017 by Toby Inkster.
|
||||
|
||||
This is free software; you can redistribute it and/or modify it under
|
||||
the same terms as the Perl 5 programming language system itself.
|
||||
|
||||
=head1 DISCLAIMER OF WARRANTIES
|
||||
|
||||
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
|
||||
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
|
||||
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
|
||||
|
Reference in New Issue
Block a user