summaryrefslogtreecommitdiffstats
path: root/upstream/fedora-40/man1/perlsub.1
diff options
context:
space:
mode:
Diffstat (limited to 'upstream/fedora-40/man1/perlsub.1')
-rw-r--r--upstream/fedora-40/man1/perlsub.12352
1 files changed, 2352 insertions, 0 deletions
diff --git a/upstream/fedora-40/man1/perlsub.1 b/upstream/fedora-40/man1/perlsub.1
new file mode 100644
index 00000000..4c78b616
--- /dev/null
+++ b/upstream/fedora-40/man1/perlsub.1
@@ -0,0 +1,2352 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds C`
+. ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+. if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. if !\nF==2 \{\
+. nr % 0
+. nr F 2
+. \}
+. \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "PERLSUB 1"
+.TH PERLSUB 1 2024-01-25 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH NAME
+perlsub \- Perl subroutines
+.IX Xref "subroutine function"
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+To declare subroutines:
+.IX Xref "subroutine, declaration sub"
+.PP
+.Vb 4
+\& sub NAME; # A "forward" declaration.
+\& sub NAME(PROTO); # ditto, but with prototypes
+\& sub NAME : ATTRS; # with attributes
+\& sub NAME(PROTO) : ATTRS; # with attributes and prototypes
+\&
+\& sub NAME BLOCK # A declaration and a definition.
+\& sub NAME(PROTO) BLOCK # ditto, but with prototypes
+\& sub NAME : ATTRS BLOCK # with attributes
+\& sub NAME(PROTO) : ATTRS BLOCK # with prototypes and attributes
+\&
+\& use feature \*(Aqsignatures\*(Aq;
+\& sub NAME(SIG) BLOCK # with signature
+\& sub NAME :ATTRS (SIG) BLOCK # with signature, attributes
+\& sub NAME :prototype(PROTO) (SIG) BLOCK # with signature, prototype
+.Ve
+.PP
+To define an anonymous subroutine at runtime:
+.IX Xref "subroutine, anonymous"
+.PP
+.Vb 4
+\& $subref = sub BLOCK; # no proto
+\& $subref = sub (PROTO) BLOCK; # with proto
+\& $subref = sub : ATTRS BLOCK; # with attributes
+\& $subref = sub (PROTO) : ATTRS BLOCK; # with proto and attributes
+\&
+\& use feature \*(Aqsignatures\*(Aq;
+\& $subref = sub (SIG) BLOCK; # with signature
+\& $subref = sub : ATTRS(SIG) BLOCK; # with signature, attributes
+.Ve
+.PP
+To import subroutines:
+.IX Xref "import"
+.PP
+.Vb 1
+\& use MODULE qw(NAME1 NAME2 NAME3);
+.Ve
+.PP
+To call subroutines:
+.IX Xref "subroutine, call call"
+.PP
+.Vb 4
+\& NAME(LIST); # & is optional with parentheses.
+\& NAME LIST; # Parentheses optional if predeclared/imported.
+\& &NAME(LIST); # Circumvent prototypes.
+\& &NAME; # Makes current @_ visible to called subroutine.
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Like many languages, Perl provides for user-defined subroutines.
+These may be located anywhere in the main program, loaded in from
+other files via the \f(CW\*(C`do\*(C'\fR, \f(CW\*(C`require\*(C'\fR, or \f(CW\*(C`use\*(C'\fR keywords, or
+generated on the fly using \f(CW\*(C`eval\*(C'\fR or anonymous subroutines.
+You can even call a function indirectly using a variable containing
+its name or a CODE reference.
+.PP
+The Perl model for function call and return values is simple: all
+functions are passed as parameters one single flat list of scalars, and
+all functions likewise return to their caller one single flat list of
+scalars. Any arrays or hashes in these call and return lists will
+collapse, losing their identities\-\-but you may always use
+pass-by-reference instead to avoid this. Both call and return lists may
+contain as many or as few scalar elements as you'd like. (Often a
+function without an explicit return statement is called a subroutine, but
+there's really no difference from Perl's perspective.)
+.IX Xref "subroutine, parameter parameter"
+.PP
+In a subroutine that uses signatures (see "Signatures" below),
+arguments are assigned into lexical variables introduced by the
+signature. In the current implementation of Perl they are also
+accessible in the \f(CW@_\fR array in the same way as for non-signature
+subroutines, but accessing them in this manner is now discouraged inside
+such a signature-using subroutine.
+.PP
+In a subroutine that does not use signatures, any arguments passed in
+show up in the array \f(CW@_\fR. Therefore, if you called a function with
+two arguments, those would be stored in \f(CW$_[0]\fR and \f(CW$_[1]\fR. The
+array \f(CW@_\fR is a local array, but its elements are aliases for the
+actual scalar parameters. In particular, if an element \f(CW$_[0]\fR is
+updated, the corresponding argument is updated (or an error occurs if it
+is not updatable). If an argument is an array or hash element which did
+not exist when the function was called, that element is created only
+when (and if) it is modified or a reference to it is taken. (Some
+earlier versions of Perl created the element whether or not the element
+was assigned to.) Assigning to the whole array \f(CW@_\fR removes that
+aliasing, and does not update any arguments.
+.IX Xref "subroutine, argument argument @_"
+.PP
+When not using signatures, Perl does not otherwise provide a means to
+create named formal parameters. In practice all you do is assign to a
+\&\f(CWmy()\fR list of these. Variables that aren't declared to be private are
+global variables. For gory details on creating private variables, see
+"Private Variables via \fBmy()\fR" and "Temporary Values via \fBlocal()\fR".
+To create protected environments for a set of functions in a separate
+package (and probably a separate file), see "Packages" in perlmod.
+.PP
+A \f(CW\*(C`return\*(C'\fR statement may be used to exit a subroutine, optionally
+specifying the returned value, which will be evaluated in the
+appropriate context (list, scalar, or void) depending on the context of
+the subroutine call. If you specify no return value, the subroutine
+returns an empty list in list context, the undefined value in scalar
+context, or nothing in void context. If you return one or more
+aggregates (arrays and hashes), these will be flattened together into
+one large indistinguishable list.
+.PP
+If no \f(CW\*(C`return\*(C'\fR is found and if the last statement is an expression, its
+value is returned. If the last statement is a loop control structure
+like a \f(CW\*(C`foreach\*(C'\fR or a \f(CW\*(C`while\*(C'\fR, the returned value is unspecified. The
+empty sub returns the empty list.
+.IX Xref "subroutine, return value return value return"
+.PP
+Example:
+.PP
+.Vb 8
+\& sub max {
+\& my $max = shift(@_);
+\& foreach $foo (@_) {
+\& $max = $foo if $max < $foo;
+\& }
+\& return $max;
+\& }
+\& $bestday = max($mon,$tue,$wed,$thu,$fri);
+.Ve
+.PP
+Example:
+.PP
+.Vb 2
+\& # get a line, combining continuation lines
+\& # that start with whitespace
+\&
+\& sub get_line {
+\& $thisline = $lookahead; # global variables!
+\& LINE: while (defined($lookahead = <STDIN>)) {
+\& if ($lookahead =~ /^[ \et]/) {
+\& $thisline .= $lookahead;
+\& }
+\& else {
+\& last LINE;
+\& }
+\& }
+\& return $thisline;
+\& }
+\&
+\& $lookahead = <STDIN>; # get first line
+\& while (defined($line = get_line())) {
+\& ...
+\& }
+.Ve
+.PP
+Assigning to a list of private variables to name your arguments:
+.PP
+.Vb 4
+\& sub maybeset {
+\& my($key, $value) = @_;
+\& $Foo{$key} = $value unless $Foo{$key};
+\& }
+.Ve
+.PP
+Because the assignment copies the values, this also has the effect
+of turning call-by-reference into call-by-value. Otherwise a
+function is free to do in-place modifications of \f(CW@_\fR and change
+its caller's values.
+.IX Xref "call-by-reference call-by-value"
+.PP
+.Vb 4
+\& upcase_in($v1, $v2); # this changes $v1 and $v2
+\& sub upcase_in {
+\& for (@_) { tr/a\-z/A\-Z/ }
+\& }
+.Ve
+.PP
+You aren't allowed to modify constants in this way, of course. If an
+argument were actually literal and you tried to change it, you'd take a
+(presumably fatal) exception. For example, this won't work:
+.IX Xref "call-by-reference call-by-value"
+.PP
+.Vb 1
+\& upcase_in("frederick");
+.Ve
+.PP
+It would be much safer if the \f(CWupcase_in()\fR function
+were written to return a copy of its parameters instead
+of changing them in place:
+.PP
+.Vb 7
+\& ($v3, $v4) = upcase($v1, $v2); # this doesn\*(Aqt change $v1 and $v2
+\& sub upcase {
+\& return unless defined wantarray; # void context, do nothing
+\& my @parms = @_;
+\& for (@parms) { tr/a\-z/A\-Z/ }
+\& return wantarray ? @parms : $parms[0];
+\& }
+.Ve
+.PP
+Notice how this (unprototyped) function doesn't care whether it was
+passed real scalars or arrays. Perl sees all arguments as one big,
+long, flat parameter list in \f(CW@_\fR. This is one area where
+Perl's simple argument-passing style shines. The \f(CWupcase()\fR
+function would work perfectly well without changing the \f(CWupcase()\fR
+definition even if we fed it things like this:
+.PP
+.Vb 2
+\& @newlist = upcase(@list1, @list2);
+\& @newlist = upcase( split /:/, $var );
+.Ve
+.PP
+Do not, however, be tempted to do this:
+.PP
+.Vb 1
+\& (@x, @y) = upcase(@list1, @list2);
+.Ve
+.PP
+Like the flattened incoming parameter list, the return list is also
+flattened on return. So all you have managed to do here is stored
+everything in \f(CW@x\fR and made \f(CW@y\fR empty. See
+"Pass by Reference" for alternatives.
+.PP
+A subroutine may be called using an explicit \f(CW\*(C`&\*(C'\fR prefix. The
+\&\f(CW\*(C`&\*(C'\fR is optional in modern Perl, as are parentheses if the
+subroutine has been predeclared. The \f(CW\*(C`&\*(C'\fR is \fInot\fR optional
+when just naming the subroutine, such as when it's used as
+an argument to \fBdefined()\fR or \fBundef()\fR. Nor is it optional when you
+want to do an indirect subroutine call with a subroutine name or
+reference using the \f(CW&$subref()\fR or \f(CW\*(C`&{$subref}()\*(C'\fR constructs,
+although the \f(CW$subref\->()\fR notation solves that problem.
+See perlref for more about all that.
+.IX Xref "&"
+.PP
+Subroutines may be called recursively. If a subroutine is called
+using the \f(CW\*(C`&\*(C'\fR form, the argument list is optional, and if omitted,
+no \f(CW@_\fR array is set up for the subroutine: the \f(CW@_\fR array at the
+time of the call is visible to subroutine instead. This is an
+efficiency mechanism that new users may wish to avoid.
+.IX Xref "recursion"
+.PP
+.Vb 2
+\& &foo(1,2,3); # pass three arguments
+\& foo(1,2,3); # the same
+\&
+\& foo(); # pass a null list
+\& &foo(); # the same
+\&
+\& &foo; # foo() get current args, like foo(@_) !!
+\& use strict \*(Aqsubs\*(Aq;
+\& foo; # like foo() iff sub foo predeclared, else
+\& # a compile\-time error
+\& no strict \*(Aqsubs\*(Aq;
+\& foo; # like foo() iff sub foo predeclared, else
+\& # a literal string "foo"
+.Ve
+.PP
+Not only does the \f(CW\*(C`&\*(C'\fR form make the argument list optional, it also
+disables any prototype checking on arguments you do provide. This
+is partly for historical reasons, and partly for having a convenient way
+to cheat if you know what you're doing. See "Prototypes" below.
+.IX Xref "&"
+.PP
+Since Perl 5.16.0, the \f(CW\*(C`_\|_SUB_\|_\*(C'\fR token is available under \f(CWuse feature
+\&\*(Aqcurrent_sub\*(Aq\fR and \f(CW\*(C`use v5.16\*(C'\fR. It will evaluate to a reference to the
+currently-running sub, which allows for recursive calls without knowing
+your subroutine's name.
+.PP
+.Vb 6
+\& use v5.16;
+\& my $factorial = sub {
+\& my ($x) = @_;
+\& return 1 if $x == 1;
+\& return($x * _\|_SUB_\|_\->( $x \- 1 ) );
+\& };
+.Ve
+.PP
+The behavior of \f(CW\*(C`_\|_SUB_\|_\*(C'\fR within a regex code block (such as \f(CW\*(C`/(?{...})/\*(C'\fR)
+is subject to change.
+.PP
+Subroutines whose names are in all upper case are reserved to the Perl
+core, as are modules whose names are in all lower case. A subroutine in
+all capitals is a loosely-held convention meaning it will be called
+indirectly by the run-time system itself, usually due to a triggered event.
+Subroutines whose name start with a left parenthesis are also reserved the
+same way. The following is a list of some subroutines that currently do
+special, pre-defined things.
+.IP "documented later in this document" 4
+.IX Item "documented later in this document"
+\&\f(CW\*(C`AUTOLOAD\*(C'\fR
+.IP "documented in perlmod" 4
+.IX Item "documented in perlmod"
+\&\f(CW\*(C`CLONE\*(C'\fR, \f(CW\*(C`CLONE_SKIP\*(C'\fR
+.IP "documented in perlobj" 4
+.IX Item "documented in perlobj"
+\&\f(CW\*(C`DESTROY\*(C'\fR, \f(CW\*(C`DOES\*(C'\fR
+.IP "documented in perltie" 4
+.IX Item "documented in perltie"
+\&\f(CW\*(C`BINMODE\*(C'\fR, \f(CW\*(C`CLEAR\*(C'\fR, \f(CW\*(C`CLOSE\*(C'\fR, \f(CW\*(C`DELETE\*(C'\fR, \f(CW\*(C`DESTROY\*(C'\fR, \f(CW\*(C`EOF\*(C'\fR, \f(CW\*(C`EXISTS\*(C'\fR,
+\&\f(CW\*(C`EXTEND\*(C'\fR, \f(CW\*(C`FETCH\*(C'\fR, \f(CW\*(C`FETCHSIZE\*(C'\fR, \f(CW\*(C`FILENO\*(C'\fR, \f(CW\*(C`FIRSTKEY\*(C'\fR, \f(CW\*(C`GETC\*(C'\fR,
+\&\f(CW\*(C`NEXTKEY\*(C'\fR, \f(CW\*(C`OPEN\*(C'\fR, \f(CW\*(C`POP\*(C'\fR, \f(CW\*(C`PRINT\*(C'\fR, \f(CW\*(C`PRINTF\*(C'\fR, \f(CW\*(C`PUSH\*(C'\fR, \f(CW\*(C`READ\*(C'\fR,
+\&\f(CW\*(C`READLINE\*(C'\fR, \f(CW\*(C`SCALAR\*(C'\fR, \f(CW\*(C`SEEK\*(C'\fR, \f(CW\*(C`SHIFT\*(C'\fR, \f(CW\*(C`SPLICE\*(C'\fR, \f(CW\*(C`STORE\*(C'\fR,
+\&\f(CW\*(C`STORESIZE\*(C'\fR, \f(CW\*(C`TELL\*(C'\fR, \f(CW\*(C`TIEARRAY\*(C'\fR, \f(CW\*(C`TIEHANDLE\*(C'\fR, \f(CW\*(C`TIEHASH\*(C'\fR,
+\&\f(CW\*(C`TIESCALAR\*(C'\fR, \f(CW\*(C`UNSHIFT\*(C'\fR, \f(CW\*(C`UNTIE\*(C'\fR, \f(CW\*(C`WRITE\*(C'\fR
+.IP "documented in PerlIO::via" 4
+.IX Item "documented in PerlIO::via"
+\&\f(CW\*(C`BINMODE\*(C'\fR, \f(CW\*(C`CLEARERR\*(C'\fR, \f(CW\*(C`CLOSE\*(C'\fR, \f(CW\*(C`EOF\*(C'\fR, \f(CW\*(C`ERROR\*(C'\fR, \f(CW\*(C`FDOPEN\*(C'\fR, \f(CW\*(C`FILENO\*(C'\fR,
+\&\f(CW\*(C`FILL\*(C'\fR, \f(CW\*(C`FLUSH\*(C'\fR, \f(CW\*(C`OPEN\*(C'\fR, \f(CW\*(C`POPPED\*(C'\fR, \f(CW\*(C`PUSHED\*(C'\fR, \f(CW\*(C`READ\*(C'\fR, \f(CW\*(C`SEEK\*(C'\fR,
+\&\f(CW\*(C`SETLINEBUF\*(C'\fR, \f(CW\*(C`SYSOPEN\*(C'\fR, \f(CW\*(C`TELL\*(C'\fR, \f(CW\*(C`UNREAD\*(C'\fR, \f(CW\*(C`UTF8\*(C'\fR, \f(CW\*(C`WRITE\*(C'\fR
+.IP "documented in perlfunc" 4
+.IX Item "documented in perlfunc"
+\&\f(CW\*(C`import\*(C'\fR, \f(CW\*(C`unimport\*(C'\fR,
+\&\f(CW\*(C`INC\*(C'\fR
+.IP "documented in UNIVERSAL" 4
+.IX Item "documented in UNIVERSAL"
+\&\f(CW\*(C`VERSION\*(C'\fR
+.IP "documented in perldebguts" 4
+.IX Item "documented in perldebguts"
+\&\f(CW\*(C`DB::DB\*(C'\fR, \f(CW\*(C`DB::sub\*(C'\fR, \f(CW\*(C`DB::lsub\*(C'\fR, \f(CW\*(C`DB::goto\*(C'\fR, \f(CW\*(C`DB::postponed\*(C'\fR
+.IP "undocumented, used internally by the overload feature" 4
+.IX Item "undocumented, used internally by the overload feature"
+any starting with \f(CW\*(C`(\*(C'\fR
+.PP
+The \f(CW\*(C`BEGIN\*(C'\fR, \f(CW\*(C`UNITCHECK\*(C'\fR, \f(CW\*(C`CHECK\*(C'\fR, \f(CW\*(C`INIT\*(C'\fR and \f(CW\*(C`END\*(C'\fR subroutines
+are not so much subroutines as named special code blocks, of which you
+can have more than one in a package, and which you can \fBnot\fR call
+explicitly. See "BEGIN, UNITCHECK, CHECK, INIT and END" in perlmod
+.SS Signatures
+.IX Subsection "Signatures"
+
+.IX Xref "formal parameter parameter, formal"
+.PP
+Perl has a facility to allow a subroutine's formal parameters to be
+declared by special syntax, separate from the procedural code of the
+subroutine body. The formal parameter list is known as a \fIsignature\fR.
+.PP
+This facility must be enabled before it can be used. It is enabled
+automatically by a \f(CW\*(C`use v5.36\*(C'\fR (or higher) declaration, or more
+directly by \f(CW\*(C`use feature \*(Aqsignatures\*(Aq\*(C'\fR, in the current scope.
+.PP
+The signature is part of a subroutine's body. Normally the body of a
+subroutine is simply a braced block of code, but when using a signature,
+the signature is a parenthesised list that goes immediately before the
+block, after any name or attributes.
+.PP
+For example,
+.PP
+.Vb 1
+\& sub foo :lvalue ($x, $y = 1, @z) { .... }
+.Ve
+.PP
+The signature declares lexical variables that are
+in scope for the block. When the subroutine is called, the signature
+takes control first. It populates the signature variables from the
+list of arguments that were passed. If the argument list doesn't meet
+the requirements of the signature, then it will throw an exception.
+When the signature processing is complete, control passes to the block.
+.PP
+Positional parameters are handled by simply naming scalar variables in
+the signature. For example,
+.PP
+.Vb 3
+\& sub foo ($left, $right) {
+\& return $left + $right;
+\& }
+.Ve
+.PP
+takes two positional parameters, which must be filled at runtime by
+two arguments. By default the parameters are mandatory, and it is
+not permitted to pass more arguments than expected. So the above is
+equivalent to
+.PP
+.Vb 7
+\& sub foo {
+\& die "Too many arguments for subroutine" unless @_ <= 2;
+\& die "Too few arguments for subroutine" unless @_ >= 2;
+\& my $left = $_[0];
+\& my $right = $_[1];
+\& return $left + $right;
+\& }
+.Ve
+.PP
+An argument can be ignored by omitting the main part of the name from
+a parameter declaration, leaving just a bare \f(CW\*(C`$\*(C'\fR sigil. For example,
+.PP
+.Vb 3
+\& sub foo ($first, $, $third) {
+\& return "first=$first, third=$third";
+\& }
+.Ve
+.PP
+Although the ignored argument doesn't go into a variable, it is still
+mandatory for the caller to pass it.
+.PP
+A positional parameter is made optional by giving a default value,
+separated from the parameter name by \f(CW\*(C`=\*(C'\fR:
+.PP
+.Vb 3
+\& sub foo ($left, $right = 0) {
+\& return $left + $right;
+\& }
+.Ve
+.PP
+The above subroutine may be called with either one or two arguments.
+The default value expression is evaluated when the subroutine is called,
+so it may provide different default values for different calls. It is
+only evaluated if the argument was actually omitted from the call.
+For example,
+.PP
+.Vb 4
+\& my $auto_id = 0;
+\& sub foo ($thing, $id = $auto_id++) {
+\& print "$thing has ID $id";
+\& }
+.Ve
+.PP
+automatically assigns distinct sequential IDs to things for which no
+ID was supplied by the caller. A default value expression may also
+refer to parameters earlier in the signature, making the default for
+one parameter vary according to the earlier parameters. For example,
+.PP
+.Vb 3
+\& sub foo ($first_name, $surname, $nickname = $first_name) {
+\& print "$first_name $surname is known as \e"$nickname\e"";
+\& }
+.Ve
+.PP
+A default value expression can also be written using the \f(CW\*(C`//=\*(C'\fR operator,
+where it will be evaluated and used if the caller omitted a value or the
+value provided was \f(CW\*(C`undef\*(C'\fR.
+.PP
+.Vb 3
+\& sub foo ($name //= "world") {
+\& print "Hello, $name";
+\& }
+\&
+\& foo(undef); # will print "Hello, world"
+.Ve
+.PP
+Similarly, the \f(CW\*(C`||=\*(C'\fR operator can be used to provide a default
+expression to be used whenever the caller provided a false value (and
+remember that a missing or \f(CW\*(C`undef\*(C'\fR value are also false).
+.PP
+.Vb 3
+\& sub foo ($x ||= 10) {
+\& return 5 + $x;
+\& }
+.Ve
+.PP
+An optional parameter can be nameless just like a mandatory parameter.
+For example,
+.PP
+.Vb 3
+\& sub foo ($thing, $ = 1) {
+\& print $thing;
+\& }
+.Ve
+.PP
+The parameter's default value will still be evaluated if the corresponding
+argument isn't supplied, even though the value won't be stored anywhere.
+This is in case evaluating it has important side effects. However, it
+will be evaluated in void context, so if it doesn't have side effects
+and is not trivial it will generate a warning if the "void" warning
+category is enabled. If a nameless optional parameter's default value
+is not important, it may be omitted just as the parameter's name was:
+.PP
+.Vb 3
+\& sub foo ($thing, $=) {
+\& print $thing;
+\& }
+.Ve
+.PP
+Optional positional parameters must come after all mandatory positional
+parameters. (If there are no mandatory positional parameters then an
+optional positional parameters can be the first thing in the signature.)
+If there are multiple optional positional parameters and not enough
+arguments are supplied to fill them all, they will be filled from left
+to right.
+.PP
+After positional parameters, additional arguments may be captured in a
+slurpy parameter. The simplest form of this is just an array variable:
+.PP
+.Vb 3
+\& sub foo ($filter, @inputs) {
+\& print $filter\->($_) foreach @inputs;
+\& }
+.Ve
+.PP
+With a slurpy parameter in the signature, there is no upper limit on how
+many arguments may be passed. A slurpy array parameter may be nameless
+just like a positional parameter, in which case its only effect is to
+turn off the argument limit that would otherwise apply:
+.PP
+.Vb 3
+\& sub foo ($thing, @) {
+\& print $thing;
+\& }
+.Ve
+.PP
+A slurpy parameter may instead be a hash, in which case the arguments
+available to it are interpreted as alternating keys and values.
+There must be as many keys as values: if there is an odd argument then
+an exception will be thrown. Keys will be stringified, and if there are
+duplicates then the later instance takes precedence over the earlier,
+as with standard hash construction.
+.PP
+.Vb 3
+\& sub foo ($filter, %inputs) {
+\& print $filter\->($_, $inputs{$_}) foreach sort keys %inputs;
+\& }
+.Ve
+.PP
+A slurpy hash parameter may be nameless just like other kinds of
+parameter. It still insists that the number of arguments available to
+it be even, even though they're not being put into a variable.
+.PP
+.Vb 3
+\& sub foo ($thing, %) {
+\& print $thing;
+\& }
+.Ve
+.PP
+A slurpy parameter, either array or hash, must be the last thing in the
+signature. It may follow mandatory and optional positional parameters;
+it may also be the only thing in the signature. Slurpy parameters cannot
+have default values: if no arguments are supplied for them then you get
+an empty array or empty hash.
+.PP
+A signature may be entirely empty, in which case all it does is check
+that the caller passed no arguments:
+.PP
+.Vb 3
+\& sub foo () {
+\& return 123;
+\& }
+.Ve
+.PP
+Prior to Perl 5.36 these were considered experimental, and emitted a
+warning in the \f(CW\*(C`experimental::signatures\*(C'\fR category. From Perl 5.36
+onwards this no longer happens, though the warning category still exists
+for back-compatibility with code that attempts to disable it with a
+statement such as:
+.PP
+.Vb 1
+\& no warnings \*(Aqexperimental::signatures\*(Aq;
+.Ve
+.PP
+In the current Perl implementation, when using a signature the arguments
+are still also available in the special array variable \f(CW@_\fR. However,
+accessing them via this array is now discouraged, and should not be
+relied upon in newly-written code as this ability may change in a future
+version. Code that attempts to access the \f(CW@_\fR array will produce
+warnings in the \f(CW\*(C`experimental::args_array_with_signatures\*(C'\fR category when
+compiled:
+.PP
+.Vb 4
+\& sub f ($x) {
+\& # This line emits the warning seen below
+\& print "Arguments are @_";
+\& }
+.Ve
+.PP
+
+.PP
+.Vb 2
+\& Use of @_ in join or string with signatured subroutine is
+\& experimental at ...
+.Ve
+.PP
+There is a difference between the two ways of accessing the arguments:
+\&\f(CW@_\fR \fIaliases\fR the arguments, but the signature variables get
+\&\fIcopies\fR of the arguments. So writing to a signature variable only
+changes that variable, and has no effect on the caller's variables, but
+writing to an element of \f(CW@_\fR modifies whatever the caller used to
+supply that argument.
+.PP
+There is a potential syntactic ambiguity between signatures and prototypes
+(see "Prototypes"), because both start with an opening parenthesis and
+both can appear in some of the same places, such as just after the name
+in a subroutine declaration. For historical reasons, when signatures
+are not enabled, any opening parenthesis in such a context will trigger
+very forgiving prototype parsing. Most signatures will be interpreted
+as prototypes in those circumstances, but won't be valid prototypes.
+(A valid prototype cannot contain any alphabetic character.) This will
+lead to somewhat confusing error messages.
+.PP
+To avoid ambiguity, when signatures are enabled the special syntax
+for prototypes is disabled. There is no attempt to guess whether a
+parenthesised group was intended to be a prototype or a signature.
+To give a subroutine a prototype under these circumstances, use a
+prototype attribute. For example,
+.PP
+.Vb 1
+\& sub foo :prototype($) { $_[0] }
+.Ve
+.PP
+It is entirely possible for a subroutine to have both a prototype and
+a signature. They do different jobs: the prototype affects compilation
+of calls to the subroutine, and the signature puts argument values into
+lexical variables at runtime. You can therefore write
+.PP
+.Vb 3
+\& sub foo :prototype($$) ($left, $right) {
+\& return $left + $right;
+\& }
+.Ve
+.PP
+The prototype attribute, and any other attributes, must come before
+the signature. The signature always immediately precedes the block of
+the subroutine's body.
+.SS "Private Variables via \fBmy()\fP"
+.IX Xref "my variable, lexical lexical lexical variable scope, lexical lexical scope attributes, my"
+.IX Subsection "Private Variables via my()"
+Synopsis:
+.PP
+.Vb 5
+\& my $foo; # declare $foo lexically local
+\& my (@wid, %get); # declare list of variables local
+\& my $foo = "flurp"; # declare $foo lexical, and init it
+\& my @oof = @bar; # declare @oof lexical, and init it
+\& my $x : Foo = $y; # similar, with an attribute applied
+.Ve
+.PP
+\&\fBWARNING\fR: The use of attribute lists on \f(CW\*(C`my\*(C'\fR declarations is still
+evolving. The current semantics and interface are subject to change.
+See attributes and Attribute::Handlers.
+.PP
+The \f(CW\*(C`my\*(C'\fR operator declares the listed variables to be lexically
+confined to the enclosing block, conditional
+(\f(CW\*(C`if\*(C'\fR/\f(CW\*(C`unless\*(C'\fR/\f(CW\*(C`elsif\*(C'\fR/\f(CW\*(C`else\*(C'\fR), loop
+(\f(CW\*(C`for\*(C'\fR/\f(CW\*(C`foreach\*(C'\fR/\f(CW\*(C`while\*(C'\fR/\f(CW\*(C`until\*(C'\fR/\f(CW\*(C`continue\*(C'\fR), subroutine, \f(CW\*(C`eval\*(C'\fR,
+or \f(CW\*(C`do\*(C'\fR/\f(CW\*(C`require\*(C'\fR/\f(CW\*(C`use\*(C'\fR'd file. If more than one value is listed, the
+list must be placed in parentheses. All listed elements must be
+legal lvalues. Only alphanumeric identifiers may be lexically
+scoped\-\-magical built-ins like \f(CW$/\fR must currently be \f(CW\*(C`local\*(C'\fRized
+with \f(CW\*(C`local\*(C'\fR instead.
+.PP
+Unlike dynamic variables created by the \f(CW\*(C`local\*(C'\fR operator, lexical
+variables declared with \f(CW\*(C`my\*(C'\fR are totally hidden from the outside
+world, including any called subroutines. This is true if it's the
+same subroutine called from itself or elsewhere\-\-every call gets
+its own copy.
+.IX Xref "local"
+.PP
+This doesn't mean that a \f(CW\*(C`my\*(C'\fR variable declared in a statically
+enclosing lexical scope would be invisible. Only dynamic scopes
+are cut off. For example, the \f(CWbumpx()\fR function below has access
+to the lexical \f(CW$x\fR variable because both the \f(CW\*(C`my\*(C'\fR and the \f(CW\*(C`sub\*(C'\fR
+occurred at the same scope, presumably file scope.
+.PP
+.Vb 2
+\& my $x = 10;
+\& sub bumpx { $x++ }
+.Ve
+.PP
+An \f(CWeval()\fR, however, can see lexical variables of the scope it is
+being evaluated in, so long as the names aren't hidden by declarations within
+the \f(CWeval()\fR itself. See perlref.
+.IX Xref "eval, scope of"
+.PP
+The parameter list to \fBmy()\fR may be assigned to if desired, which allows you
+to initialize your variables. (If no initializer is given for a
+particular variable, it is created with the undefined value.) Commonly
+this is used to name input parameters to a subroutine. Examples:
+.PP
+.Vb 4
+\& $arg = "fred"; # "global" variable
+\& $n = cube_root(27);
+\& print "$arg thinks the root is $n\en";
+\& # outputs: fred thinks the root is 3
+\&
+\& sub cube_root {
+\& my $arg = shift; # name doesn\*(Aqt matter
+\& $arg **= 1/3;
+\& return $arg;
+\& }
+.Ve
+.PP
+The \f(CW\*(C`my\*(C'\fR is simply a modifier on something you might assign to. So when
+you do assign to variables in its argument list, \f(CW\*(C`my\*(C'\fR doesn't
+change whether those variables are viewed as a scalar or an array. So
+.PP
+.Vb 2
+\& my ($foo) = <STDIN>; # WRONG?
+\& my @FOO = <STDIN>;
+.Ve
+.PP
+both supply a list context to the right-hand side, while
+.PP
+.Vb 1
+\& my $foo = <STDIN>;
+.Ve
+.PP
+supplies a scalar context. But the following declares only one variable:
+.PP
+.Vb 1
+\& my $foo, $bar = 1; # WRONG
+.Ve
+.PP
+That has the same effect as
+.PP
+.Vb 2
+\& my $foo;
+\& $bar = 1;
+.Ve
+.PP
+The declared variable is not introduced (is not visible) until after
+the current statement. Thus,
+.PP
+.Vb 1
+\& my $x = $x;
+.Ve
+.PP
+can be used to initialize a new \f(CW$x\fR with the value of the old \f(CW$x\fR, and
+the expression
+.PP
+.Vb 1
+\& my $x = 123 and $x == 123
+.Ve
+.PP
+is false unless the old \f(CW$x\fR happened to have the value \f(CW123\fR.
+.PP
+Lexical scopes of control structures are not bounded precisely by the
+braces that delimit their controlled blocks; control expressions are
+part of that scope, too. Thus in the loop
+.PP
+.Vb 5
+\& while (my $line = <>) {
+\& $line = lc $line;
+\& } continue {
+\& print $line;
+\& }
+.Ve
+.PP
+the scope of \f(CW$line\fR extends from its declaration throughout the rest of
+the loop construct (including the \f(CW\*(C`continue\*(C'\fR clause), but not beyond
+it. Similarly, in the conditional
+.PP
+.Vb 8
+\& if ((my $answer = <STDIN>) =~ /^yes$/i) {
+\& user_agrees();
+\& } elsif ($answer =~ /^no$/i) {
+\& user_disagrees();
+\& } else {
+\& chomp $answer;
+\& die "\*(Aq$answer\*(Aq is neither \*(Aqyes\*(Aq nor \*(Aqno\*(Aq";
+\& }
+.Ve
+.PP
+the scope of \f(CW$answer\fR extends from its declaration through the rest
+of that conditional, including any \f(CW\*(C`elsif\*(C'\fR and \f(CW\*(C`else\*(C'\fR clauses,
+but not beyond it. See "Simple Statements" in perlsyn for information
+on the scope of variables in statements with modifiers.
+.PP
+The \f(CW\*(C`foreach\*(C'\fR loop defaults to scoping its index variable dynamically
+in the manner of \f(CW\*(C`local\*(C'\fR. However, if the index variable is
+prefixed with the keyword \f(CW\*(C`my\*(C'\fR, or if there is already a lexical
+by that name in scope, then a new lexical is created instead. Thus
+in the loop
+.IX Xref "foreach for"
+.PP
+.Vb 3
+\& for my $i (1, 2, 3) {
+\& some_function();
+\& }
+.Ve
+.PP
+the scope of \f(CW$i\fR extends to the end of the loop, but not beyond it,
+rendering the value of \f(CW$i\fR inaccessible within \f(CWsome_function()\fR.
+.IX Xref "foreach for"
+.PP
+Some users may wish to encourage the use of lexically scoped variables.
+As an aid to catching implicit uses to package variables,
+which are always global, if you say
+.PP
+.Vb 1
+\& use strict \*(Aqvars\*(Aq;
+.Ve
+.PP
+then any variable mentioned from there to the end of the enclosing
+block must either refer to a lexical variable, be predeclared via
+\&\f(CW\*(C`our\*(C'\fR or \f(CW\*(C`use vars\*(C'\fR, or else must be fully qualified with the package name.
+A compilation error results otherwise. An inner block may countermand
+this with \f(CW\*(C`no strict \*(Aqvars\*(Aq\*(C'\fR.
+.PP
+A \f(CW\*(C`my\*(C'\fR has both a compile-time and a run-time effect. At compile
+time, the compiler takes notice of it. The principal usefulness
+of this is to quiet \f(CW\*(C`use strict \*(Aqvars\*(Aq\*(C'\fR, but it is also essential
+for generation of closures as detailed in perlref. Actual
+initialization is delayed until run time, though, so it gets executed
+at the appropriate time, such as each time through a loop, for
+example.
+.PP
+Variables declared with \f(CW\*(C`my\*(C'\fR are not part of any package and are therefore
+never fully qualified with the package name. In particular, you're not
+allowed to try to make a package variable (or other global) lexical:
+.PP
+.Vb 1
+\& my $pack::var; # ERROR! Illegal syntax
+.Ve
+.PP
+In fact, a dynamic variable (also known as package or global variables)
+are still accessible using the fully qualified \f(CW\*(C`::\*(C'\fR notation even while a
+lexical of the same name is also visible:
+.PP
+.Vb 4
+\& package main;
+\& local $x = 10;
+\& my $x = 20;
+\& print "$x and $::x\en";
+.Ve
+.PP
+That will print out \f(CW20\fR and \f(CW10\fR.
+.PP
+You may declare \f(CW\*(C`my\*(C'\fR variables at the outermost scope of a file
+to hide any such identifiers from the world outside that file. This
+is similar in spirit to C's static variables when they are used at
+the file level. To do this with a subroutine requires the use of
+a closure (an anonymous function that accesses enclosing lexicals).
+If you want to create a private subroutine that cannot be called
+from outside that block, it can declare a lexical variable containing
+an anonymous sub reference:
+.PP
+.Vb 3
+\& my $secret_version = \*(Aq1.001\-beta\*(Aq;
+\& my $secret_sub = sub { print $secret_version };
+\& &$secret_sub();
+.Ve
+.PP
+As long as the reference is never returned by any function within the
+module, no outside module can see the subroutine, because its name is not in
+any package's symbol table. Remember that it's not \fIREALLY\fR called
+\&\f(CW$some_pack::secret_version\fR or anything; it's just \f(CW$secret_version\fR,
+unqualified and unqualifiable.
+.PP
+This does not work with object methods, however; all object methods
+have to be in the symbol table of some package to be found. See
+"Function Templates" in perlref for something of a work-around to
+this.
+.SS "Persistent Private Variables"
+.IX Xref "state state variable static variable, persistent variable, static closure"
+.IX Subsection "Persistent Private Variables"
+There are two ways to build persistent private variables in Perl 5.10.
+First, you can simply use the \f(CW\*(C`state\*(C'\fR feature. Or, you can use closures,
+if you want to stay compatible with releases older than 5.10.
+.PP
+\fIPersistent variables via \fR\f(BIstate()\fR
+.IX Subsection "Persistent variables via state()"
+.PP
+Beginning with Perl 5.10.0, you can declare variables with the \f(CW\*(C`state\*(C'\fR
+keyword in place of \f(CW\*(C`my\*(C'\fR. For that to work, though, you must have
+enabled that feature beforehand, either by using the \f(CW\*(C`feature\*(C'\fR pragma, or
+by using \f(CW\*(C`\-E\*(C'\fR on one-liners (see feature). Beginning with Perl 5.16,
+the \f(CW\*(C`CORE::state\*(C'\fR form does not require the
+\&\f(CW\*(C`feature\*(C'\fR pragma.
+.PP
+The \f(CW\*(C`state\*(C'\fR keyword creates a lexical variable (following the same scoping
+rules as \f(CW\*(C`my\*(C'\fR) that persists from one subroutine call to the next. If a
+state variable resides inside an anonymous subroutine, then each copy of
+the subroutine has its own copy of the state variable. However, the value
+of the state variable will still persist between calls to the same copy of
+the anonymous subroutine. (Don't forget that \f(CW\*(C`sub { ... }\*(C'\fR creates a new
+subroutine each time it is executed.)
+.PP
+For example, the following code maintains a private counter, incremented
+each time the \fBgimme_another()\fR function is called:
+.PP
+.Vb 2
+\& use feature \*(Aqstate\*(Aq;
+\& sub gimme_another { state $x; return ++$x }
+.Ve
+.PP
+And this example uses anonymous subroutines to create separate counters:
+.PP
+.Vb 4
+\& use feature \*(Aqstate\*(Aq;
+\& sub create_counter {
+\& return sub { state $x; return ++$x }
+\& }
+.Ve
+.PP
+Also, since \f(CW$x\fR is lexical, it can't be reached or modified by any Perl
+code outside.
+.PP
+When combined with variable declaration, simple assignment to \f(CW\*(C`state\*(C'\fR
+variables (as in \f(CW\*(C`state $x = 42\*(C'\fR) is executed only the first time. When such
+statements are evaluated subsequent times, the assignment is ignored. The
+behavior of assignment to \f(CW\*(C`state\*(C'\fR declarations where the left hand side
+of the assignment involves any parentheses is currently undefined.
+.PP
+\fIPersistent variables with closures\fR
+.IX Subsection "Persistent variables with closures"
+.PP
+Just because a lexical variable is lexically (also called statically)
+scoped to its enclosing block, \f(CW\*(C`eval\*(C'\fR, or \f(CW\*(C`do\*(C'\fR FILE, this doesn't mean that
+within a function it works like a C static. It normally works more
+like a C auto, but with implicit garbage collection.
+.PP
+Unlike local variables in C or C++, Perl's lexical variables don't
+necessarily get recycled just because their scope has exited.
+If something more permanent is still aware of the lexical, it will
+stick around. So long as something else references a lexical, that
+lexical won't be freed\-\-which is as it should be. You wouldn't want
+memory being free until you were done using it, or kept around once you
+were done. Automatic garbage collection takes care of this for you.
+.PP
+This means that you can pass back or save away references to lexical
+variables, whereas to return a pointer to a C auto is a grave error.
+It also gives us a way to simulate C's function statics. Here's a
+mechanism for giving a function private variables with both lexical
+scoping and a static lifetime. If you do want to create something like
+C's static variables, just enclose the whole function in an extra block,
+and put the static variable outside the function but in the block.
+.PP
+.Vb 8
+\& {
+\& my $secret_val = 0;
+\& sub gimme_another {
+\& return ++$secret_val;
+\& }
+\& }
+\& # $secret_val now becomes unreachable by the outside
+\& # world, but retains its value between calls to gimme_another
+.Ve
+.PP
+If this function is being sourced in from a separate file
+via \f(CW\*(C`require\*(C'\fR or \f(CW\*(C`use\*(C'\fR, then this is probably just fine. If it's
+all in the main program, you'll need to arrange for the \f(CW\*(C`my\*(C'\fR
+to be executed early, either by putting the whole block above
+your main program, or more likely, placing merely a \f(CW\*(C`BEGIN\*(C'\fR
+code block around it to make sure it gets executed before your program
+starts to run:
+.PP
+.Vb 6
+\& BEGIN {
+\& my $secret_val = 0;
+\& sub gimme_another {
+\& return ++$secret_val;
+\& }
+\& }
+.Ve
+.PP
+See "BEGIN, UNITCHECK, CHECK, INIT and END" in perlmod about the
+special triggered code blocks, \f(CW\*(C`BEGIN\*(C'\fR, \f(CW\*(C`UNITCHECK\*(C'\fR, \f(CW\*(C`CHECK\*(C'\fR,
+\&\f(CW\*(C`INIT\*(C'\fR and \f(CW\*(C`END\*(C'\fR.
+.PP
+If declared at the outermost scope (the file scope), then lexicals
+work somewhat like C's file statics. They are available to all
+functions in that same file declared below them, but are inaccessible
+from outside that file. This strategy is sometimes used in modules
+to create private variables that the whole module can see.
+.SS "Temporary Values via \fBlocal()\fP"
+.IX Xref "local scope, dynamic dynamic scope variable, local variable, temporary"
+.IX Subsection "Temporary Values via local()"
+\&\fBWARNING\fR: In general, you should be using \f(CW\*(C`my\*(C'\fR instead of \f(CW\*(C`local\*(C'\fR, because
+it's faster and safer. Exceptions to this include the global punctuation
+variables, global filehandles and formats, and direct manipulation of the
+Perl symbol table itself. \f(CW\*(C`local\*(C'\fR is mostly used when the current value
+of a variable must be visible to called subroutines.
+.PP
+Synopsis:
+.PP
+.Vb 1
+\& # localization of values
+\&
+\& local $foo; # make $foo dynamically local
+\& local (@wid, %get); # make list of variables local
+\& local $foo = "flurp"; # make $foo dynamic, and init it
+\& local @oof = @bar; # make @oof dynamic, and init it
+\&
+\& local $hash{key} = "val"; # sets a local value for this hash entry
+\& delete local $hash{key}; # delete this entry for the current block
+\& local ($cond ? $v1 : $v2); # several types of lvalues support
+\& # localization
+\&
+\& # localization of symbols
+\&
+\& local *FH; # localize $FH, @FH, %FH, &FH ...
+\& local *merlyn = *randal; # now $merlyn is really $randal, plus
+\& # @merlyn is really @randal, etc
+\& local *merlyn = \*(Aqrandal\*(Aq; # SAME THING: promote \*(Aqrandal\*(Aq to *randal
+\& local *merlyn = \e$randal; # just alias $merlyn, not @merlyn etc
+.Ve
+.PP
+A \f(CW\*(C`local\*(C'\fR modifies its listed variables to be "local" to the
+enclosing block, \f(CW\*(C`eval\*(C'\fR, or \f(CW\*(C`do FILE\*(C'\fR\-\-and to \fIany subroutine
+called from within that block\fR. A \f(CW\*(C`local\*(C'\fR just gives temporary
+values to global (meaning package) variables. It does \fInot\fR create
+a local variable. This is known as dynamic scoping. Lexical scoping
+is done with \f(CW\*(C`my\*(C'\fR, which works more like C's auto declarations.
+.PP
+Some types of lvalues can be localized as well: hash and array elements
+and slices, conditionals (provided that their result is always
+localizable), and symbolic references. As for simple variables, this
+creates new, dynamically scoped values.
+.PP
+If more than one variable or expression is given to \f(CW\*(C`local\*(C'\fR, they must be
+placed in parentheses. This operator works
+by saving the current values of those variables in its argument list on a
+hidden stack and restoring them upon exiting the block, subroutine, or
+eval. This means that called subroutines can also reference the local
+variable, but not the global one. The argument list may be assigned to if
+desired, which allows you to initialize your local variables. (If no
+initializer is given for a particular variable, it is created with an
+undefined value.)
+.PP
+Because \f(CW\*(C`local\*(C'\fR is a run-time operator, it gets executed each time
+through a loop. Consequently, it's more efficient to localize your
+variables outside the loop.
+.PP
+\fIGrammatical note on \fR\f(BIlocal()\fR
+.IX Xref "local, context"
+.IX Subsection "Grammatical note on local()"
+.PP
+A \f(CW\*(C`local\*(C'\fR is simply a modifier on an lvalue expression. When you assign to
+a \f(CW\*(C`local\*(C'\fRized variable, the \f(CW\*(C`local\*(C'\fR doesn't change whether its list is
+viewed as a scalar or an array. So
+.PP
+.Vb 2
+\& local($foo) = <STDIN>;
+\& local @FOO = <STDIN>;
+.Ve
+.PP
+both supply a list context to the right-hand side, while
+.PP
+.Vb 1
+\& local $foo = <STDIN>;
+.Ve
+.PP
+supplies a scalar context.
+.PP
+\fILocalization of special variables\fR
+.IX Xref "local, special variable"
+.IX Subsection "Localization of special variables"
+.PP
+If you localize a special variable, you'll be giving a new value to it,
+but its magic won't go away. That means that all side-effects related
+to this magic still work with the localized value.
+.PP
+This feature allows code like this to work :
+.PP
+.Vb 2
+\& # Read the whole contents of FILE in $slurp
+\& { local $/ = undef; $slurp = <FILE>; }
+.Ve
+.PP
+Note, however, that this restricts localization of some values ; for
+example, the following statement dies, as of Perl 5.10.0, with an error
+\&\fIModification of a read-only value attempted\fR, because the \f(CW$1\fR variable is
+magical and read-only :
+.PP
+.Vb 1
+\& local $1 = 2;
+.Ve
+.PP
+One exception is the default scalar variable: starting with Perl 5.14
+\&\f(CWlocal($_)\fR will always strip all magic from \f(CW$_\fR, to make it possible
+to safely reuse \f(CW$_\fR in a subroutine.
+.PP
+\&\fBWARNING\fR: Localization of tied arrays and hashes does not currently
+work as described.
+This will be fixed in a future release of Perl; in the meantime, avoid
+code that relies on any particular behavior of localising tied arrays
+or hashes (localising individual elements is still okay).
+See "Localising Tied Arrays and Hashes Is Broken" in perl58delta for more
+details.
+.IX Xref "local, tie"
+.PP
+\fILocalization of globs\fR
+.IX Xref "local, glob glob"
+.IX Subsection "Localization of globs"
+.PP
+The construct
+.PP
+.Vb 1
+\& local *name;
+.Ve
+.PP
+creates a whole new symbol table entry for the glob \f(CW\*(C`name\*(C'\fR in the
+current package. That means that all variables in its glob slot ($name,
+\&\f(CW@name\fR, \f(CW%name\fR, &name, and the \f(CW\*(C`name\*(C'\fR filehandle) are dynamically reset.
+.PP
+This implies, among other things, that any magic eventually carried by
+those variables is locally lost. In other words, saying \f(CW\*(C`local */\*(C'\fR
+will not have any effect on the internal value of the input record
+separator.
+.PP
+\fILocalization of elements of composite types\fR
+.IX Xref "local, composite type element local, array element local, hash element"
+.IX Subsection "Localization of elements of composite types"
+.PP
+It's also worth taking a moment to explain what happens when you
+\&\f(CW\*(C`local\*(C'\fRize a member of a composite type (i.e. an array or hash element).
+In this case, the element is \f(CW\*(C`local\*(C'\fRized \fIby name\fR. This means that
+when the scope of the \f(CWlocal()\fR ends, the saved value will be
+restored to the hash element whose key was named in the \f(CWlocal()\fR, or
+the array element whose index was named in the \f(CWlocal()\fR. If that
+element was deleted while the \f(CWlocal()\fR was in effect (e.g. by a
+\&\f(CWdelete()\fR from a hash or a \f(CWshift()\fR of an array), it will spring
+back into existence, possibly extending an array and filling in the
+skipped elements with \f(CW\*(C`undef\*(C'\fR. For instance, if you say
+.PP
+.Vb 10
+\& %hash = ( \*(AqThis\*(Aq => \*(Aqis\*(Aq, \*(Aqa\*(Aq => \*(Aqtest\*(Aq );
+\& @ary = ( 0..5 );
+\& {
+\& local($ary[5]) = 6;
+\& local($hash{\*(Aqa\*(Aq}) = \*(Aqdrill\*(Aq;
+\& while (my $e = pop(@ary)) {
+\& print "$e . . .\en";
+\& last unless $e > 3;
+\& }
+\& if (@ary) {
+\& $hash{\*(Aqonly a\*(Aq} = \*(Aqtest\*(Aq;
+\& delete $hash{\*(Aqa\*(Aq};
+\& }
+\& }
+\& print join(\*(Aq \*(Aq, map { "$_ $hash{$_}" } sort keys %hash),".\en";
+\& print "The array has ",scalar(@ary)," elements: ",
+\& join(\*(Aq, \*(Aq, map { defined $_ ? $_ : \*(Aqundef\*(Aq } @ary),"\en";
+.Ve
+.PP
+Perl will print
+.PP
+.Vb 5
+\& 6 . . .
+\& 4 . . .
+\& 3 . . .
+\& This is a test only a test.
+\& The array has 6 elements: 0, 1, 2, undef, undef, 5
+.Ve
+.PP
+The behavior of \fBlocal()\fR on non-existent members of composite
+types is subject to change in future. The behavior of \fBlocal()\fR
+on array elements specified using negative indexes is particularly
+surprising, and is very likely to change.
+.PP
+\fILocalized deletion of elements of composite types\fR
+.IX Xref "delete local, composite type element local, array element local, hash element"
+.IX Subsection "Localized deletion of elements of composite types"
+.PP
+You can use the \f(CW\*(C`delete local $array[$idx]\*(C'\fR and \f(CW\*(C`delete local $hash{key}\*(C'\fR
+constructs to delete a composite type entry for the current block and restore
+it when it ends. They return the array/hash value before the localization,
+which means that they are respectively equivalent to
+.PP
+.Vb 6
+\& do {
+\& my $val = $array[$idx];
+\& local $array[$idx];
+\& delete $array[$idx];
+\& $val
+\& }
+.Ve
+.PP
+and
+.PP
+.Vb 6
+\& do {
+\& my $val = $hash{key};
+\& local $hash{key};
+\& delete $hash{key};
+\& $val
+\& }
+.Ve
+.PP
+except that for those the \f(CW\*(C`local\*(C'\fR is
+scoped to the \f(CW\*(C`do\*(C'\fR block. Slices are
+also accepted.
+.PP
+.Vb 4
+\& my %hash = (
+\& a => [ 7, 8, 9 ],
+\& b => 1,
+\& )
+\&
+\& {
+\& my $x = delete local $hash{a};
+\& # $x is [ 7, 8, 9 ]
+\& # %hash is (b => 1)
+\&
+\& {
+\& my @nums = delete local @$x[0, 2]
+\& # @nums is (7, 9)
+\& # $x is [ undef, 8 ]
+\&
+\& $x[0] = 999; # will be erased when the scope ends
+\& }
+\& # $x is back to [ 7, 8, 9 ]
+\&
+\& }
+\& # %hash is back to its original state
+.Ve
+.PP
+This construct is supported since Perl v5.12.
+.SS "Lvalue subroutines"
+.IX Xref "lvalue subroutine, lvalue"
+.IX Subsection "Lvalue subroutines"
+It is possible to return a modifiable value from a subroutine.
+To do this, you have to declare the subroutine to return an lvalue.
+.PP
+.Vb 7
+\& my $val;
+\& sub canmod : lvalue {
+\& $val; # or: return $val;
+\& }
+\& sub nomod {
+\& $val;
+\& }
+\&
+\& canmod() = 5; # assigns to $val
+\& nomod() = 5; # ERROR
+.Ve
+.PP
+The scalar/list context for the subroutine and for the right-hand
+side of assignment is determined as if the subroutine call is replaced
+by a scalar. For example, consider:
+.PP
+.Vb 1
+\& data(2,3) = get_data(3,4);
+.Ve
+.PP
+Both subroutines here are called in a scalar context, while in:
+.PP
+.Vb 1
+\& (data(2,3)) = get_data(3,4);
+.Ve
+.PP
+and in:
+.PP
+.Vb 1
+\& (data(2),data(3)) = get_data(3,4);
+.Ve
+.PP
+all the subroutines are called in a list context.
+.PP
+Lvalue subroutines are convenient, but you have to keep in mind that,
+when used with objects, they may violate encapsulation. A normal
+mutator can check the supplied argument before setting the attribute
+it is protecting, an lvalue subroutine cannot. If you require any
+special processing when storing and retrieving the values, consider
+using the CPAN module Sentinel or something similar.
+.SS "Lexical Subroutines"
+.IX Xref "my sub state sub our sub subroutine, lexical"
+.IX Subsection "Lexical Subroutines"
+Beginning with Perl 5.18, you can declare a private subroutine with \f(CW\*(C`my\*(C'\fR
+or \f(CW\*(C`state\*(C'\fR. As with state variables, the \f(CW\*(C`state\*(C'\fR keyword is only
+available under \f(CW\*(C`use feature \*(Aqstate\*(Aq\*(C'\fR or \f(CW\*(C`use v5.10\*(C'\fR or higher.
+.PP
+Prior to Perl 5.26, lexical subroutines were deemed experimental and were
+available only under the \f(CW\*(C`use feature \*(Aqlexical_subs\*(Aq\*(C'\fR pragma. They also
+produced a warning unless the "experimental::lexical_subs" warnings
+category was disabled.
+.PP
+These subroutines are only visible within the block in which they are
+declared, and only after that declaration:
+.PP
+.Vb 4
+\& # Include these two lines if your code is intended to run under Perl
+\& # versions earlier than 5.26.
+\& no warnings "experimental::lexical_subs";
+\& use feature \*(Aqlexical_subs\*(Aq;
+\&
+\& foo(); # calls the package/global subroutine
+\& state sub foo {
+\& foo(); # also calls the package subroutine
+\& }
+\& foo(); # calls "state" sub
+\& my $ref = \e&foo; # take a reference to "state" sub
+\&
+\& my sub bar { ... }
+\& bar(); # calls "my" sub
+.Ve
+.PP
+You can't (directly) write a recursive lexical subroutine:
+.PP
+.Vb 4
+\& # WRONG
+\& my sub baz {
+\& baz();
+\& }
+.Ve
+.PP
+This example fails because \f(CWbaz()\fR refers to the package/global subroutine
+\&\f(CW\*(C`baz\*(C'\fR, not the lexical subroutine currently being defined.
+.PP
+The solution is to use \f(CW\*(C`_\|_SUB_\|_\*(C'\fR:
+.PP
+.Vb 3
+\& my sub baz {
+\& _\|_SUB_\|_\->(); # calls itself
+\& }
+.Ve
+.PP
+It is possible to predeclare a lexical subroutine. The \f(CW\*(C`sub foo {...}\*(C'\fR
+subroutine definition syntax respects any previous \f(CW\*(C`my sub;\*(C'\fR or \f(CW\*(C`state sub;\*(C'\fR
+declaration. Using this to define recursive subroutines is a bad idea,
+however:
+.PP
+.Vb 4
+\& my sub baz; # predeclaration
+\& sub baz { # define the "my" sub
+\& baz(); # WRONG: calls itself, but leaks memory
+\& }
+.Ve
+.PP
+Just like \f(CW\*(C`my $f; $f = sub { $f\->() }\*(C'\fR, this example leaks memory. The
+name \f(CW\*(C`baz\*(C'\fR is a reference to the subroutine, and the subroutine uses the name
+\&\f(CW\*(C`baz\*(C'\fR; they keep each other alive (see "Circular References" in perlref).
+.PP
+\fR\f(CI\*(C`state sub\*(C'\fR\fI vs \fR\f(CI\*(C`my sub\*(C'\fR\fI\fR
+.IX Subsection "state sub vs my sub"
+.PP
+What is the difference between "state" subs and "my" subs? Each time that
+execution enters a block when "my" subs are declared, a new copy of each
+sub is created. "State" subroutines persist from one execution of the
+containing block to the next.
+.PP
+So, in general, "state" subroutines are faster. But "my" subs are
+necessary if you want to create closures:
+.PP
+.Vb 7
+\& sub whatever {
+\& my $x = shift;
+\& my sub inner {
+\& ... do something with $x ...
+\& }
+\& inner();
+\& }
+.Ve
+.PP
+In this example, a new \f(CW$x\fR is created when \f(CW\*(C`whatever\*(C'\fR is called, and
+also a new \f(CW\*(C`inner\*(C'\fR, which can see the new \f(CW$x\fR. A "state" sub will only
+see the \f(CW$x\fR from the first call to \f(CW\*(C`whatever\*(C'\fR.
+.PP
+\fR\f(CI\*(C`our\*(C'\fR\fI subroutines\fR
+.IX Subsection "our subroutines"
+.PP
+Like \f(CW\*(C`our $variable\*(C'\fR, \f(CW\*(C`our sub\*(C'\fR creates a lexical alias to the package
+subroutine of the same name.
+.PP
+The two main uses for this are to switch back to using the package sub
+inside an inner scope:
+.PP
+.Vb 1
+\& sub foo { ... }
+\&
+\& sub bar {
+\& my sub foo { ... }
+\& {
+\& # need to use the outer foo here
+\& our sub foo;
+\& foo();
+\& }
+\& }
+.Ve
+.PP
+and to make a subroutine visible to other packages in the same scope:
+.PP
+.Vb 1
+\& package MySneakyModule;
+\&
+\& our sub do_something { ... }
+\&
+\& sub do_something_with_caller {
+\& package DB;
+\& () = caller 1; # sets @DB::args
+\& do_something(@args); # uses MySneakyModule::do_something
+\& }
+.Ve
+.SS "Passing Symbol Table Entries (typeglobs)"
+.IX Xref "typeglob *"
+.IX Subsection "Passing Symbol Table Entries (typeglobs)"
+\&\fBWARNING\fR: The mechanism described in this section was originally
+the only way to simulate pass-by-reference in older versions of
+Perl. While it still works fine in modern versions, the new reference
+mechanism is generally easier to work with. See below.
+.PP
+Sometimes you don't want to pass the value of an array to a subroutine
+but rather the name of it, so that the subroutine can modify the global
+copy of it rather than working with a local copy. In Perl you can
+refer to all objects of a particular name by prefixing the name
+with a star: \f(CW*foo\fR. This is often known as a "typeglob", because the
+star on the front can be thought of as a wildcard match for all the
+funny prefix characters on variables and subroutines and such.
+.PP
+When evaluated, the typeglob produces a scalar value that represents
+all the objects of that name, including any filehandle, format, or
+subroutine. When assigned to, it causes the name mentioned to refer to
+whatever \f(CW\*(C`*\*(C'\fR value was assigned to it. Example:
+.PP
+.Vb 8
+\& sub doubleary {
+\& local(*someary) = @_;
+\& foreach $elem (@someary) {
+\& $elem *= 2;
+\& }
+\& }
+\& doubleary(*foo);
+\& doubleary(*bar);
+.Ve
+.PP
+Scalars are already passed by reference, so you can modify
+scalar arguments without using this mechanism by referring explicitly
+to \f(CW$_[0]\fR etc. You can modify all the elements of an array by passing
+all the elements as scalars, but you have to use the \f(CW\*(C`*\*(C'\fR mechanism (or
+the equivalent reference mechanism) to \f(CW\*(C`push\*(C'\fR, \f(CW\*(C`pop\*(C'\fR, or change the size of
+an array. It will certainly be faster to pass the typeglob (or reference).
+.PP
+Even if you don't want to modify an array, this mechanism is useful for
+passing multiple arrays in a single LIST, because normally the LIST
+mechanism will merge all the array values so that you can't extract out
+the individual arrays. For more on typeglobs, see
+"Typeglobs and Filehandles" in perldata.
+.SS "When to Still Use \fBlocal()\fP"
+.IX Xref "local variable, local"
+.IX Subsection "When to Still Use local()"
+Despite the existence of \f(CW\*(C`my\*(C'\fR, there are still three places where the
+\&\f(CW\*(C`local\*(C'\fR operator still shines. In fact, in these three places, you
+\&\fImust\fR use \f(CW\*(C`local\*(C'\fR instead of \f(CW\*(C`my\*(C'\fR.
+.IP 1. 4
+You need to give a global variable a temporary value, especially \f(CW$_\fR.
+.Sp
+The global variables, like \f(CW@ARGV\fR or the punctuation variables, must be
+\&\f(CW\*(C`local\*(C'\fRized with \f(CWlocal()\fR. This block reads in \fI/etc/motd\fR, and splits
+it up into chunks separated by lines of equal signs, which are placed
+in \f(CW@Fields\fR.
+.Sp
+.Vb 6
+\& {
+\& local @ARGV = ("/etc/motd");
+\& local $/ = undef;
+\& local $_ = <>;
+\& @Fields = split /^\es*=+\es*$/;
+\& }
+.Ve
+.Sp
+It particular, it's important to \f(CW\*(C`local\*(C'\fRize \f(CW$_\fR in any routine that assigns
+to it. Look out for implicit assignments in \f(CW\*(C`while\*(C'\fR conditionals.
+.IP 2. 4
+You need to create a local file or directory handle or a local function.
+.Sp
+A function that needs a filehandle of its own must use
+\&\f(CWlocal()\fR on a complete typeglob. This can be used to create new symbol
+table entries:
+.Sp
+.Vb 6
+\& sub ioqueue {
+\& local (*READER, *WRITER); # not my!
+\& pipe (READER, WRITER) or die "pipe: $!";
+\& return (*READER, *WRITER);
+\& }
+\& ($head, $tail) = ioqueue();
+.Ve
+.Sp
+See the Symbol module for a way to create anonymous symbol table
+entries.
+.Sp
+Because assignment of a reference to a typeglob creates an alias, this
+can be used to create what is effectively a local function, or at least,
+a local alias.
+.Sp
+.Vb 6
+\& {
+\& local *grow = \e&shrink; # only until this block exits
+\& grow(); # really calls shrink()
+\& move(); # if move() grow()s, it shrink()s too
+\& }
+\& grow(); # get the real grow() again
+.Ve
+.Sp
+See "Function Templates" in perlref for more about manipulating
+functions by name in this way.
+.IP 3. 4
+You want to temporarily change just one element of an array or hash.
+.Sp
+You can \f(CW\*(C`local\*(C'\fRize just one element of an aggregate. Usually this
+is done on dynamics:
+.Sp
+.Vb 5
+\& {
+\& local $SIG{INT} = \*(AqIGNORE\*(Aq;
+\& funct(); # uninterruptible
+\& }
+\& # interruptibility automatically restored here
+.Ve
+.Sp
+But it also works on lexically declared aggregates.
+.SS "Pass by Reference"
+.IX Xref "pass by reference pass-by-reference reference"
+.IX Subsection "Pass by Reference"
+If you want to pass more than one array or hash into a function\-\-or
+return them from it\-\-and have them maintain their integrity, then
+you're going to have to use an explicit pass-by-reference. Before you
+do that, you need to understand references as detailed in perlref.
+This section may not make much sense to you otherwise.
+.PP
+Here are a few simple examples. First, let's pass in several arrays
+to a function and have it \f(CW\*(C`pop\*(C'\fR all of then, returning a new list
+of all their former last elements:
+.PP
+.Vb 1
+\& @tailings = popmany ( \e@w, \e@x, \e@y, \e@z );
+\&
+\& sub popmany {
+\& my $aref;
+\& my @retlist;
+\& foreach $aref ( @_ ) {
+\& push @retlist, pop @$aref;
+\& }
+\& return @retlist;
+\& }
+.Ve
+.PP
+Here's how you might write a function that returns a
+list of keys occurring in all the hashes passed to it:
+.PP
+.Vb 10
+\& @common = inter( \e%foo, \e%bar, \e%joe );
+\& sub inter {
+\& my ($k, $href, %seen); # locals
+\& foreach $href (@_) {
+\& while ( $k = each %$href ) {
+\& $seen{$k}++;
+\& }
+\& }
+\& return grep { $seen{$_} == @_ } keys %seen;
+\& }
+.Ve
+.PP
+So far, we're using just the normal list return mechanism.
+What happens if you want to pass or return a hash? Well,
+if you're using only one of them, or you don't mind them
+concatenating, then the normal calling convention is ok, although
+a little expensive.
+.PP
+Where people get into trouble is here:
+.PP
+.Vb 3
+\& (@w, @x) = func(@y, @z);
+\&or
+\& (%w, %x) = func(%y, %z);
+.Ve
+.PP
+That syntax simply won't work. It sets just \f(CW@w\fR or \f(CW%w\fR and
+clears the \f(CW@x\fR or \f(CW%x\fR. Plus the function didn't get passed
+into two separate arrays or hashes: it got one long list in \f(CW@_\fR,
+as always.
+.PP
+If you can arrange for everyone to deal with this through references, it's
+cleaner code, although not so nice to look at. Here's a function that
+takes two array references as arguments, returning the two array elements
+in order of how many elements they have in them:
+.PP
+.Vb 10
+\& ($wref, $xref) = func(\e@y, \e@z);
+\& print "@$wref has more than @$xref\en";
+\& sub func {
+\& my ($yref, $zref) = @_;
+\& if (@$yref > @$zref) {
+\& return ($yref, $zref);
+\& } else {
+\& return ($zref, $yref);
+\& }
+\& }
+.Ve
+.PP
+It turns out that you can actually do this also:
+.PP
+.Vb 10
+\& (*w, *x) = func(\e@y, \e@z);
+\& print "@w has more than @x\en";
+\& sub func {
+\& local (*y, *z) = @_;
+\& if (@y > @z) {
+\& return (\e@y, \e@z);
+\& } else {
+\& return (\e@z, \e@y);
+\& }
+\& }
+.Ve
+.PP
+Here we're using the typeglobs to do symbol table aliasing. It's
+a tad subtle, though, and also won't work if you're using \f(CW\*(C`my\*(C'\fR
+variables, because only globals (even in disguise as \f(CW\*(C`local\*(C'\fRs)
+are in the symbol table.
+.PP
+If you're passing around filehandles, you could usually just use the bare
+typeglob, like \f(CW*STDOUT\fR, but typeglobs references work, too.
+For example:
+.PP
+.Vb 5
+\& splutter(\e*STDOUT);
+\& sub splutter {
+\& my $fh = shift;
+\& print $fh "her um well a hmmm\en";
+\& }
+\&
+\& $rec = get_rec(\e*STDIN);
+\& sub get_rec {
+\& my $fh = shift;
+\& return scalar <$fh>;
+\& }
+.Ve
+.PP
+If you're planning on generating new filehandles, you could do this.
+Notice to pass back just the bare *FH, not its reference.
+.PP
+.Vb 5
+\& sub openit {
+\& my $path = shift;
+\& local *FH;
+\& return open (FH, $path) ? *FH : undef;
+\& }
+.Ve
+.SS Prototypes
+.IX Xref "prototype subroutine, prototype"
+.IX Subsection "Prototypes"
+Perl supports a very limited kind of compile-time argument checking
+using function prototyping. This can be declared in either the PROTO
+section or with a prototype attribute.
+If you declare either of
+.PP
+.Vb 2
+\& sub mypush (\e@@)
+\& sub mypush :prototype(\e@@)
+.Ve
+.PP
+then \f(CWmypush()\fR takes arguments exactly like \f(CWpush()\fR does.
+.PP
+If subroutine signatures are enabled (see "Signatures"), then
+the shorter PROTO syntax is unavailable, because it would clash with
+signatures. In that case, a prototype can only be declared in the form
+of an attribute.
+.PP
+The
+function declaration must be visible at compile time. The prototype
+affects only interpretation of new-style calls to the function,
+where new-style is defined as not using the \f(CW\*(C`&\*(C'\fR character. In
+other words, if you call it like a built-in function, then it behaves
+like a built-in function. If you call it like an old-fashioned
+subroutine, then it behaves like an old-fashioned subroutine. It
+naturally falls out from this rule that prototypes have no influence
+on subroutine references like \f(CW\*(C`\e&foo\*(C'\fR or on indirect subroutine
+calls like \f(CW\*(C`&{$subref}\*(C'\fR or \f(CW$subref\->()\fR.
+.PP
+Method calls are not influenced by prototypes either, because the
+function to be called is indeterminate at compile time, since
+the exact code called depends on inheritance.
+.PP
+Because the intent of this feature is primarily to let you define
+subroutines that work like built-in functions, here are prototypes
+for some other functions that parse almost exactly like the
+corresponding built-in.
+.PP
+.Vb 1
+\& Declared as Called as
+\&
+\& sub mylink ($$) mylink $old, $new
+\& sub myvec ($$$) myvec $var, $offset, 1
+\& sub myindex ($$;$) myindex &getstring, "substr"
+\& sub mysyswrite ($$$;$) mysyswrite $buf, 0, length($buf) \- $off, $off
+\& sub myreverse (@) myreverse $x, $y, $z
+\& sub myjoin ($@) myjoin ":", $x, $y, $z
+\& sub mypop (\e@) mypop @array
+\& sub mysplice (\e@$$@) mysplice @array, 0, 2, @pushme
+\& sub mykeys (\e[%@]) mykeys $hashref\->%*
+\& sub myopen (*;$) myopen HANDLE, $name
+\& sub mypipe (**) mypipe READHANDLE, WRITEHANDLE
+\& sub mygrep (&@) mygrep { /foo/ } $x, $y, $z
+\& sub myrand (;$) myrand 42
+\& sub mytime () mytime
+.Ve
+.PP
+Any backslashed prototype character represents an actual argument
+that must start with that character (optionally preceded by \f(CW\*(C`my\*(C'\fR,
+\&\f(CW\*(C`our\*(C'\fR or \f(CW\*(C`local\*(C'\fR), with the exception of \f(CW\*(C`$\*(C'\fR, which will
+accept any scalar lvalue expression, such as \f(CW\*(C`$foo = 7\*(C'\fR or
+\&\f(CW\*(C`my_function()\->[0]\*(C'\fR. The value passed as part of \f(CW@_\fR will be a
+reference to the actual argument given in the subroutine call,
+obtained by applying \f(CW\*(C`\e\*(C'\fR to that argument.
+.PP
+You can use the \f(CW\*(C`\e[]\*(C'\fR backslash group notation to specify more than one
+allowed argument type. For example:
+.PP
+.Vb 1
+\& sub myref (\e[$@%&*])
+.Ve
+.PP
+will allow calling \fBmyref()\fR as
+.PP
+.Vb 5
+\& myref $var
+\& myref @array
+\& myref %hash
+\& myref &sub
+\& myref *glob
+.Ve
+.PP
+and the first argument of \fBmyref()\fR will be a reference to
+a scalar, an array, a hash, a code, or a glob.
+.PP
+Unbackslashed prototype characters have special meanings. Any
+unbackslashed \f(CW\*(C`@\*(C'\fR or \f(CW\*(C`%\*(C'\fR eats all remaining arguments, and forces
+list context. An argument represented by \f(CW\*(C`$\*(C'\fR forces scalar context. An
+\&\f(CW\*(C`&\*(C'\fR requires an anonymous subroutine, which, if passed as the first
+argument, does not require the \f(CW\*(C`sub\*(C'\fR keyword or a subsequent comma.
+.PP
+A \f(CW\*(C`*\*(C'\fR allows the subroutine to accept a bareword, constant, scalar expression,
+typeglob, or a reference to a typeglob in that slot. The value will be
+available to the subroutine either as a simple scalar, or (in the latter
+two cases) as a reference to the typeglob. If you wish to always convert
+such arguments to a typeglob reference, use \fBSymbol::qualify_to_ref()\fR as
+follows:
+.PP
+.Vb 1
+\& use Symbol \*(Aqqualify_to_ref\*(Aq;
+\&
+\& sub foo (*) {
+\& my $fh = qualify_to_ref(shift, caller);
+\& ...
+\& }
+.Ve
+.PP
+The \f(CW\*(C`+\*(C'\fR prototype is a special alternative to \f(CW\*(C`$\*(C'\fR that will act like
+\&\f(CW\*(C`\e[@%]\*(C'\fR 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:
+.PP
+.Vb 5
+\& sub mypush (+@) {
+\& my $aref = shift;
+\& die "Not an array or arrayref" unless ref $aref eq \*(AqARRAY\*(Aq;
+\& push @$aref, @_;
+\& }
+.Ve
+.PP
+When using the \f(CW\*(C`+\*(C'\fR prototype, your function must check that the argument
+is of an acceptable type.
+.PP
+A semicolon (\f(CW\*(C`;\*(C'\fR) separates mandatory arguments from optional arguments.
+It is redundant before \f(CW\*(C`@\*(C'\fR or \f(CW\*(C`%\*(C'\fR, which gobble up everything else.
+.PP
+As the last character of a prototype, or just before a semicolon, a \f(CW\*(C`@\*(C'\fR
+or a \f(CW\*(C`%\*(C'\fR, you can use \f(CW\*(C`_\*(C'\fR in place of \f(CW\*(C`$\*(C'\fR: if this argument is not
+provided, \f(CW$_\fR will be used instead.
+.PP
+Note how the last three examples in the table above are treated
+specially by the parser. \f(CWmygrep()\fR is parsed as a true list
+operator, \f(CWmyrand()\fR is parsed as a true unary operator with unary
+precedence the same as \f(CWrand()\fR, and \f(CWmytime()\fR is truly without
+arguments, just like \f(CWtime()\fR. That is, if you say
+.PP
+.Vb 1
+\& mytime +2;
+.Ve
+.PP
+you'll get \f(CW\*(C`mytime() + 2\*(C'\fR, not \f(CWmytime(2)\fR, which is how it would be parsed
+without a prototype. If you want to force a unary function to have the
+same precedence as a list operator, add \f(CW\*(C`;\*(C'\fR to the end of the prototype:
+.PP
+.Vb 2
+\& sub mygetprotobynumber($;);
+\& mygetprotobynumber $x > $y; # parsed as mygetprotobynumber($x > $y)
+.Ve
+.PP
+The interesting thing about \f(CW\*(C`&\*(C'\fR is that you can generate new syntax with it,
+provided it's in the initial position:
+.IX Xref "&"
+.PP
+.Vb 9
+\& sub try (&@) {
+\& my($try,$catch) = @_;
+\& eval { &$try };
+\& if ($@) {
+\& local $_ = $@;
+\& &$catch;
+\& }
+\& }
+\& sub catch (&) { $_[0] }
+\&
+\& try {
+\& die "phooey";
+\& } catch {
+\& /phooey/ and print "unphooey\en";
+\& };
+.Ve
+.PP
+That prints \f(CW"unphooey"\fR. (Yes, there are still unresolved
+issues having to do with visibility of \f(CW@_\fR. I'm ignoring that
+question for the moment. (But note that if we make \f(CW@_\fR lexically
+scoped, those anonymous subroutines can act like closures... (Gee,
+is this sounding a little Lispish? (Never mind.))))
+.PP
+And here's a reimplementation of the Perl \f(CW\*(C`grep\*(C'\fR operator:
+.IX Xref "grep"
+.PP
+.Vb 8
+\& sub mygrep (&@) {
+\& my $code = shift;
+\& my @result;
+\& foreach $_ (@_) {
+\& push(@result, $_) if &$code;
+\& }
+\& @result;
+\& }
+.Ve
+.PP
+Some folks would prefer full alphanumeric prototypes. Alphanumerics have
+been intentionally left out of prototypes for the express purpose of
+someday in the future adding named, formal parameters. The current
+mechanism's main goal is to let module writers provide better diagnostics
+for module users. Larry feels the notation quite understandable to Perl
+programmers, and that it will not intrude greatly upon the meat of the
+module, nor make it harder to read. The line noise is visually
+encapsulated into a small pill that's easy to swallow.
+.PP
+If you try to use an alphanumeric sequence in a prototype you will
+generate an optional warning \- "Illegal character in prototype...".
+Unfortunately earlier versions of Perl allowed the prototype to be
+used as long as its prefix was a valid prototype. The warning may be
+upgraded to a fatal error in a future version of Perl once the
+majority of offending code is fixed.
+.PP
+It's probably best to prototype new functions, not retrofit prototyping
+into older ones. That's because you must be especially careful about
+silent impositions of differing list versus scalar contexts. For example,
+if you decide that a function should take just one parameter, like this:
+.PP
+.Vb 4
+\& sub func ($) {
+\& my $n = shift;
+\& print "you gave me $n\en";
+\& }
+.Ve
+.PP
+and someone has been calling it with an array or expression
+returning a list:
+.PP
+.Vb 2
+\& func(@foo);
+\& func( $text =~ /\ew+/g );
+.Ve
+.PP
+Then you've just supplied an automatic \f(CW\*(C`scalar\*(C'\fR in front of their
+argument, which can be more than a bit surprising. The old \f(CW@foo\fR
+which used to hold one thing doesn't get passed in. Instead,
+\&\f(CWfunc()\fR now gets passed in a \f(CW1\fR; that is, the number of elements
+in \f(CW@foo\fR. And the \f(CW\*(C`m//g\*(C'\fR gets called in scalar context so instead of a
+list of words it returns a boolean result and advances \f(CWpos($text)\fR. Ouch!
+.PP
+If a sub has both a PROTO and a BLOCK, the prototype is not applied
+until after the BLOCK is completely defined. This means that a recursive
+function with a prototype has to be predeclared for the prototype to take
+effect, like so:
+.PP
+.Vb 4
+\& sub foo($$);
+\& sub foo($$) {
+\& foo 1, 2;
+\& }
+.Ve
+.PP
+This is all very powerful, of course, and should be used only in moderation
+to make the world a better place.
+.SS "Constant Functions"
+.IX Xref "constant"
+.IX Subsection "Constant Functions"
+Functions with a prototype of \f(CW\*(C`()\*(C'\fR are potential candidates for
+inlining. If the result after optimization and constant folding
+is either a constant or a lexically-scoped scalar which has no other
+references, then it will be used in place of function calls made
+without \f(CW\*(C`&\*(C'\fR. Calls made using \f(CW\*(C`&\*(C'\fR are never inlined. (See
+constant for an easy way to declare most constants.)
+.PP
+The following functions would all be inlined:
+.PP
+.Vb 5
+\& sub pi () { 3.14159 } # Not exact, but close.
+\& sub PI () { 4 * atan2 1, 1 } # As good as it gets,
+\& # and it\*(Aqs inlined, too!
+\& sub ST_DEV () { 0 }
+\& sub ST_INO () { 1 }
+\&
+\& sub FLAG_FOO () { 1 << 8 }
+\& sub FLAG_BAR () { 1 << 9 }
+\& sub FLAG_MASK () { FLAG_FOO | FLAG_BAR }
+\&
+\& sub OPT_BAZ () { not (0x1B58 & FLAG_MASK) }
+\&
+\& sub N () { int(OPT_BAZ) / 3 }
+\&
+\& sub FOO_SET () { 1 if FLAG_MASK & FLAG_FOO }
+\& sub FOO_SET2 () { if (FLAG_MASK & FLAG_FOO) { 1 } }
+.Ve
+.PP
+(Be aware that the last example was not always inlined in Perl 5.20 and
+earlier, which did not behave consistently with subroutines containing
+inner scopes.) You can countermand inlining by using an explicit
+\&\f(CW\*(C`return\*(C'\fR:
+.PP
+.Vb 9
+\& sub baz_val () {
+\& if (OPT_BAZ) {
+\& return 23;
+\& }
+\& else {
+\& return 42;
+\& }
+\& }
+\& sub bonk_val () { return 12345 }
+.Ve
+.PP
+As alluded to earlier you can also declare inlined subs dynamically at
+BEGIN time if their body consists of a lexically-scoped scalar which
+has no other references. Only the first example here will be inlined:
+.PP
+.Vb 5
+\& BEGIN {
+\& my $var = 1;
+\& no strict \*(Aqrefs\*(Aq;
+\& *INLINED = sub () { $var };
+\& }
+\&
+\& BEGIN {
+\& my $var = 1;
+\& my $ref = \e$var;
+\& no strict \*(Aqrefs\*(Aq;
+\& *NOT_INLINED = sub () { $var };
+\& }
+.Ve
+.PP
+A not so obvious caveat with this (see [RT #79908]) is what happens if the
+variable is potentially modifiable. For example:
+.PP
+.Vb 6
+\& BEGIN {
+\& my $x = 10;
+\& *FOO = sub () { $x };
+\& $x++;
+\& }
+\& print FOO(); # printed 10 prior to 5.32.0
+.Ve
+.PP
+From Perl 5.22 onwards this gave a deprecation warning, and from Perl 5.32
+onwards it became a run-time error. Previously the variable was
+immediately inlined, and stopped behaving like a normal lexical variable;
+so it printed \f(CW10\fR, not \f(CW11\fR.
+.PP
+If you still want such a subroutine to be inlined (with no warning), make
+sure the variable is not used in a context where it could be modified
+aside from where it is declared.
+.PP
+.Vb 11
+\& # Fine, no warning
+\& BEGIN {
+\& my $x = 54321;
+\& *INLINED = sub () { $x };
+\& }
+\& # Error
+\& BEGIN {
+\& my $x;
+\& $x = 54321;
+\& *ALSO_INLINED = sub () { $x };
+\& }
+.Ve
+.PP
+Perl 5.22 also introduces the experimental "const" attribute as an
+alternative. (Disable the "experimental::const_attr" warnings if you want
+to use it.) When applied to an anonymous subroutine, it forces the sub to
+be called when the \f(CW\*(C`sub\*(C'\fR expression is evaluated. The return value is
+captured and turned into a constant subroutine:
+.PP
+.Vb 3
+\& my $x = 54321;
+\& *INLINED = sub : const { $x };
+\& $x++;
+.Ve
+.PP
+The return value of \f(CW\*(C`INLINED\*(C'\fR in this example will always be 54321,
+regardless of later modifications to \f(CW$x\fR. You can also put any arbitrary
+code inside the sub, at it will be executed immediately and its return
+value captured the same way.
+.PP
+If you really want a subroutine with a \f(CW\*(C`()\*(C'\fR prototype that returns a
+lexical variable you can easily force it to not be inlined by adding
+an explicit \f(CW\*(C`return\*(C'\fR:
+.PP
+.Vb 6
+\& BEGIN {
+\& my $x = 10;
+\& *FOO = sub () { return $x };
+\& $x++;
+\& }
+\& print FOO(); # prints 11
+.Ve
+.PP
+The easiest way to tell if a subroutine was inlined is by using
+B::Deparse. Consider this example of two subroutines returning
+\&\f(CW1\fR, one with a \f(CW\*(C`()\*(C'\fR prototype causing it to be inlined, and one
+without (with deparse output truncated for clarity):
+.PP
+.Vb 7
+\& $ perl \-MO=Deparse \-e \*(Aqsub ONE { 1 } if (ONE) { print ONE if ONE }\*(Aq
+\& sub ONE {
+\& 1;
+\& }
+\& if (ONE ) {
+\& print ONE() if ONE ;
+\& }
+\&
+\& $ perl \-MO=Deparse \-e \*(Aqsub ONE () { 1 } if (ONE) { print ONE if ONE }\*(Aq
+\& sub ONE () { 1 }
+\& do {
+\& print 1
+\& };
+.Ve
+.PP
+If you redefine a subroutine that was eligible for inlining, you'll
+get a warning by default. You can use this warning to tell whether or
+not a particular subroutine is considered inlinable, since it's
+different than the warning for overriding non-inlined subroutines:
+.PP
+.Vb 4
+\& $ perl \-e \*(Aqsub one () {1} sub one () {2}\*(Aq
+\& Constant subroutine one redefined at \-e line 1.
+\& $ perl \-we \*(Aqsub one {1} sub one {2}\*(Aq
+\& Subroutine one redefined at \-e line 1.
+.Ve
+.PP
+The warning is considered severe enough not to be affected by the
+\&\fB\-w\fR switch (or its absence) because previously compiled invocations
+of the function will still be using the old value of the function. If
+you need to be able to redefine the subroutine, you need to ensure
+that it isn't inlined, either by dropping the \f(CW\*(C`()\*(C'\fR prototype (which
+changes calling semantics, so beware) or by thwarting the inlining
+mechanism in some other way, e.g. by adding an explicit \f(CW\*(C`return\*(C'\fR, as
+mentioned above:
+.PP
+.Vb 1
+\& sub not_inlined () { return 23 }
+.Ve
+.SS "Overriding Built-in Functions"
+.IX Xref "built-in override CORE CORE::GLOBAL"
+.IX Subsection "Overriding Built-in Functions"
+Many built-in functions may be overridden, though this should be tried
+only occasionally and for good reason. Typically this might be
+done by a package attempting to emulate missing built-in functionality
+on a non-Unix system.
+.PP
+Overriding may be done only by importing the name from a module at
+compile time\-\-ordinary predeclaration isn't good enough. However, the
+\&\f(CW\*(C`use subs\*(C'\fR pragma lets you, in effect, predeclare subs
+via the import syntax, and these names may then override built-in ones:
+.PP
+.Vb 3
+\& use subs \*(Aqchdir\*(Aq, \*(Aqchroot\*(Aq, \*(Aqchmod\*(Aq, \*(Aqchown\*(Aq;
+\& chdir $somewhere;
+\& sub chdir { ... }
+.Ve
+.PP
+To unambiguously refer to the built-in form, precede the
+built-in name with the special package qualifier \f(CW\*(C`CORE::\*(C'\fR. For example,
+saying \f(CWCORE::open()\fR always refers to the built-in \f(CWopen()\fR, even
+if the current package has imported some other subroutine called
+\&\f(CW&open()\fR from elsewhere. Even though it looks like a regular
+function call, it isn't: the \f(CW\*(C`CORE::\*(C'\fR prefix in that case is part of Perl's
+syntax, and works for any keyword, regardless of what is in the \f(CW\*(C`CORE\*(C'\fR
+package. Taking a reference to it, that is, \f(CW\*(C`\e&CORE::open\*(C'\fR, only works
+for some keywords. See CORE.
+.PP
+Library modules should not in general export built-in names like \f(CW\*(C`open\*(C'\fR
+or \f(CW\*(C`chdir\*(C'\fR as part of their default \f(CW@EXPORT\fR list, because these may
+sneak into someone else's namespace and change the semantics unexpectedly.
+Instead, if the module adds that name to \f(CW@EXPORT_OK\fR, then it's
+possible for a user to import the name explicitly, but not implicitly.
+That is, they could say
+.PP
+.Vb 1
+\& use Module \*(Aqopen\*(Aq;
+.Ve
+.PP
+and it would import the \f(CW\*(C`open\*(C'\fR override. But if they said
+.PP
+.Vb 1
+\& use Module;
+.Ve
+.PP
+they would get the default imports without overrides.
+.PP
+The foregoing mechanism for overriding built-in is restricted, quite
+deliberately, to the package that requests the import. There is a second
+method that is sometimes applicable when you wish to override a built-in
+everywhere, without regard to namespace boundaries. This is achieved by
+importing a sub into the special namespace \f(CW\*(C`CORE::GLOBAL::\*(C'\fR. Here is an
+example that quite brazenly replaces the \f(CW\*(C`glob\*(C'\fR operator with something
+that understands regular expressions.
+.PP
+.Vb 4
+\& package REGlob;
+\& require Exporter;
+\& @ISA = \*(AqExporter\*(Aq;
+\& @EXPORT_OK = \*(Aqglob\*(Aq;
+\&
+\& sub import {
+\& my $pkg = shift;
+\& return unless @_;
+\& my $sym = shift;
+\& my $where = ($sym =~ s/^GLOBAL_// ? \*(AqCORE::GLOBAL\*(Aq : caller(0));
+\& $pkg\->export($where, $sym, @_);
+\& }
+\&
+\& sub glob {
+\& my $pat = shift;
+\& my @got;
+\& if (opendir my $d, \*(Aq.\*(Aq) {
+\& @got = grep /$pat/, readdir $d;
+\& closedir $d;
+\& }
+\& return @got;
+\& }
+\& 1;
+.Ve
+.PP
+And here's how it could be (ab)used:
+.PP
+.Vb 4
+\& #use REGlob \*(AqGLOBAL_glob\*(Aq; # override glob() in ALL namespaces
+\& package Foo;
+\& use REGlob \*(Aqglob\*(Aq; # override glob() in Foo:: only
+\& print for <^[a\-z_]+\e.pm\e$>; # show all pragmatic modules
+.Ve
+.PP
+The initial comment shows a contrived, even dangerous example.
+By overriding \f(CW\*(C`glob\*(C'\fR globally, you would be forcing the new (and
+subversive) behavior for the \f(CW\*(C`glob\*(C'\fR operator for \fIevery\fR namespace,
+without the complete cognizance or cooperation of the modules that own
+those namespaces. Naturally, this should be done with extreme caution\-\-if
+it must be done at all.
+.PP
+The \f(CW\*(C`REGlob\*(C'\fR example above does not implement all the support needed to
+cleanly override Perl's \f(CW\*(C`glob\*(C'\fR operator. The built-in \f(CW\*(C`glob\*(C'\fR has
+different behaviors depending on whether it appears in a scalar or list
+context, but our \f(CW\*(C`REGlob\*(C'\fR doesn't. Indeed, many Perl built-ins have such
+context sensitive behaviors, and these must be adequately supported by
+a properly written override. For a fully functional example of overriding
+\&\f(CW\*(C`glob\*(C'\fR, study the implementation of \f(CW\*(C`File::DosGlob\*(C'\fR in the standard
+library.
+.PP
+When you override a built-in, your replacement should be consistent (if
+possible) with the built-in native syntax. You can achieve this by using
+a suitable prototype. To get the prototype of an overridable built-in,
+use the \f(CW\*(C`prototype\*(C'\fR function with an argument of \f(CW"CORE::builtin_name"\fR
+(see "prototype" in perlfunc).
+.PP
+Note however that some built-ins can't have their syntax expressed by a
+prototype (such as \f(CW\*(C`system\*(C'\fR or \f(CW\*(C`chomp\*(C'\fR). If you override them you won't
+be able to fully mimic their original syntax.
+.PP
+The built-ins \f(CW\*(C`do\*(C'\fR, \f(CW\*(C`require\*(C'\fR and \f(CW\*(C`glob\*(C'\fR can also be overridden, but due
+to special magic, their original syntax is preserved, and you don't have
+to define a prototype for their replacements. (You can't override the
+\&\f(CW\*(C`do BLOCK\*(C'\fR syntax, though).
+.PP
+\&\f(CW\*(C`require\*(C'\fR has special additional dark magic: if you invoke your
+\&\f(CW\*(C`require\*(C'\fR replacement as \f(CW\*(C`require Foo::Bar\*(C'\fR, it will actually receive
+the argument \f(CW"Foo/Bar.pm"\fR in \f(CW@_\fR. See "require" in perlfunc.
+.PP
+And, as you'll have noticed from the previous example, if you override
+\&\f(CW\*(C`glob\*(C'\fR, the \f(CW\*(C`<*>\*(C'\fR glob operator is overridden as well.
+.PP
+In a similar fashion, overriding the \f(CW\*(C`readline\*(C'\fR function also overrides
+the equivalent I/O operator \f(CW\*(C`<FILEHANDLE>\*(C'\fR. Also, overriding
+\&\f(CW\*(C`readpipe\*(C'\fR also overrides the operators \f(CW\`\`\fR and \f(CW\*(C`qx//\*(C'\fR.
+.PP
+Finally, some built-ins (e.g. \f(CW\*(C`exists\*(C'\fR or \f(CW\*(C`grep\*(C'\fR) can't be overridden.
+.SS Autoloading
+.IX Xref "autoloading AUTOLOAD"
+.IX Subsection "Autoloading"
+If you call a subroutine that is undefined, you would ordinarily
+get an immediate, fatal error complaining that the subroutine doesn't
+exist. (Likewise for subroutines being used as methods, when the
+method doesn't exist in any base class of the class's package.)
+However, if an \f(CW\*(C`AUTOLOAD\*(C'\fR subroutine is defined in the package or
+packages used to locate the original subroutine, then that
+\&\f(CW\*(C`AUTOLOAD\*(C'\fR subroutine is called with the arguments that would have
+been passed to the original subroutine. The fully qualified name
+of the original subroutine magically appears in the global \f(CW$AUTOLOAD\fR
+variable of the same package as the \f(CW\*(C`AUTOLOAD\*(C'\fR routine. The name
+is not passed as an ordinary argument because, er, well, just
+because, that's why. (As an exception, a method call to a nonexistent
+\&\f(CW\*(C`import\*(C'\fR or \f(CW\*(C`unimport\*(C'\fR method is just skipped instead. Also, if
+the AUTOLOAD subroutine is an XSUB, there are other ways to retrieve the
+subroutine name. See "Autoloading with XSUBs" in perlguts for details.)
+.PP
+Many \f(CW\*(C`AUTOLOAD\*(C'\fR routines load in a definition for the requested
+subroutine using \fBeval()\fR, then execute that subroutine using a special
+form of \fBgoto()\fR that erases the stack frame of the \f(CW\*(C`AUTOLOAD\*(C'\fR routine
+without a trace. (See the source to the standard module documented
+in AutoLoader, for example.) But an \f(CW\*(C`AUTOLOAD\*(C'\fR routine can
+also just emulate the routine and never define it. For example,
+let's pretend that a function that wasn't defined should just invoke
+\&\f(CW\*(C`system\*(C'\fR with those arguments. All you'd do is:
+.PP
+.Vb 9
+\& sub AUTOLOAD {
+\& our $AUTOLOAD; # keep \*(Aquse strict\*(Aq happy
+\& my $program = $AUTOLOAD;
+\& $program =~ s/.*:://;
+\& system($program, @_);
+\& }
+\& date();
+\& who();
+\& ls(\*(Aq\-l\*(Aq);
+.Ve
+.PP
+In fact, if you predeclare functions you want to call that way, you don't
+even need parentheses:
+.PP
+.Vb 4
+\& use subs qw(date who ls);
+\& date;
+\& who;
+\& ls \*(Aq\-l\*(Aq;
+.Ve
+.PP
+A more complete example of this is the Shell module on CPAN, which
+can treat undefined subroutine calls as calls to external programs.
+.PP
+Mechanisms are available to help modules writers split their modules
+into autoloadable files. See the standard AutoLoader module
+described in AutoLoader and in AutoSplit, the standard
+SelfLoader modules in SelfLoader, and the document on adding C
+functions to Perl code in perlxs.
+.SS "Subroutine Attributes"
+.IX Xref "attribute subroutine, attribute attrs"
+.IX Subsection "Subroutine Attributes"
+A subroutine declaration or definition may have a list of attributes
+associated with it. If such an attribute list is present, it is
+broken up at space or colon boundaries and treated as though a
+\&\f(CW\*(C`use attributes\*(C'\fR had been seen. See attributes for details
+about what attributes are currently supported.
+Unlike the limitation with the obsolescent \f(CW\*(C`use attrs\*(C'\fR, the
+\&\f(CW\*(C`sub : ATTRLIST\*(C'\fR syntax works to associate the attributes with
+a pre-declaration, and not just with a subroutine definition.
+.PP
+The attributes must be valid as simple identifier names (without any
+punctuation other than the '_' character). They may have a parameter
+list appended, which is only checked for whether its parentheses ('(',')')
+nest properly.
+.PP
+Examples of valid syntax (even though the attributes are unknown):
+.PP
+.Vb 3
+\& sub fnord (&\e%) : switch(10,foo(7,3)) : expensive;
+\& sub plugh () : Ugly(\*(Aq\e(") :Bad;
+\& sub xyzzy : _5x5 { ... }
+.Ve
+.PP
+Examples of invalid syntax:
+.PP
+.Vb 5
+\& sub fnord : switch(10,foo(); # ()\-string not balanced
+\& sub snoid : Ugly(\*(Aq(\*(Aq); # ()\-string not balanced
+\& sub xyzzy : 5x5; # "5x5" not a valid identifier
+\& sub plugh : Y2::north; # "Y2::north" not a simple identifier
+\& sub snurt : foo + bar; # "+" not a colon or space
+.Ve
+.PP
+The attribute list is passed as a list of constant strings to the code
+which associates them with the subroutine. In particular, the second example
+of valid syntax above currently looks like this in terms of how it's
+parsed and invoked:
+.PP
+.Vb 1
+\& use attributes _\|_PACKAGE_\|_, \e&plugh, q[Ugly(\*(Aq\e(")], \*(AqBad\*(Aq;
+.Ve
+.PP
+For further details on attribute lists and their manipulation,
+see attributes and Attribute::Handlers.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+See "Function Templates" in perlref for more about references and closures.
+See perlxs if you'd like to learn about calling C subroutines from Perl.
+See perlembed if you'd like to learn about calling Perl subroutines from C.
+See perlmod to learn about bundling up your functions in separate files.
+See perlmodlib to learn what library modules come standard on your system.
+See perlootut to learn how to make object method calls.