X-Git-Url: http://git.vpit.fr/?p=perl%2Fmodules%2FSub-Prototype-Util.git;a=blobdiff_plain;f=README;h=316b1f609e8360c89476d3912457e8a9264c13d8;hp=915c7892431054b6ac34706ce98f6e75e0dd6add;hb=cdcb726f9c5b8e0414ea40052350331c72c637c8;hpb=29d3a214c70390edd665985eddfb42ff7e29a02a

diff --git a/README b/README
index 915c789..316b1f6 100644
--- a/README
+++ b/README
@@ -2,16 +2,18 @@ NAME
     Sub::Prototype::Util - Prototype-related utility routines.
 
 VERSION
-    Version 0.05
+    Version 0.08
 
 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,
@@ -52,9 +54,43 @@ FUNCTIONS
 
         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 ':funcs' 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, Exporter (core modules since perl 5), Scalar::Util (since 5.7.3).