X-Git-Url: http://git.vpit.fr/?p=perl%2Fmodules%2FSub-Prototype-Util.git;a=blobdiff_plain;f=README;h=04da32e0b5761ce7e981ac4be67ba05c0194be4a;hp=316b1f609e8360c89476d3912457e8a9264c13d8;hb=ca9ceb4f24802eebce590c2adcb09f8e170146c9;hpb=861f5f77448b046e9c7180f348200a7fedd08b11 diff --git a/README b/README index 316b1f6..04da32e 100644 --- a/README +++ b/README @@ -2,17 +2,17 @@ NAME 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 @@ -28,39 +28,28 @@ FUNCTIONS 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 @@ -78,17 +67,30 @@ FUNCTIONS "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. @@ -98,8 +100,7 @@ DEPENDENCIES AUTHOR Vincent Pit, "", . - 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 @@ -117,7 +118,7 @@ SUPPORT . 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.