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

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

diff --git a/README b/README
index 2971b31c9f02803257832191dfff9722047720c0..316b1f609e8360c89476d3912457e8a9264c13d8 100644 (file)
--- a/README
+++ b/README
@@ -2,16 +2,18 @@ NAME
     Sub::Prototype::Util - Prototype-related utility routines.
 
 VERSION
-    Version 0.04
+    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,
@@ -40,9 +42,55 @@ FUNCTIONS
     3". This is especially needed for core functions because you can't
     "goto" into them.
 
+    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
+    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
+
+  "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).