Sub::Prototype::Util - Prototype-related utility routines.
VERSION
- Version 0.08
+ Version 0.09
SYNOPSIS
- use Sub::Prototype::Util qw/flatten recall wrap/;
+ use Sub::Prototype::Util qw/flatten wrap recall/;
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 $splice = wrap 'CORE::splice';
my @b = $splice->(\@a, 4, 2); # @a is now ('a', 'b', 'c', 1, 3) and @b is ({ d => 2 }, undef)
DESCRIPTION
Flattens the array @args according to the prototype $proto. When @args
is what @_ is after calling a subroutine with prototype $proto,
"flatten" returns the list of what @_ would have been if there were no
- prototype.
+ prototype. It croaks if the arguments can't possibly match the required
+ prototype, e.g. when a reference type is wrong or when not enough
+ elements were provided.
- "recall $name, @args"
- Calls the function $name with the prototyped argument list @args. That
- is, @args should be what @_ is when you define a subroutine with the
- same prototype as $name. For example,
-
- my $a = [ ];
- recall 'CORE::push', $a, 1, 2, 3;
+ "wrap $name, %opts"
+ Generates a wrapper that calls the function $name with a prototyped
+ argument list. That is, the wrapper's arguments should be what @_ is
+ when you define a subroutine with the same prototype as $name.
- will call "push @$a, 1, 2, 3" and so fill the arrayref $a with "1, 2,
- 3". This is especially needed for core functions because you can't
- "goto" into them.
+ my $a = [ 0 .. 2 ];
+ my $push = wrap 'CORE::push';
+ $push->($a, 3, 4); # returns 3 + 2 = 5 and $a now contains 0 .. 4
- 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
+ You can 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
+ my $push = wrap { 'CORE::push' => '\@$' }; # only pushes 1 arg
- "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 :
+ Others arguments are seen as key / value pairs that are meant to tune
+ the code generated by "wrap". Valid keys are :
"ref => $func"
Specifies the function used in the generated code to test the
"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.
+ code reference. Be careful that in this case "ref" must be a fully
+ qualified function name. Defaults to true, but turned off when "sub"
+ is false.
+
+ For example, this allows you to recall into "CORE::grep" and "CORE::map"
+ by using the "\&@" prototype :
- This is how you make your own "push" that pushes into array references :
+ my $grep = wrap { 'CORE::grep' => '\&@' };
+ sub mygrep (&@) { $grep->(@_) } # the prototypes are intentionally different
+
+ "recall $name, @args"
+ Calls the function $name with the prototyped argument list @args. That
+ is, @args should be what @_ is when you call a subroutine with $name as
+ prototype. You can still force the prototype by passing "{ $name =>
+ $proto }" as the first argument.
+
+ my $a = [ ];
+ recall { 'CORE::push' => '\@$' }, $a, 1, 2, 3; # $a just contains 1
- 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
+ It's implemented in terms of "wrap", and hence calls "eval" at each run.
+ If you plan to recall several times, consider using "wrap" instead.
EXPORT
- The functions "flatten", "recall" and "wrap" are only exported on
+ The functions "flatten", "wrap" and "recall" are only exported on
request, either by providing their name or by the ':funcs' and ':all'
tags.
AUTHOR
Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
- You can contact me by mail or on #perl @ FreeNode (vincent or
- Prof_Vince).
+ You can contact me by mail or on "irc.perl.org" (vincent).
BUGS
Please report any bugs or feature requests to "bug-sub-prototype-util at
<http://www.profvince.com/perl/cover/Sub-Prototype-Util>.
COPYRIGHT & LICENSE
- Copyright 2008 Vincent Pit, all rights reserved.
+ Copyright 2008-2009 Vincent Pit, all rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
projects / perl / modules / Sub-Prototype-Util.git / commitdiff