X-Git-Url: http://git.vpit.fr/?a=blobdiff_plain;f=README;h=04da32e0b5761ce7e981ac4be67ba05c0194be4a;hb=576d9150e16d22ddc32e9d87cf60c03bf1ccb3b8;hp=20b9d5904e2d17b8ef5ae8a766d2e0f430cc3a30;hpb=4b145ee918e94698fe49c6e9240d50cfb2a36c75;p=perl%2Fmodules%2FSub-Prototype-Util.git diff --git a/README b/README index 20b9d59..04da32e 100644 --- a/README +++ b/README @@ -1,22 +1,24 @@ NAME - Sub::Prototype::Util - Prototypes-related utility routines. + Sub::Prototype::Util - Prototype-related utility routines. VERSION - Version 0.01 + Version 0.09 SYNOPSIS - use Sub::Prototype::Util qw/flatten recall/; + 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'; + 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. @@ -26,32 +28,79 @@ 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. + + "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. + + 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 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. + + my $push = wrap { 'CORE::push' => '\@$' }; # only pushes 1 arg + + 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 + 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. 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' => '\&@' }; + 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 define a subroutine with the - same prototype as $name. For example, + 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; + recall { 'CORE::push' => '\@$' }, $a, 1, 2, 3; # $a just contains 1 - 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. + 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" and "recall" are only exported on request, - either by providing their name or by the ':consts' and ':all' tags. + The functions "flatten", "wrap" and "recall" 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, "", . - 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 @@ -69,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.