local-lib5/man/man3/Sub::Exporter::Util.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Sub::Exporter::Util 3"
 132 .TH Sub::Exporter::Util 3 "2009-01-16" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Sub::Exporter::Util \- utilities to make Sub::Exporter easier
 135 .SH "VERSION"
 136 .IX Header "VERSION"
 137 version 0.982
 138 .SH "DESCRIPTION"
 139 .IX Header "DESCRIPTION"
 140 This module provides a number of utility functions for performing common or
 141 useful operations when setting up a Sub::Exporter configuration.  All of the
 142 utilites may be exported, but none are by default.
 143 .SH "THE UTILITIES"
 144 .IX Header "THE UTILITIES"
 145 .Sh "curry_method"
 146 .IX Subsection "curry_method"
 147 .Vb 3
 148 \&  exports => {
 149 \&    some_method => curry_method,
 150 \&  }
 151 .Ve
 152 .PP
 153 This utility returns a generator which will produce an invocant-curried version
 154 of a method.  In other words, it will export a method call with the exporting
 155 class built in as the invocant.
 156 .PP
 157 A module importing the code some the above example might do this:
 158 .PP
 159 .Vb 1
 160 \&  use Some::Module qw(some_method);
 161 .Ve
 162 .PP
 163 .Vb 1
 164 \&  my $x = some_method;
 165 .Ve
 166 .PP
 167 This would be equivalent to:
 168 .PP
 169 .Vb 1
 170 \&  use Some::Module;
 171 .Ve
 172 .PP
 173 .Vb 1
 174 \&  my $x = Some::Module\->some_method;
 175 .Ve
 176 .PP
 177 If Some::Module is subclassed and the subclass's import method is called to
 178 import \f(CW\*(C`some_method\*(C'\fR, the subclass will be curried in as the invocant.
 179 .PP
 180 If an argument is provided for \f(CW\*(C`curry_method\*(C'\fR it is used as the name of the
 181 curried method to export.  This means you could export a Widget constructor
 182 like this:
 183 .PP
 184 .Vb 1
 185 \&  exports => { widget => curry_method('new') }
 186 .Ve
 187 .PP
 188 This utility may also be called as \f(CW\*(C`curry_class\*(C'\fR, for backwards compatibility.
 189 .Sh "curry_chain"
 190 .IX Subsection "curry_chain"
 191 \&\f(CW\*(C`curry_chain\*(C'\fR behaves like \f(CW\*(C`\*(L"curry_method\*(R"\*(C'\fR, but is meant for generating
 192 exports that will call several methods in succession.
 193 .PP
 194 .Vb 5
 195 \&  exports => {
 196 \&    reticulate => curry_chain([
 197 \&      new => gather_data => analyze => [ detail => 100 ] => results
 198 \&    ]),
 199 \&  }
 200 .Ve
 201 .PP
 202 If imported from Spliner, calling the \f(CW\*(C`reticulate\*(C'\fR routine will be equivalent
 203 to:
 204 .PP
 205 .Vb 1
 206 \&  Splinter\->new\->gather_data\->analyze(detail => 100)\->results;
 207 .Ve
 208 .PP
 209 If any method returns something on which methods may not be called, the routine
 210 croaks.
 211 .PP
 212 The arguments to \f(CW\*(C`curry_chain\*(C'\fR form an optlist.  The names are methods to be
 213 called and the arguments, if given, are arrayrefs to be dereferenced and passed
 214 as arguments to those methods.  \f(CW\*(C`curry_chain\*(C'\fR returns a generator like those
 215 expected by Sub::Exporter.
 216 .PP
 217 \&\fBAchtung!\fR at present, there is no way to pass arguments from the generated
 218 routine to the method calls.  This will probably be solved in future revisions
 219 by allowing the opt list's values to be subroutines that will be called with
 220 the generated routine's stack.
 221 .Sh "merge_col"
 222 .IX Subsection "merge_col"
 223 .Vb 6
 224 \&  exports => {
 225 \&    merge_col(defaults => {
 226 \&      twiddle => \e'_twiddle_gen',
 227 \&      tweak   => \e&_tweak_gen,
 228 \&    }),
 229 \&  }
 230 .Ve
 231 .PP
 232 This utility wraps the given generator in one that will merge the named
 233 collection into its args before calling it.  This means that you can support a
 234 \&\*(L"default\*(R" collector in multipe exports without writing the code each time.
 235 .PP
 236 You can specify as many pairs of collection names and generators as you like.
 237 .Sh "mixin_installer"
 238 .IX Subsection "mixin_installer"
 239 .Vb 4
 240 \&  use Sub::Exporter \-setup => {
 241 \&    installer => Sub::Exporter::Util::mixin_installer,
 242 \&    exports   => [ qw(foo bar baz) ],
 243 \&  };
 244 .Ve
 245 .PP
 246 This utility returns an installer that will install into a superclass and
 247 adjust the \s-1ISA\s0 importing class to include the newly generated superclass.
 248 .PP
 249 If the target of importing is an object, the hierarchy is reversed: the new
 250 class will be \s-1ISA\s0 the object's class, and the object will be reblessed.
 251 .PP
 252 \&\fBPrerequisites\fR: This utility requires that Package::Generator be installed.
 253 .Sh "like"
 254 .IX Subsection "like"
 255 It's a collector that adds imports for anything like given regex.
 256 .PP
 257 If you provide this configuration:
 258 .PP
 259 .Vb 2
 260 \&  exports    => [ qw(igrep imap islurp exhausted) ],
 261 \&  collectors => { \-like => Sub::Exporter::Util::like },
 262 .Ve
 263 .PP
 264 A user may import from your module like this:
 265 .PP
 266 .Vb 1
 267 \&  use Your::Iterator \-like => qr/^i/; # imports igre, imap, islurp
 268 .Ve
 269 .PP
 270 or
 271 .PP
 272 .Vb 1
 273 \&  use Your::Iterator \-like => [ qr/^i/ => { \-prefix => 'your_' } ];
 274 .Ve
 275 .PP
 276 The group-like prefix and suffix arguments are respected; other arguments are
 277 passed on to the generators for matching exports.
 278 .SH "AUTHOR"
 279 .IX Header "AUTHOR"
 280 Ricardo \s-1SIGNES\s0, \f(CW\*(C`<rjbs@cpan.org>\*(C'\fR
 281 .SH "BUGS"
 282 .IX Header "BUGS"
 283 Please report any bugs or feature requests through the web interface at
 284 <http://rt.cpan.org>. I will be notified, and then you'll automatically be
 285 notified of progress on your bug as I make changes.
 286 .SH "COPYRIGHT"
 287 .IX Header "COPYRIGHT"
 288 Copyright 2006\-2007, Ricardo \s-1SIGNES\s0.  This program is free software;  you can
 289 redistribute it and/or modify it under the same terms as Perl itself.