Make $^V recommendation the first sentence in $]

[perl5.git] / pod / perlsub.pod

diff --git a/pod/perlsub.pod b/pod/perlsub.pod
index 93f6e5f..cfa4ad4 100644 (file)
--- a/pod/perlsub.pod
+++ b/pod/perlsub.pod
@@ -1053,7 +1053,7 @@ X<prototype> X<subroutine, prototype>
 Perl supports a very limited kind of compile-time argument checking
 using function prototyping.  If you declare
 
-    sub mypush (\@@)
+    sub mypush (+@)
 
 then C<mypush()> takes arguments exactly like C<push()> does.  The
 function declaration must be visible at compile time.  The prototype
@@ -1083,9 +1083,9 @@ corresponding built-in.
     sub mysyswrite ($$$;$)   mysyswrite $buf, 0, length($buf) - $off, $off
     sub myreverse (@)       myreverse $a, $b, $c
     sub myjoin ($@)         myjoin ":", $a, $b, $c
-    sub mypop (\@)          mypop @array
-    sub mysplice (\@$$@)     mysplice @array, 0, 2, @pushme
-    sub mykeys (\%)         mykeys %{$hashref}
+    sub mypop (+)           mypop @array
+    sub mysplice (+$$@)             mysplice @array, 0, 2, @pushme
+    sub mykeys (+)          mykeys %{$hashref}
     sub myopen (*;$)        myopen HANDLE, $name
     sub mypipe (**)         mypipe READHANDLE, WRITEHANDLE
     sub mygrep (&@)         mygrep { /foo/ } $a, $b, $c
@@ -1093,12 +1093,15 @@ corresponding built-in.
     sub mytime ()           mytime
 
 Any backslashed prototype character represents an actual argument
-that absolutely must start with that character.  The value passed
-as part of C<@_> will be a reference to the actual argument given
-in the subroutine call, obtained by applying C<\> to that argument.
+that must start with that character (optionally preceded by C<my>,
+C<our> or C<local>), with the exception of C<$>, which will accept a
+hash or array element even without a dollar sign, such as
+C<< my_function()->[0] >>. The value passed as part of C<@_> will be a
+reference to the actual argument given in the subroutine call,
+obtained by applying C<\> to that argument.
 
-You can also backslash several argument types simultaneously by using
-the C<\[]> notation:
+You can use the C<\[]> backslash group notation to specify more than one
+allowed argument type. For example:
 
     sub myref (\[$@%&*])
 
@@ -1133,6 +1136,20 @@ follows:
        ...
     }
 
+The C<+> prototype is a special alternative to C<$> that will act like
+C<\[@%]> when given a literal array or hash variable, but will otherwise
+force scalar context on the argument.  This is useful for functions which
+should accept either a literal array or an array reference as the argument:
+
+    sub mypush (+@) {
+        my $aref = shift;
+        die "Not an array or arrayref" unless ref $aref eq 'ARRAY';
+        push @$aref, @_;
+    }
+
+When using the C<+> prototype, your function must check that the argument
+is of an acceptable type.
+
 A semicolon (C<;>) separates mandatory arguments from optional arguments.
 It is redundant before C<@> or C<%>, which gobble up everything else.