This is 0.11

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

diff --git a/README b/README
index 040b0e70e3f3bb7106b0f2a6a05434bd16ff4fbe..ad69e34840c8e265741c6352da03ecbb056a2bcb 100644 (file)
--- a/README
+++ b/README
@@ -2,7 +2,7 @@ NAME
     Sub::Prototype::Util - Prototype-related utility routines.
 
 VERSION
-    Version 0.10
+    Version 0.11
 
 SYNOPSIS
         use Sub::Prototype::Util qw<flatten wrap recall>;
@@ -10,10 +10,17 @@ SYNOPSIS
         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 @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 is now ('a', 'b', 'c', 1, 3) and @b is ({ d => 2 }, undef)
+        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,
@@ -24,7 +31,9 @@ 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
@@ -32,7 +41,10 @@ FUNCTIONS
     prototype, e.g. when a reference type is wrong or when not enough
     elements were provided.
 
-  "wrap $name, %opts"
+  "wrap"
+        my $wrapper = wrap($name, %opts);
+        my $wrapper = wrap({ $name => $proto }, %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.
@@ -48,24 +60,28 @@ FUNCTIONS
 
         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 :
+    The remaining arguments %opts are treated as key / value pairs that are
+    meant to 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 "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. Be careful that in this case "ref" must be a fully
         qualified function name. Defaults to true, but turned off when "sub"
@@ -75,9 +91,13 @@ FUNCTIONS
     by using the "\&@" prototype :
 
         my $grep = wrap { 'CORE::grep' => '\&@' };
-        sub mygrep (&@) { $grep->(@_) } # the prototypes are intentionally different
+        # the prototypes are intentionally different
+        sub mygrep (&@) { $grep->(@_) }
+
+  "recall"
+        my @res = recall($name, @args);
+        my @res = recall({ $name => $proto }, @args);
 
-  "recall $name, @args"
     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 =>
@@ -118,7 +138,7 @@ SUPPORT
     <http://www.profvince.com/perl/cover/Sub-Prototype-Util>.
 
 COPYRIGHT & LICENSE
-    Copyright 2008,2009,2010,2011 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.