Importing Sub-Prototype-Util-0.06.tar.gz

[perl/modules/Sub-Prototype-Util.git] / README

diff --git a/README b/README
index 915c7892431054b6ac34706ce98f6e75e0dd6add..a9792c1a0a74566a0b3d68975bd2279805897033 100644 (file)
--- a/README
+++ b/README
@@ -2,7 +2,7 @@ NAME
     Sub::Prototype::Util - Prototype-related utility routines.
 
 VERSION
-    Version 0.05
+    Version 0.06
 
 SYNOPSIS
         use Sub::Prototype::Util qw/flatten recall/;
@@ -52,9 +52,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).