--- /dev/null
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sh \" Subsection heading
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.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. | will give a
+.\" real vertical bar. \*(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-|\(bv\*(Tr
+.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" ''
+'br\}
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.\"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "Sub::Exporter::Tutorial 3"
+.TH Sub::Exporter::Tutorial 3 "2008-11-21" "perl v5.8.7" "User Contributed Perl Documentation"
+.SH "NAME"
+Sub::Exporter::Tutorial \- a friendly guide to exporting with Sub::Exporter
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+.Sh "What's an Exporter?"
+.IX Subsection "What's an Exporter?"
+When you \f(CW\*(C`use\*(C'\fR a module, first it is required, then its \f(CW\*(C`import\*(C'\fR method is
+called. The Perl documentation tells us that the following two lines are
+equivalent:
+.PP
+.Vb 1
+\& use Module LIST;
+.Ve
+.PP
+.Vb 1
+\& BEGIN { require Module; Module\->import(LIST); }
+.Ve
+.PP
+The import method is the module's \fIexporter\fR.
+.Sh "The Basics of Sub::Exporter"
+.IX Subsection "The Basics of Sub::Exporter"
+Sub::Exporter builds a custom exporter which can then be installed into your
+module. It builds this method based on configuration passed to its
+\&\f(CW\*(C`setup_exporter\*(C'\fR method.
+.PP
+A very basic use case might look like this:
+.PP
+.Vb 3
+\& package Addition;
+\& use Sub::Exporter;
+\& Sub::Exporter::setup_exporter({ exports => [ qw(plus) ]});
+.Ve
+.PP
+.Vb 1
+\& sub plus { my ($x, $y) = @_; return $x + $y; }
+.Ve
+.PP
+This would mean that when someone used your Addition module, they could have
+its \f(CW\*(C`plus\*(C'\fR routine imported into their package:
+.PP
+.Vb 1
+\& use Addition qw(plus);
+.Ve
+.PP
+.Vb 1
+\& my $z = plus(2, 2); # this works, because now plus is in the main package
+.Ve
+.PP
+That syntax to set up the exporter, above, is a little verbose, so for the
+simple case of just naming some exports, you can write this:
+.PP
+.Vb 1
+\& use Sub::Exporter \-setup => { exports => [ qw(plus) ] };
+.Ve
+.PP
+\&...which is the same as the original example \*(-- except that now the exporter is
+built and installed at compile time. Well, that and you typed less.
+.Sh "Using Export Groups"
+.IX Subsection "Using Export Groups"
+You can specify whole groups of things that should be exportable together.
+These are called groups. Exporter calls these tags. To specify groups, you
+just pass a \f(CW\*(C`groups\*(C'\fR key in your exporter configuration:
+.PP
+.Vb 8
+\& package Food;
+\& use Sub::Exporter \-setup => {
+\& exports => [ qw(apple banana beef fluff lox rabbit) ],
+\& groups => {
+\& fauna => [ qw(beef lox rabbit) ],
+\& flora => [ qw(apple banana) ],
+\& }
+\& };
+.Ve
+.PP
+Now, to import all that delicious foreign meat, your consumer needs only to
+write:
+.PP
+.Vb 2
+\& use Food qw(:fauna);
+\& use Food qw(\-fauna);
+.Ve
+.PP
+Either one of the above is acceptable. A colon is more traditional, but
+barewords with a leading colon can't be enquoted by a fat arrow. We'll see why
+that matters later on.
+.PP
+Groups can contain other groups. If you include a group name (with the leading
+dash or colon) in a group definition, it will be expanded recursively when the
+exporter is called. The exporter will \fBnot\fR recurse into the same group twice
+while expanding groups.
+.PP
+There are two special groups: \f(CW\*(C`all\*(C'\fR and \f(CW\*(C`default\*(C'\fR. The \f(CW\*(C`all\*(C'\fR group is
+defined by default, and contains all exportable subs. You can redefine it,
+if you want to export only a subset when all exports are requested. The
+\&\f(CW\*(C`default\*(C'\fR group is the set of routines to export when nothing specific is
+requested. By default, there is no \f(CW\*(C`default\*(C'\fR group.
+.Sh "Renaming Your Imports"
+.IX Subsection "Renaming Your Imports"
+Sometimes you want to import something, but you don't like the name as which
+it's imported. Sub::Exporter can rename your imports for you. If you wanted
+to import \f(CW\*(C`lox\*(C'\fR from the Food package, but you don't like the name, you could
+write this:
+.PP
+.Vb 1
+\& use Food lox => { \-as => 'salmon' };
+.Ve
+.PP
+Now you'd get the \f(CW\*(C`lox\*(C'\fR routine, but it would be called salmon in your
+package. You can also rename entire groups by using the \f(CW\*(C`prefix\*(C'\fR option:
+.PP
+.Vb 1
+\& use Food \-fauna => { \-prefix => 'cute_little_' };
+.Ve
+.PP
+Now you can call your \f(CW\*(C`cute_little_rabbit\*(C'\fR routine. (You can also call
+\&\f(CW\*(C`cute_little_beef\*(C'\fR, but that hardly seems as enticing.)
+.PP
+When you define groups, you can include renaming.
+.PP
+.Vb 6
+\& use Sub::Exporter \-setup => {
+\& exports => [ qw(apple banana beef fluff lox rabbit) ],
+\& groups => {
+\& fauna => [ qw(beef lox), rabbit => { \-as => 'coney' } ],
+\& }
+\& };
+.Ve
+.PP
+A prefix on a group like that does the right thing. This is when it's useful
+to use a dash instead of a colon to indicate a group: you can put a fat arrow
+between the group and its arguments, then.
+.PP
+.Vb 1
+\& use Food \-fauna => { \-prefix => 'lovely_' };
+.Ve
+.PP
+.Vb 1
+\& eat( lovely_coney ); # this works
+.Ve
+.PP
+Prefixes also apply recursively. That means that this code works:
+.PP
+.Vb 7
+\& use Sub::Exporter \-setup => {
+\& exports => [ qw(apple banana beef fluff lox rabbit) ],
+\& groups => {
+\& fauna => [ qw(beef lox), rabbit => { \-as => 'coney' } ],
+\& allowed => [ \-fauna => { \-prefix => 'willing_' }, 'banana' ],
+\& }
+\& };
+.Ve
+.PP
+.Vb 1
+\& ...
+.Ve
+.PP
+.Vb 1
+\& use Food \-allowed => { \-prefix => 'any_' };
+.Ve
+.PP
+.Vb 1
+\& $dinner = any_willing_coney; # yum!
+.Ve
+.PP
+Groups can also be passed a \f(CW\*(C`\-suffix\*(C'\fR argument.
+.PP
+Finally, if the \f(CW\*(C`\-as\*(C'\fR argument to an exported routine is a reference to a
+scalar, a reference to the routine will be placed in that scalar.
+.Sh "Building Subroutines to Order"
+.IX Subsection "Building Subroutines to Order"
+Sometimes, you want to export things that you don't have on hand. You might
+want to offer customized routines built to the specification of your consumer;
+that's just good business! With Sub::Exporter, this is easy.
+.PP
+To offer subroutines to order, you need to provide a generator when you set up
+your exporter. A generator is just a routine that returns a new routine.
+perlref is talking about these when it discusses closures and function
+templates. The canonical example of a generator builds a unique incrementor;
+here's how you'd do that with Sub::Exporter;
+.PP
+.Vb 5
+\& package Package::Counter;
+\& use Sub::Exporter \-setup => {
+\& exports => [ counter => sub { my $i = 0; sub { $i++ } } ],
+\& groups => { default => [ qw(counter) ] },
+\& };
+.Ve
+.PP
+Now anyone can use your Package::Counter module and he'll receive a \f(CW\*(C`counter\*(C'\fR
+in his package. It will count up by one, and will never interfere with anyone
+else's counter.
+.PP
+This isn't very useful, though, unless the consumer can explain what he wants.
+This is done, in part, by supplying arguments when importing. The following
+example shows how a generator can take and use arguments:
+.PP
+.Vb 1
+\& package Package::Counter;
+.Ve
+.PP
+.Vb 6
+\& sub _build_counter {
+\& my ($class, $arg) = @_;
+\& $arg ||= {};
+\& my $i = $arg\->{start} || 0;
+\& return sub { $i++ };
+\& }
+.Ve
+.PP
+.Vb 4
+\& use Sub::Exporter \-setup => {
+\& exports => [ counter => \e'_build_counter' ],
+\& groups => { default => [ qw(counter) ] },
+\& };
+.Ve
+.PP
+Now, the consumer can (if he wants) specify a starting value for his counter:
+.PP
+.Vb 1
+\& use Package::Counter counter => { start => 10 };
+.Ve
+.PP
+Arguments to a group are passed along to the generators of routines in that
+group, but Sub::Exporter arguments \*(-- anything beginning with a dash \*(-- are
+never passed in. When groups are nested, the arguments are merged as the
+groups are expanded.
+.PP
+Notice, too, that in the example above, we gave a reference to a method \fIname\fR
+rather than a method \fIimplementation\fR. By giving the name rather than the
+subroutine, we make it possible for subclasses of our \*(L"Package::Counter\*(R" module
+to replace the \f(CW\*(C`_build_counter\*(C'\fR method.
+.PP
+When a generator is called, it is passed four parameters:
+.IP "* the invocant on which the exporter was called" 4
+.IX Item "the invocant on which the exporter was called"
+.PD 0
+.IP "* the name of the export being generated (not the name it's being installed as)" 4
+.IX Item "the name of the export being generated (not the name it's being installed as)"
+.IP "* the arguments supplied for the routine" 4
+.IX Item "the arguments supplied for the routine"
+.IP "* the collection of generic arguments" 4
+.IX Item "the collection of generic arguments"
+.PD
+.PP
+The fourth item is the last major feature that hasn't been covered.
+.Sh "Argument Collectors"
+.IX Subsection "Argument Collectors"
+Sometimes you will want to accept arguments once that can then be available to
+any subroutine that you're going to export. To do this, you specify
+collectors, like this:
+.PP
+.Vb 6
+\& use Menu::Airline
+\& use Sub::Exporter \-setup => {
+\& exports => ... ,
+\& groups => ... ,
+\& collectors => [ qw(allergies ethics) ],
+\& };
+.Ve
+.PP
+Collectors look like normal exports in the import call, but they don't do
+anything but collect data which can later be passed to generators. If the
+module was used like this:
+.PP
+.Vb 1
+\& use Menu::Airline allergies => [ qw(peanuts) ], ethics => [ qw(vegan) ];
+.Ve
+.PP
+\&...the consumer would get a salad. Also, all the generators would be passed,
+as their fourth argument, something like this:
+.PP
+.Vb 1
+\& { allerges => [ qw(peanuts) ], ethics => [ qw(vegan) ] }
+.Ve
+.PP
+Generators may have arguments in their definition, as well. These must be code
+refs that perform validation of the collected values. They are passed the
+collection value and may return true or false. If they return false, the
+exporter will throw an exception.
+.Sh "Generating Many Routines in One Scope"
+.IX Subsection "Generating Many Routines in One Scope"
+Sometimes it's useful to have multiple routines generated in one scope. This
+way they can share lexical data which is otherwise unavailable. To do this,
+you can supply a generator for a group which returns a hashref of names and
+code references. This generator is passed all the usual data, and the group
+may receive the usual \f(CW\*(C`\-prefix\*(C'\fR or \f(CW\*(C`\-suffix\*(C'\fR arguments.
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Ricardo \s-1SIGNES\s0, \f(CW\*(C`<rjbs@cpan.org>\*(C'\fR
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+.IP "* Sub::Exporter for complete documentation and references to other exporters." 4
+.IX Item "Sub::Exporter for complete documentation and references to other exporters."
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright 2007 Ricardo \s-1SIGNES\s0. This program is free software; you can
+redistribute it and/or modify it under the same terms as Perl itself.
projects / catagits/Gitalist.git / blobdiff