Add missing bullets to POD items

[perl/modules/Sub-Prototype-Util.git] / lib / Sub / Prototype / Util.pm

diff --git a/lib/Sub/Prototype/Util.pm b/lib/Sub/Prototype/Util.pm
index efcd9749771bafbedce3173e8970a399da6a3422..b2f67a7f81aa703868e3d5217232265446aeaa87 100644 (file)
--- a/lib/Sub/Prototype/Util.pm
+++ b/lib/Sub/Prototype/Util.pm
@@ -5,8 +5,8 @@ use 5.006;
 use strict;
 use warnings;
 
-use Carp qw/croak/;
-use Scalar::Util qw/reftype/;
+use Carp         qw<croak>;
+use Scalar::Util qw<reftype>;
 
 =head1 NAME
 
@@ -14,25 +14,32 @@ Sub::Prototype::Util - Prototype-related utility routines.
 
 =head1 VERSION
 
-Version 0.09
+Version 0.10
 
 =cut
 
-use vars qw/$VERSION/;
+use vars qw<$VERSION>;
 
-$VERSION = '0.09';
+$VERSION = '0.10';
 
 =head1 SYNOPSIS
 
-    use Sub::Prototype::Util qw/flatten wrap recall/;
+    use Sub::Prototype::Util qw<flatten wrap recall>;
 
-    my @a = qw/a b c/;
+    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)
 
 =head1 DESCRIPTION
 
@@ -45,7 +52,7 @@ They all handle C<5.10>'s C<_> prototype.
 
 =cut
 
-my %sigils   = qw/SCALAR $ ARRAY @ HASH % GLOB * CODE &/;
+my %sigils   = qw<SCALAR $ ARRAY @ HASH % GLOB * CODE &>;
 my %reftypes = reverse %sigils;
 
 sub _check_ref {
@@ -72,7 +79,9 @@ sub _clean_msg {
  $msg;
 }
 
-=head2 C<flatten $proto, @args>
+=head2 C<flatten>
+
+    my @flattened = flatten($proto, @args);
 
 Flattens the array C<@args> according to the prototype C<$proto>.
 When C<@args> is what C<@_> is after calling a subroutine with prototype C<$proto>, C<flatten> returns the list of what C<@_> would have been if there were no prototype.
@@ -118,7 +127,10 @@ sub flatten {
  return @args;
 }
 
-=head2 C<wrap $name, %opts>
+=head2 C<wrap>
+
+    my $wrapper = wrap($name, %opts);
+    my $wrapper = wrap({ $name => $proto }, %opts);
 
 Generates a wrapper that calls the function C<$name> with a prototyped argument list.
 That is, the wrapper's arguments should be what C<@_> is when you define a subroutine with the same prototype as C<$name>.
@@ -132,29 +144,37 @@ In this case, C<$name> must be a hash reference that holds exactly one key / val
 
     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 L</wrap>.
+The remaining arguments C<%opts> are treated as key / value pairs that are meant to tune the code generated by L</wrap>.
 Valid keys are :
 
 =over 4
 
-=item C<< ref => $func >>
+=item *
+
+C<< ref => $func >>
 
 Specifies the function used in the generated code to test the reference type of scalars.
 Defaults to C<'ref'>.
 You may also want to use L<Scalar::Util/reftype>.
 
-=item C<< wrong_ref => $code >>
+=item *
+
+C<< 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 C<'undef'>.
 It's a good place to C<croak> or C<die> too.
 
-=item C<< sub => $bool >>
+=item *
+
+C<< sub => $bool >>
 
 Encloses the code into a C<sub { }> block.
 Default is true.
 
-=item C<< compile => $bool >>
+=item *
+
+C<< compile => $bool >>
 
 Makes L</wrap> compile the code generated and return the resulting code reference.
 Be careful that in this case C<ref> must be a fully qualified function name.
@@ -165,7 +185,8 @@ Defaults to true, but turned off when C<sub> is false.
 For example, this allows you to recall into C<CORE::grep> and C<CORE::map> by using the C<\&@> prototype :
 
     my $grep = wrap { 'CORE::grep' => '\&@' };
-    sub mygrep (&@) { $grep->(@_) } # the prototypes are intentionally different
+    # the prototypes are intentionally different
+    sub mygrep (&@) { $grep->(@_) }
 
 =cut
 
@@ -279,7 +300,10 @@ sub wrap {
  return $call;
 }
 
-=head2 C<recall $name, @args>
+=head2 C<recall>
+
+    my @res = recall($name, @args);
+    my @res = recall({ $name => $proto }, @args);
 
 Calls the function C<$name> with the prototyped argument list C<@args>.
 That is, C<@args> should be what C<@_> is when you call a subroutine with C<$name> as prototype.
@@ -293,18 +317,36 @@ If you plan to recall several times, consider using L</wrap> instead.
 
 =cut
 
-sub recall {
- my $name = shift;
+sub recall;
 
- my ($wrap, $err);
- {
-  local $@;
-  $wrap = eval { wrap $name };
-  $err  = $@;
- }
- croak _clean_msg $err if $err;
+BEGIN {
+ my $safe_wrap = sub {
+  my $name = shift;
 
- goto $wrap;
+  my ($wrap, $err);
+  {
+   local $@;
+   $wrap = eval { wrap $name };
+   $err  = $@;
+  }
+
+  $wrap, $err;
+ };
+
+ if ("$]" == 5.008) {
+  # goto tends to crash a lot on perl 5.8.0
+  *recall = sub {
+   my ($wrap, $err) = $safe_wrap->(shift);
+   croak _clean_msg $err if $err;
+   $wrap->(@_)
+  }
+ } else {
+  *recall = sub {
+   my ($wrap, $err) = $safe_wrap->(shift);
+   croak _clean_msg $err if $err;
+   goto $wrap;
+  }
+ }
 }
 
 =head1 EXPORT
@@ -313,13 +355,13 @@ The functions L</flatten>, L</wrap> and L</recall> are only exported on request,
 
 =cut
 
-use base qw/Exporter/;
+use base qw<Exporter>;
 
-use vars qw/@EXPORT @EXPORT_OK %EXPORT_TAGS/;
+use vars qw<@EXPORT @EXPORT_OK %EXPORT_TAGS>;
 
 @EXPORT             = ();
 %EXPORT_TAGS        = (
- 'funcs' =>  [ qw/flatten wrap recall/ ]
+ 'funcs' =>  [ qw<flatten wrap recall> ]
 );
 @EXPORT_OK          = map { @$_ } values %EXPORT_TAGS;
 $EXPORT_TAGS{'all'} = [ @EXPORT_OK ];