diff options
Diffstat (limited to 'upstream/debian-bookworm/man1/perlsub.1')
| -rw-r--r-- | upstream/debian-bookworm/man1/perlsub.1 | 2346 |
1 files changed, 2346 insertions, 0 deletions
diff --git a/upstream/debian-bookworm/man1/perlsub.1 b/upstream/debian-bookworm/man1/perlsub.1 new file mode 100644 index 00000000..1df1ceec --- /dev/null +++ b/upstream/debian-bookworm/man1/perlsub.1 @@ -0,0 +1,2346 @@ +.\" Automatically generated by Pod::Man 4.14 (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 +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. 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 "2023-11-25" "perl v5.36.0" "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 \s-1CODE\s0 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 \*(L"Signatures\*(R" 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(CW\*(C`my()\*(C'\fR list of these. Variables that aren't declared to be private are +global variables. For gory details on creating private variables, see +\&\*(L"Private Variables via \fBmy()\fR\*(R" and \*(L"Temporary Values via \fBlocal()\fR\*(R". +To create protected environments for a set of functions in a separate +package (and probably a separate file), see \*(L"Packages\*(R" 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(CW\*(C`upcase_in()\*(C'\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(CW\*(C`upcase()\*(C'\fR +function would work perfectly well without changing the \f(CW\*(C`upcase()\*(C'\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 +\& (@a, @b) = 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@a\fR and made \f(CW@b\fR empty. See +\&\*(L"Pass by Reference\*(R" 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\*(C`&$subref()\*(C'\fR or \f(CW\*(C`&{$subref}()\*(C'\fR constructs, +although the \f(CW\*(C`$subref\->()\*(C'\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 \*(L"Prototypes\*(R" below. +.IX Xref "&" +.PP +Since Perl 5.16.0, the \f(CW\*(C`_\|_SUB_\|_\*(C'\fR token is available under \f(CW\*(C`use feature +\&\*(Aqcurrent_sub\*(Aq\*(C'\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 \s-1UNIVERSAL\s0" 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 \*(L"\s-1BEGIN, UNITCHECK, CHECK, INIT\s0 and \s-1END\*(R"\s0 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 ($a, $b = 1, @c) { .... } +.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 +\&\s-1ID\s0 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 +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 \*(L"void\*(R" 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 \*(L"Prototypes\*(R"), 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 +\&\fB\s-1WARNING\s0\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(CW\*(C`bumpx()\*(C'\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(CW\*(C`eval()\*(C'\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(CW\*(C`eval()\*(C'\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"; +\& 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 \*(L"Simple Statements\*(R" 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(CW\*(C`some_function()\*(C'\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 \fI\s-1REALLY\s0\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 +\&\*(L"Function Templates\*(R" 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 \f(BIstate()\fI\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 \s-1FILE,\s0 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 \*(L"\s-1BEGIN, UNITCHECK, CHECK, INIT\s0 and \s-1END\*(R"\s0 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()" +\&\fB\s-1WARNING\s0\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 \*(L"local\*(R" 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 \f(BIlocal()\fI\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(CW\*(C`local($_)\*(C'\fR will always strip all magic from \f(CW$_\fR, to make it possible +to safely reuse \f(CW$_\fR in a subroutine. +.PP +\&\fB\s-1WARNING\s0\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 \*(L"Localising Tied Arrays and Hashes Is Broken\*(R" 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(CW\*(C`local()\*(C'\fR ends, the saved value will be +restored to the hash element whose key was named in the \f(CW\*(C`local()\*(C'\fR, or +the array element whose index was named in the \f(CW\*(C`local()\*(C'\fR. If that +element was deleted while the \f(CW\*(C`local()\*(C'\fR was in effect (e.g. by a +\&\f(CW\*(C`delete()\*(C'\fR from a hash or a \f(CW\*(C`shift()\*(C'\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 $a = delete local $hash{a}; +\& # $a is [ 7, 8, 9 ] +\& # %hash is (b => 1) +\& +\& { +\& my @nums = delete local @$a[0, 2] +\& # @nums is (7, 9) +\& # $a is [ undef, 8 ] +\& +\& $a[0] = 999; # will be erased when the scope ends +\& } +\& # $a 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 \s-1CPAN\s0 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 \*(L"experimental::lexical_subs\*(R" 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(CW\*(C`baz()\*(C'\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 \*(L"Circular References\*(R" in perlref). +.PP +\fI\f(CI\*(C`state sub\*(C'\fI vs \f(CI\*(C`my sub\*(C'\fI\fR +.IX Subsection "state sub vs my sub" +.PP +What is the difference between \*(L"state\*(R" subs and \*(L"my\*(R" subs? Each time that +execution enters a block when \*(L"my\*(R" subs are declared, a new copy of each +sub is created. \*(L"State\*(R" subroutines persist from one execution of the +containing block to the next. +.PP +So, in general, \*(L"state\*(R" subroutines are faster. But \*(L"my\*(R" 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 \*(L"state\*(R" sub will only +see the \f(CW$x\fR from the first call to \f(CW\*(C`whatever\*(C'\fR. +.PP +\fI\f(CI\*(C`our\*(C'\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)" +\&\fB\s-1WARNING\s0\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 \*(L"typeglob\*(R", 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 \s-1LIST,\s0 because normally the \s-1LIST\s0 +mechanism will merge all the array values so that you can't extract out +the individual arrays. For more on typeglobs, see +\&\*(L"Typeglobs and Filehandles\*(R" 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(CW\*(C`local()\*(C'\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(CW\*(C`local()\*(C'\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 \*(L"Function Templates\*(R" 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@a, \e@b, \e@c, \e@d ); +\& +\& 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 +\& (@a, @b) = func(@c, @d); +\&or +\& (%a, %b) = func(%c, %d); +.Ve +.PP +That syntax simply won't work. It sets just \f(CW@a\fR or \f(CW%a\fR and +clears the \f(CW@b\fR or \f(CW%b\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 +\& ($aref, $bref) = func(\e@c, \e@d); +\& print "@$aref has more than @$bref\en"; +\& sub func { +\& my ($cref, $dref) = @_; +\& if (@$cref > @$dref) { +\& return ($cref, $dref); +\& } else { +\& return ($dref, $cref); +\& } +\& } +.Ve +.PP +It turns out that you can actually do this also: +.PP +.Vb 10 +\& (*a, *b) = func(\e@c, \e@d); +\& print "@a has more than @b\en"; +\& sub func { +\& local (*c, *d) = @_; +\& if (@c > @d) { +\& return (\e@c, \e@d); +\& } else { +\& return (\e@d, \e@c); +\& } +\& } +.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 \s-1PROTO\s0 +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(CW\*(C`mypush()\*(C'\fR takes arguments exactly like \f(CW\*(C`push()\*(C'\fR does. +.PP +If subroutine signatures are enabled (see \*(L"Signatures\*(R"), then +the shorter \s-1PROTO\s0 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\*(C`$subref\->()\*(C'\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 $a, $b, $c +\& sub myjoin ($@) myjoin ":", $a, $b, $c +\& 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/ } $a, $b, $c +\& 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(CW\*(C`mygrep()\*(C'\fR is parsed as a true list +operator, \f(CW\*(C`myrand()\*(C'\fR is parsed as a true unary operator with unary +precedence the same as \f(CW\*(C`rand()\*(C'\fR, and \f(CW\*(C`mytime()\*(C'\fR is truly without +arguments, just like \f(CW\*(C`time()\*(C'\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 $a > $b; # parsed as mygetprotobynumber($a > $b) +.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 \- \*(L"Illegal character in prototype...\*(R". +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(CW\*(C`func()\*(C'\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(CW\*(C`pos($text)\*(C'\fR. Ouch! +.PP +If a sub has both a \s-1PROTO\s0 and a \s-1BLOCK,\s0 the prototype is not applied +until after the \s-1BLOCK\s0 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 +\&\s-1BEGIN\s0 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 [\s-1RT\s0 #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 \*(L"const\*(R" attribute as an +alternative. (Disable the \*(L"experimental::const_attr\*(R" 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 \-le \*(Aqsub ONE { 1 } if (ONE) { print ONE if ONE }\*(Aq +\& sub ONE { +\& 1; +\& } +\& if (ONE ) { +\& print ONE() if ONE ; +\& } +\& +\& $ perl \-MO=Deparse \-le \*(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(CW\*(C`CORE::open()\*(C'\fR always refers to the built-in \f(CW\*(C`open()\*(C'\fR, even +if the current package has imported some other subroutine called +\&\f(CW\*(C`&open()\*(C'\fR from elsewhere. Even though it looks like a regular +function call, it isn't: the \s-1CORE::\s0 prefix in that case is part of Perl's +syntax, and works for any keyword, regardless of what is in the \s-1CORE\s0 +package. Taking a reference to it, that is, \f(CW\*(C`\e&CORE::open\*(C'\fR, only works +for some keywords. See \s-1CORE\s0. +.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-in 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 \*(L"prototype\*(R" 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 \*(L"require\*(R" 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\*(C`\`\`\*(C'\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 \s-1AUTOLOAD\s0 subroutine is an \s-1XSUB,\s0 there are other ways to retrieve the +subroutine name. See \*(L"Autoloading with XSUBs\*(R" 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 \s-1CPAN,\s0 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 \*(L"Function Templates\*(R" 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. |