diff options
Diffstat (limited to 'pod/perlsub.pod')
| -rw-r--r-- | pod/perlsub.pod | 215 |
1 files changed, 212 insertions, 3 deletions
diff --git a/pod/perlsub.pod b/pod/perlsub.pod index 2a9e0a838f..bf082628e0 100644 --- a/pod/perlsub.pod +++ b/pod/perlsub.pod @@ -15,16 +15,20 @@ X<subroutine, declaration> X<sub> sub NAME BLOCK # A declaration and a definition. sub NAME(PROTO) BLOCK # ditto, but with prototypes + sub NAME SIG BLOCK # with signature sub NAME : ATTRS BLOCK # with attributes sub NAME(PROTO) : ATTRS BLOCK # with prototypes and attributes + sub NAME : ATTRS SIG BLOCK # with attributes and signature To define an anonymous subroutine at runtime: X<subroutine, anonymous> $subref = sub BLOCK; # no proto $subref = sub (PROTO) BLOCK; # with proto + $subref = sub SIG BLOCK; # with signature $subref = sub : ATTRS BLOCK; # with attributes $subref = sub (PROTO) : ATTRS BLOCK; # with proto and attributes + $subref = sub : ATTRS SIG BLOCK; # with attribs and signature To import subroutines: X<import> @@ -59,7 +63,9 @@ function without an explicit return statement is called a subroutine, but there's really no difference from Perl's perspective.) X<subroutine, parameter> X<parameter> -Any arguments passed in show up in the array C<@_>. Therefore, if +Any arguments passed in show up in the array C<@_>. +(They may also show up in lexical variables introduced by a signature; +see L</Signatures> below.) Therefore, if you called a function with two arguments, those would be stored in C<$_[0]> and C<$_[1]>. The array C<@_> is a local array, but its elements are aliases for the actual scalar parameters. In particular, @@ -88,6 +94,7 @@ like a C<foreach> or a C<while>, the returned value is unspecified. The empty sub returns the empty list. X<subroutine, return value> X<return value> X<return> +Aside from an experimental facility (see L</Signatures> below), Perl does not have named formal parameters. In practice all you do is assign to a C<my()> list of these. Variables that aren't declared to be private are global variables. For gory details @@ -296,6 +303,200 @@ 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 B<not> call explicitly. See L<perlmod/"BEGIN, UNITCHECK, CHECK, INIT and END"> +=head2 Signatures + +B<WARNING>: Subroutine signatures are experimental. The feature may be +modified or removed in future versions of Perl. + +Perl has an experimental facility to allow a subroutine's formal +parameters to be introduced by special syntax, separate from the +procedural code of the subroutine body. The formal parameter list +is known as a I<signature>. The facility must be enabled first by a +pragmatic declaration, C<use feature 'signatures'>, and it will produce +a warning unless the "experimental::signatures" warnings category is +disabled. + +The signature is part of a subroutine's body. Normally the body of a +subroutine is simply a braced block of code. When using a signature, +the signature is a parenthesised list that goes immediately before +the braced block. 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. + +Positional parameters are handled by simply naming scalar variables in +the signature. For example, + + sub foo ($left, $right) { + return $left + $right; + } + +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 + + 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; + } + +An argument can be ignored by omitting the main part of the name from +a parameter declaration, leaving just a bare C<$> sigil. For example, + + sub foo ($first, $, $third) { + return "first=$first, third=$third"; + } + +Although the ignored argument doesn't go into a variable, it is still +mandatory for the caller to pass it. + +A positional parameter is made optional by giving a default value, +separated from the parameter name by C<=>: + + sub foo ($left, $right = 0) { + return $left + $right; + } + +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, + + my $auto_id = 0; + sub foo ($thing, $id = $auto_id++) { + print "$thing has ID $id"; + } + +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, + + sub foo ($first_name, $surname, $nickname = $first_name) { + print "$first_name $surname is known as \"$nickname\""; + } + +An optional parameter can be nameless just like a mandatory parameter. +For example, + + sub foo ($thing, $ = 1) { + print $thing; + } + +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: + + sub foo ($thing, $=) { + print $thing; + } + +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. + +After positional parameters, additional arguments may be captured in a +slurpy parameter. The simplest form of this is just an array variable: + + sub foo ($filter, @inputs) { + print $filter->($_) foreach @inputs; + } + +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: + + sub foo ($thing, @) { + print $thing; + } + +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. + + sub foo ($filter, %inputs) { + print $filter->($_, $inputs{$_}) foreach sort keys %inputs; + } + +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. + + sub foo ($thing, %) { + print $thing; + } + +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. + +A signature may be entirely empty, in which case all it does is check +that the caller passed no arguments: + + sub foo () { + return 123; + } + +When using a signature, the arguments are still available in the special +array variable C<@_>, in addition to the lexical variables of the +signature. There is a difference between the two ways of accessing the +arguments: C<@_> I<aliases> the arguments, but the signature variables +get I<copies> 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 C<@_> modifies whatever the caller used to +supply that argument. + +There is a potential syntactic ambiguity between signatures and prototypes +(see L</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. + +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 +L<prototype attribute|attributes/Built-in Attributes>. For example, + + sub foo :prototype($) { $_[0] } + +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 + + sub foo :prototype($$) ($left, $right) { + return $left + $right; + } + +The prototype attribute, and any other attributes, must come before +the signature. The signature always immediately precedes the block of +the subroutine's body. + =head2 Private Variables via my() X<my> X<variable, lexical> X<lexical> X<lexical variable> X<scope, lexical> X<lexical scope> X<attributes, my> @@ -1191,11 +1392,19 @@ X<prototype> X<subroutine, prototype> 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 L<prototype attribute|attributes/Built-in Attributes>. -If you declare +If you declare either of sub mypush (+@) + sub mypush :prototype(+@) + +then C<mypush()> takes arguments exactly like C<push()> does. + +If subroutine signatures are enabled (see L</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. -then C<mypush()> takes arguments exactly like C<push()> does. The +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 C<&> character. In |