X-Git-Url: http://git.vpit.fr/?p=perl%2Fmodules%2FSub-Prototype-Util.git;a=blobdiff_plain;f=README;h=ad69e34840c8e265741c6352da03ecbb056a2bcb;hp=a9792c1a0a74566a0b3d68975bd2279805897033;hb=HEAD;hpb=812065270f1262b670f91bc7de80f67c583a123e diff --git a/README b/README index a9792c1..ad69e34 100644 --- a/README +++ b/README @@ -2,16 +2,25 @@ NAME Sub::Prototype::Util - Prototype-related utility routines. VERSION - Version 0.06 + Version 0.11 SYNOPSIS - use Sub::Prototype::Util qw/flatten recall/; + use Sub::Prototype::Util qw; - my @a = qw/a b c/; + my @a = qw; 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 @flat = flatten '\@$;$', @args; + # @flat contains now ('a', 'b', 'c', 1, { d => 2 }) + + my $res = recall 'CORE::push', @args; + # @a contains now 'a', 'b', 'c', 1, { d => 2 }, undef, 3 + # and $res is 7 + + my $splice = wrap 'CORE::splice'; + my @b = $splice->(\@a, 4, 2); + # @a contains 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, @@ -22,71 +31,86 @@ DESCRIPTION They all handle 5.10's "_" prototype. FUNCTIONS - "flatten $proto, @args" + "flatten" + my @flattened = flatten($proto, @args); + 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, + "wrap" + my $wrapper = wrap($name, %opts); + my $wrapper = wrap({ $name => $proto }, %opts); - my $a = [ ]; - recall 'CORE::push', $a, 1, 2, 3; + 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 : + my $push = wrap { 'CORE::push' => '\@$' }; # only pushes 1 arg - sub mygrep (&@) { recall { 'CORE::grep' => '\&@' }, @_ } # the prototypes are intentionally different + The remaining arguments %opts are treated as key / value pairs that are + meant to tune the code generated by "wrap". Valid keys are : - "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" - "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". + use "reftype" in Scalar::Util. + + * "wrong_ref => $code" - "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" + * "sub => $bool" + Encloses the code into a "sub { }" block. Default is true. - "compile => $bool" + * "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 : + + my $grep = wrap { 'CORE::grep' => '\&@' }; + # the prototypes are intentionally different + sub mygrep (&@) { $grep->(@_) } + + "recall" + my @res = recall($name, @args); + my @res = recall({ $name => $proto }, @args); - This is how you make your own "push" that pushes into array references : + 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. @@ -96,8 +120,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 @@ -115,7 +138,7 @@ SUPPORT . COPYRIGHT & LICENSE - Copyright 2008 Vincent Pit, all rights reserved. + Copyright 2008,2009,2010,2011,2013 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.