.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Tidy 3pm" .TH Tidy 3pm "2022-06-13" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Exporter::Tidy \- Another way of exporting symbols .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 4 \& package MyModule::HTTP; \& use Exporter::Tidy \& default => [ qw(get) ], \& other => [ qw(post head) ]; \& \& use MyModule::HTTP qw(:all); \& use MyModule::HTTP qw(:default post); \& use MyModule::HTTP qw(post); \& use MyModule::HTTP _prefix => \*(Aqhttp_\*(Aq, qw(get post); \& use MyModule::HTTP qw(get post), _prefix => \*(Aqhttp_\*(Aq, qw(head); \& use MyModule::HTTP \& _prefix => \*(Aqfoo\*(Aq, qw(get post), \& _prefix => \*(Aqbar\*(Aq, qw(get head); \& \& package MyModule::Foo; \& use Exporter::Tidy \& default => [ qw($foo $bar quux) ], \& _map => { \& \*(Aq$foo\*(Aq => \e$my_foo, \& \*(Aq$bar\*(Aq => \e$my_bar, \& quux => sub { print "Hello, world!\en" } \& }; \& \& package MyModule::Constants; \& use Exporter::Tidy \& default => [ qw(:all) ], \& _map => { \& FOO => sub () { 1 }, \& BAR => sub () { 2 }, \& OK => sub () { 1 }, \& FAILURE => sub () { 0 } \& }; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module serves as an easy, clean alternative to Exporter. Unlike Exporter, it is not subclassed, but it simply exports a custom \fBimport()\fR into your namespace. .PP With Exporter::Tidy, you don't need to use any package global in your module. Even the subs you export can be lexically scoped. .SS "use Exporter::Tidy \s-1LIST\s0" .IX Subsection "use Exporter::Tidy LIST" The list supplied to \f(CW\*(C`use Exporter::Tidy\*(C'\fR should be a key-value list. Each key serves as a tag, used to group exportable symbols. The values in this key-value list should be array references. There are a few special tags: .IP "all" 10 .IX Item "all" If you don't provide an \f(CW\*(C`all\*(C'\fR tag yourself, Tidy::Exporter will generate one for you. It will contain all exportable symbols. .IP "default" 10 .IX Item "default" The \f(CW\*(C`default\*(C'\fR tag will be used if the user supplies no list to the \f(CW\*(C`use\*(C'\fR statement. .IP "_map" 10 .IX Item "_map" With _map you should not use an array reference, but a hash reference. Here, you can rewrite symbols to other names or even define one on the spot by using a reference. You can \f(CW\*(C`foo => \*(Aqbar\*(Aq\*(C'\fR to export \f(CW\*(C`bar\*(C'\fR if \f(CW\*(C`foo\*(C'\fR is requested. .SS "Exportable symbols" .IX Subsection "Exportable symbols" Every symbol specified in a tag's array, or used as a key in _map's hash is exportable. .SS "Symbol types" .IX Subsection "Symbol types" You can export subs, scalars, arrays, hashes and typeglobs. Do not use an ampersand (\f(CW\*(C`&\*(C'\fR) for subs. All other types must have the proper sigil. .SS "Importing from a module that uses Exporter::Tidy" .IX Subsection "Importing from a module that uses Exporter::Tidy" You can use either a symbol name (without the sigil if it is a sub, or with the appropriate sigil if it is not), or a tag name prefixed with a colon. It is possible to import a symbol twice, but a symbol is never exported twice under the same name, so you can use tags that overlap. If you supply any list to the \f(CW\*(C`use\*(C'\fR statement, \f(CW\*(C`:default\*(C'\fR is no longer used if not specified explicitly. .PP To avoid name clashes, it is possible to have symbols prefixed. Supply \&\f(CW\*(C`_prefix\*(C'\fR followed by the prefix that you want. Multiple can be used. .PP .Vb 1 \& use Some::Module qw(foo bar), _prefix => \*(Aqsome_\*(Aq, qw(quux); .Ve .PP imports Some::Module::foo as foo, Some::Module::bar as bar, and Some::Module::quux as some_quux. See the \s-1SYNOPSIS\s0 for more examples. .SH "COMPARISON" .IX Header "COMPARISON" Exporter::Tidy \*(L"versus\*(R" Exporter .PP These numbers are valid for my Linux system with Perl 5.8.0. Your mileage may vary. .SS "Speed" .IX Subsection "Speed" Exporting two symbols using no import list (@EXPORT and :default) is approximately 10% faster with Exporter. But if you use any tag explicitly, Exporter::Tidy is more than twice as fast (!) as Exporter. .SS "Memory usage" .IX Subsection "Memory usage" .Vb 1 \& perl \-le\*(Aqrequire X; print((split " ", \`cat /proc/$$/stat\`)[22])\*(Aq \& \& No module 3022848 \& Exporter::Tidy 3067904 \& Exporter 3084288 \& Exporter::Heavy 3174400 .Ve .PP Exporter loads Exporter::Heavy automatically when needed. It is needed to support exporter tags, amongst other things. Exporter::Tidy has all functionality built into one module. .PP Both Exporter(::Heavy) and Exporter::Tidy delay loading Carp until it is needed. .SS "Usage" .IX Subsection "Usage" Exporter is subclassed and gets its information from package global variables like \f(CW@EXPORT\fR, \f(CW@EXPORT_OK\fR and \f(CW%EXPORT_TAGS\fR. .PP Exporter::Tidy exports an \f(CW\*(C`import\*(C'\fR method and gets its information from the \f(CW\*(C`use\*(C'\fR statement. .SH "LICENSE" .IX Header "LICENSE" Pick your favourite \s-1OSI\s0 approved license :) .PP http://www.opensource.org/licenses/alphabetical .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" Thanks to Aristotle Pagaltzis for suggesting the name Exporter::Tidy. .SH "AUTHOR" .IX Header "AUTHOR" Juerd Waalboer