.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.48)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "Sub::Exporter::Util 3"
.TH Sub::Exporter::Util 3 2026-10-25 "perl v5.44.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 DESCRIPTION
.IX Header "DESCRIPTION"
This module provides a number of utility functions for performing common or
useful operations when setting up a Sub::Exporter configuration.  All of the
utilities may be exported, but none are by default.
.SH "THE UTILITIES"
.IX Header "THE UTILITIES"
.SS curry_method
.IX Subsection "curry_method"
.Vb 3
\&  exports => {
\&    some_method => curry_method,
\&  }
.Ve
.PP
This utility returns a generator which will produce an invocant\-curried version
of a method.  In other words, it will export a method call with the exporting
class built in as the invocant.
.PP
A module importing the code some the above example might do this:
.PP
.Vb 1
\&  use Some::Module qw(some_method);
\&
\&  my $x = some_method;
.Ve
.PP
This would be equivalent to:
.PP
.Vb 1
\&  use Some::Module;
\&
\&  my $x = Some::Module\->some_method;
.Ve
.PP
If Some::Module is subclassed and the subclass\*(Aqs import method is called to
import \f(CW\*(C`some_method\*(C'\fR, the subclass will be curried in as the invocant.
.PP
If an argument is provided for \f(CW\*(C`curry_method\*(C'\fR it is used as the name of the
curried method to export.  This means you could export a Widget constructor
like this:
.PP
.Vb 1
\&  exports => { widget => curry_method(\*(Aqnew\*(Aq) }
.Ve
.PP
This utility may also be called as \f(CW\*(C`curry_class\*(C'\fR, for backwards compatibility.
.SS curry_chain
.IX Subsection "curry_chain"
\&\f(CW\*(C`curry_chain\*(C'\fR behaves like \f(CW"curry_method"\fR, but is meant for generating
exports that will call several methods in succession.
.PP
.Vb 5
\&  exports => {
\&    reticulate => curry_chain(
\&      new => gather_data => analyze => [ detail => 100 ] => \*(Aqresults\*(Aq
\&    ),
\&  }
.Ve
.PP
If imported from Spliner, calling the \f(CW\*(C`reticulate\*(C'\fR routine will be equivalent
to:
.PP
.Vb 1
\&  Spliner\->new\->gather_data\->analyze(detail => 100)\->results;
.Ve
.PP
If any method returns something on which methods may not be called, the routine
croaks.
.PP
The arguments to \f(CW\*(C`curry_chain\*(C'\fR form an optlist.  The names are methods to be
called and the arguments, if given, are arrayrefs to be dereferenced and passed
as arguments to those methods.  \f(CW\*(C`curry_chain\*(C'\fR returns a generator like those
expected by Sub::Exporter.
.PP
\&\fBAchtung!\fR at present, there is no way to pass arguments from the generated
routine to the method calls.  This will probably be solved in future revisions
by allowing the opt list\*(Aqs values to be subroutines that will be called with
the generated routine\*(Aqs stack.
.SS merge_col
.IX Subsection "merge_col"
.Vb 6
\&  exports => {
\&    merge_col(defaults => {
\&      twiddle => \e\*(Aq_twiddle_gen\*(Aq,
\&      tweak   => \e&_tweak_gen,
\&    }),
\&  }
.Ve
.PP
This utility wraps the given generator in one that will merge the named
collection into its args before calling it.  This means that you can support a
"default" collector in multiple exports without writing the code each time.
.PP
You can specify as many pairs of collection names and generators as you like.
.SS mixin_installer
.IX Subsection "mixin_installer"
.Vb 4
\&  use Sub::Exporter \-setup => {
\&    installer => Sub::Exporter::Util::mixin_installer,
\&    exports   => [ qw(foo bar baz) ],
\&  };
.Ve
.PP
This utility returns an installer that will install into a superclass and
adjust the ISA importing class to include the newly generated superclass.
.PP
If the target of importing is an object, the hierarchy is reversed: the new
class will be ISA the object\*(Aqs class, and the object will be reblessed.
.PP
\&\fBPrerequisites\fR: This utility requires that Package::Generator be installed.
.SS like
.IX Subsection "like"
It\*(Aqs a collector that adds imports for anything like given regex.
.PP
If you provide this configuration:
.PP
.Vb 2
\&  exports    => [ qw(igrep imap islurp exhausted) ],
\&  collectors => { \-like => Sub::Exporter::Util::like },
.Ve
.PP
A user may import from your module like this:
.PP
.Vb 1
\&  use Your::Iterator \-like => qr/^i/; # imports igre, imap, islurp
.Ve
.PP
or
.PP
.Vb 1
\&  use Your::Iterator \-like => [ qr/^i/ => { \-prefix => \*(Aqyour_\*(Aq } ];
.Ve
.PP
The group\-like prefix and suffix arguments are respected; other arguments are
passed on to the generators for matching exports.