NAME
- Sub::Prototype::Util - Prototypes-related utility routines.
+ Sub::Prototype::Util - Prototype-related utility routines.
VERSION
- Version 0.01
+ Version 0.07
SYNOPSIS
- use Sub::Prototype::Util qw/flatten recall/;
+ use Sub::Prototype::Util qw/flatten recall wrap/;
my @a = qw/a b c/;
my @args = ( \@a, 1, { d => 2 }, undef, 3 );
my @flat = flatten '\@$;$', @args; # ('a', 'b', 'c', 1, { d => 2 })
recall 'CORE::push', @args; # @a contains 'a', 'b', 'c', 1, { d => 2 }, undef, 3
+ my $splice = wrap 'CORE::splice', compile => 1;
+ my @b = $splice->(\@a, 4, 2); # @a is now ('a', 'b', 'c', 1, 3) and @b is ({ d => 2 }, undef)
DESCRIPTION
Prototypes are evil, but sometimes you just have to bear with them,
especially when messing with core functions. This module provides
- several utilities aimed at faciliting "overloading" of prototyped
+ several utilities aimed at facilitating "overloading" of prototyped
functions.
They all handle 5.10's "_" prototype.
3". This is especially needed for core functions because you can't
"goto" into them.
+ You can also force the use of a specific prototype. In this case, $name
+ must be a hash reference that holds exactly one key/value pair, the key
+ being the function name and the value the prototpye that should be used
+ to call it.
+
+ recall { 'CORE::push' => '\@$' }, $a, 1, 2, 3; # will only push 1
+
+ This allows you to recall into "CORE::grep" and "CORE::map" by using the
+ "\&@" prototype :
+
+ sub mygrep (&@) { recall { 'CORE::grep' => '\&@' }, @_ } # the prototypes are intentionally different
+
+ "wrap $name, %opts"
+ Generates a wrapper that does the same thing as "recall", but
+ specialized for a given function. This wrapper can be compiled once for
+ all to avoid calling "eval" at each run (like "recall" does). You can
+ still force the prototype by passing "{ $name => $proto }" as the first
+ argument. Others arguments are seen as key / value pairs and tune the
+ code generated by "wrap". Valid keys are :
+
+ "ref => $func"
+ Specifies the function used in the generated code to test the
+ reference type of scalars. Defaults to 'ref'. You may also want to
+ use "Scalar::Util::reftype".
+
+ "wrong_ref => $code"
+ The code executed when a reference of incorrect type is encountered.
+ The result of this snippet is also the result of the generated code,
+ hence it defaults to 'undef'. It's a good place to "croak" or "die"
+ too.
+
+ "sub => $bool"
+ Encloses the code into a "sub { }" block. Default is true.
+
+ "compile => $bool"
+ Makes "wrap" compile the code generated and return the resulting
+ code reference. Implies "sub => 1". Be careful that in this case
+ "ref" must be a fully qualified function name. Defaults to false.
+
+ This is how you make your own "push" that pushes into array references :
+
+ my @a = (0 .. 2);
+ my $push = wrap 'CORE::push', compile => 1;
+ $push->(\@a, 3 .. 7); # returns 3 + 5 = 8, and @a now contains 0 .. 7
+
EXPORT
- The functions "flatten" and "recall" are only exported on request,
- either by providing their name or by the ':consts' and ':all' tags.
+ The functions "flatten", "recall" and "wrap" are only exported on
+ request, either by providing their name or by the ':funcs' and ':all'
+ tags.
DEPENDENCIES
- Carp (core module since perl 5), Scalar::Util (since 5.7.3).
+ Carp, Exporter (core modules since perl 5), Scalar::Util (since 5.7.3).
AUTHOR
Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.