Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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.