| 1 | =head1 NAME |
| 2 | X<subroutine> X<function> |
| 3 | |
| 4 | perlsub - Perl subroutines |
| 5 | |
| 6 | =head1 SYNOPSIS |
| 7 | |
| 8 | To declare subroutines: |
| 9 | X<subroutine, declaration> X<sub> |
| 10 | |
| 11 | sub NAME; # A "forward" declaration. |
| 12 | sub NAME(PROTO); # ditto, but with prototypes |
| 13 | sub NAME : ATTRS; # with attributes |
| 14 | sub NAME(PROTO) : ATTRS; # with attributes and prototypes |
| 15 | |
| 16 | sub NAME BLOCK # A declaration and a definition. |
| 17 | sub NAME(PROTO) BLOCK # ditto, but with prototypes |
| 18 | sub NAME(SIG) BLOCK # with a signature instead |
| 19 | sub NAME : ATTRS BLOCK # with attributes |
| 20 | sub NAME(PROTO) : ATTRS BLOCK # with prototypes and attributes |
| 21 | sub NAME(SIG) : ATTRS BLOCK # with a signature and attributes |
| 22 | |
| 23 | To define an anonymous subroutine at runtime: |
| 24 | X<subroutine, anonymous> |
| 25 | |
| 26 | $subref = sub BLOCK; # no proto |
| 27 | $subref = sub (PROTO) BLOCK; # with proto |
| 28 | $subref = sub (SIG) BLOCK; # with signature |
| 29 | $subref = sub : ATTRS BLOCK; # with attributes |
| 30 | $subref = sub (PROTO) : ATTRS BLOCK; # with proto and attributes |
| 31 | $subref = sub (SIG) : ATTRS BLOCK; # with signature and attributes |
| 32 | |
| 33 | To import subroutines: |
| 34 | X<import> |
| 35 | |
| 36 | use MODULE qw(NAME1 NAME2 NAME3); |
| 37 | |
| 38 | To call subroutines: |
| 39 | X<subroutine, call> X<call> |
| 40 | |
| 41 | NAME(LIST); # & is optional with parentheses. |
| 42 | NAME LIST; # Parentheses optional if predeclared/imported. |
| 43 | &NAME(LIST); # Circumvent prototypes. |
| 44 | &NAME; # Makes current @_ visible to called subroutine. |
| 45 | |
| 46 | =head1 DESCRIPTION |
| 47 | |
| 48 | Like many languages, Perl provides for user-defined subroutines. |
| 49 | These may be located anywhere in the main program, loaded in from |
| 50 | other files via the C<do>, C<require>, or C<use> keywords, or |
| 51 | generated on the fly using C<eval> or anonymous subroutines. |
| 52 | You can even call a function indirectly using a variable containing |
| 53 | its name or a CODE reference. |
| 54 | |
| 55 | The Perl model for function call and return values is simple: all |
| 56 | functions are passed as parameters one single flat list of scalars, and |
| 57 | all functions likewise return to their caller one single flat list of |
| 58 | scalars. Any arrays or hashes in these call and return lists will |
| 59 | collapse, losing their identities--but you may always use |
| 60 | pass-by-reference instead to avoid this. Both call and return lists may |
| 61 | contain as many or as few scalar elements as you'd like. (Often a |
| 62 | function without an explicit return statement is called a subroutine, but |
| 63 | there's really no difference from Perl's perspective.) |
| 64 | X<subroutine, parameter> X<parameter> |
| 65 | |
| 66 | Any arguments passed in show up in the array C<@_>. |
| 67 | (They may also show up in lexical variables introduced by a signature; |
| 68 | see L</Signatures> below.) Therefore, if |
| 69 | you called a function with two arguments, those would be stored in |
| 70 | C<$_[0]> and C<$_[1]>. The array C<@_> is a local array, but its |
| 71 | elements are aliases for the actual scalar parameters. In particular, |
| 72 | if an element C<$_[0]> is updated, the corresponding argument is |
| 73 | updated (or an error occurs if it is not updatable). If an argument |
| 74 | is an array or hash element which did not exist when the function |
| 75 | was called, that element is created only when (and if) it is modified |
| 76 | or a reference to it is taken. (Some earlier versions of Perl |
| 77 | created the element whether or not the element was assigned to.) |
| 78 | Assigning to the whole array C<@_> removes that aliasing, and does |
| 79 | not update any arguments. |
| 80 | X<subroutine, argument> X<argument> X<@_> |
| 81 | |
| 82 | A C<return> statement may be used to exit a subroutine, optionally |
| 83 | specifying the returned value, which will be evaluated in the |
| 84 | appropriate context (list, scalar, or void) depending on the context of |
| 85 | the subroutine call. If you specify no return value, the subroutine |
| 86 | returns an empty list in list context, the undefined value in scalar |
| 87 | context, or nothing in void context. If you return one or more |
| 88 | aggregates (arrays and hashes), these will be flattened together into |
| 89 | one large indistinguishable list. |
| 90 | |
| 91 | If no C<return> is found and if the last statement is an expression, its |
| 92 | value is returned. If the last statement is a loop control structure |
| 93 | like a C<foreach> or a C<while>, the returned value is unspecified. The |
| 94 | empty sub returns the empty list. |
| 95 | X<subroutine, return value> X<return value> X<return> |
| 96 | |
| 97 | Aside from an experimental facility (see L</Signatures> below), |
| 98 | Perl does not have named formal parameters. In practice all you |
| 99 | do is assign to a C<my()> list of these. Variables that aren't |
| 100 | declared to be private are global variables. For gory details |
| 101 | on creating private variables, see L</"Private Variables via my()"> |
| 102 | and L</"Temporary Values via local()">. To create protected |
| 103 | environments for a set of functions in a separate package (and |
| 104 | probably a separate file), see L<perlmod/"Packages">. |
| 105 | X<formal parameter> X<parameter, formal> |
| 106 | |
| 107 | Example: |
| 108 | |
| 109 | sub max { |
| 110 | my $max = shift(@_); |
| 111 | foreach $foo (@_) { |
| 112 | $max = $foo if $max < $foo; |
| 113 | } |
| 114 | return $max; |
| 115 | } |
| 116 | $bestday = max($mon,$tue,$wed,$thu,$fri); |
| 117 | |
| 118 | Example: |
| 119 | |
| 120 | # get a line, combining continuation lines |
| 121 | # that start with whitespace |
| 122 | |
| 123 | sub get_line { |
| 124 | $thisline = $lookahead; # global variables! |
| 125 | LINE: while (defined($lookahead = <STDIN>)) { |
| 126 | if ($lookahead =~ /^[ \t]/) { |
| 127 | $thisline .= $lookahead; |
| 128 | } |
| 129 | else { |
| 130 | last LINE; |
| 131 | } |
| 132 | } |
| 133 | return $thisline; |
| 134 | } |
| 135 | |
| 136 | $lookahead = <STDIN>; # get first line |
| 137 | while (defined($line = get_line())) { |
| 138 | ... |
| 139 | } |
| 140 | |
| 141 | Assigning to a list of private variables to name your arguments: |
| 142 | |
| 143 | sub maybeset { |
| 144 | my($key, $value) = @_; |
| 145 | $Foo{$key} = $value unless $Foo{$key}; |
| 146 | } |
| 147 | |
| 148 | Because the assignment copies the values, this also has the effect |
| 149 | of turning call-by-reference into call-by-value. Otherwise a |
| 150 | function is free to do in-place modifications of C<@_> and change |
| 151 | its caller's values. |
| 152 | X<call-by-reference> X<call-by-value> |
| 153 | |
| 154 | upcase_in($v1, $v2); # this changes $v1 and $v2 |
| 155 | sub upcase_in { |
| 156 | for (@_) { tr/a-z/A-Z/ } |
| 157 | } |
| 158 | |
| 159 | You aren't allowed to modify constants in this way, of course. If an |
| 160 | argument were actually literal and you tried to change it, you'd take a |
| 161 | (presumably fatal) exception. For example, this won't work: |
| 162 | X<call-by-reference> X<call-by-value> |
| 163 | |
| 164 | upcase_in("frederick"); |
| 165 | |
| 166 | It would be much safer if the C<upcase_in()> function |
| 167 | were written to return a copy of its parameters instead |
| 168 | of changing them in place: |
| 169 | |
| 170 | ($v3, $v4) = upcase($v1, $v2); # this doesn't change $v1 and $v2 |
| 171 | sub upcase { |
| 172 | return unless defined wantarray; # void context, do nothing |
| 173 | my @parms = @_; |
| 174 | for (@parms) { tr/a-z/A-Z/ } |
| 175 | return wantarray ? @parms : $parms[0]; |
| 176 | } |
| 177 | |
| 178 | Notice how this (unprototyped) function doesn't care whether it was |
| 179 | passed real scalars or arrays. Perl sees all arguments as one big, |
| 180 | long, flat parameter list in C<@_>. This is one area where |
| 181 | Perl's simple argument-passing style shines. The C<upcase()> |
| 182 | function would work perfectly well without changing the C<upcase()> |
| 183 | definition even if we fed it things like this: |
| 184 | |
| 185 | @newlist = upcase(@list1, @list2); |
| 186 | @newlist = upcase( split /:/, $var ); |
| 187 | |
| 188 | Do not, however, be tempted to do this: |
| 189 | |
| 190 | (@a, @b) = upcase(@list1, @list2); |
| 191 | |
| 192 | Like the flattened incoming parameter list, the return list is also |
| 193 | flattened on return. So all you have managed to do here is stored |
| 194 | everything in C<@a> and made C<@b> empty. See |
| 195 | L</Pass by Reference> for alternatives. |
| 196 | |
| 197 | A subroutine may be called using an explicit C<&> prefix. The |
| 198 | C<&> is optional in modern Perl, as are parentheses if the |
| 199 | subroutine has been predeclared. The C<&> is I<not> optional |
| 200 | when just naming the subroutine, such as when it's used as |
| 201 | an argument to defined() or undef(). Nor is it optional when you |
| 202 | want to do an indirect subroutine call with a subroutine name or |
| 203 | reference using the C<&$subref()> or C<&{$subref}()> constructs, |
| 204 | although the C<< $subref->() >> notation solves that problem. |
| 205 | See L<perlref> for more about all that. |
| 206 | X<&> |
| 207 | |
| 208 | Subroutines may be called recursively. If a subroutine is called |
| 209 | using the C<&> form, the argument list is optional, and if omitted, |
| 210 | no C<@_> array is set up for the subroutine: the C<@_> array at the |
| 211 | time of the call is visible to subroutine instead. This is an |
| 212 | efficiency mechanism that new users may wish to avoid. |
| 213 | X<recursion> |
| 214 | |
| 215 | &foo(1,2,3); # pass three arguments |
| 216 | foo(1,2,3); # the same |
| 217 | |
| 218 | foo(); # pass a null list |
| 219 | &foo(); # the same |
| 220 | |
| 221 | &foo; # foo() get current args, like foo(@_) !! |
| 222 | foo; # like foo() IFF sub foo predeclared, else "foo" |
| 223 | |
| 224 | Not only does the C<&> form make the argument list optional, it also |
| 225 | disables any prototype checking on arguments you do provide. This |
| 226 | is partly for historical reasons, and partly for having a convenient way |
| 227 | to cheat if you know what you're doing. See L</Prototypes> below. |
| 228 | X<&> |
| 229 | |
| 230 | Since Perl 5.16.0, the C<__SUB__> token is available under C<use feature |
| 231 | 'current_sub'> and C<use 5.16.0>. It will evaluate to a reference to the |
| 232 | currently-running sub, which allows for recursive calls without knowing |
| 233 | your subroutine's name. |
| 234 | |
| 235 | use 5.16.0; |
| 236 | my $factorial = sub { |
| 237 | my ($x) = @_; |
| 238 | return 1 if $x == 1; |
| 239 | return($x * __SUB__->( $x - 1 ) ); |
| 240 | }; |
| 241 | |
| 242 | The behavior of C<__SUB__> within a regex code block (such as C</(?{...})/>) |
| 243 | is subject to change. |
| 244 | |
| 245 | Subroutines whose names are in all upper case are reserved to the Perl |
| 246 | core, as are modules whose names are in all lower case. A subroutine in |
| 247 | all capitals is a loosely-held convention meaning it will be called |
| 248 | indirectly by the run-time system itself, usually due to a triggered event. |
| 249 | Subroutines whose name start with a left parenthesis are also reserved the |
| 250 | same way. The following is a list of some subroutines that currently do |
| 251 | special, pre-defined things. |
| 252 | |
| 253 | =over |
| 254 | |
| 255 | =item documented later in this document |
| 256 | |
| 257 | C<AUTOLOAD> |
| 258 | |
| 259 | =item documented in L<perlmod> |
| 260 | |
| 261 | C<CLONE>, C<CLONE_SKIP> |
| 262 | |
| 263 | =item documented in L<perlobj> |
| 264 | |
| 265 | C<DESTROY>, C<DOES> |
| 266 | |
| 267 | =item documented in L<perltie> |
| 268 | |
| 269 | C<BINMODE>, C<CLEAR>, C<CLOSE>, C<DELETE>, C<DESTROY>, C<EOF>, C<EXISTS>, |
| 270 | C<EXTEND>, C<FETCH>, C<FETCHSIZE>, C<FILENO>, C<FIRSTKEY>, C<GETC>, |
| 271 | C<NEXTKEY>, C<OPEN>, C<POP>, C<PRINT>, C<PRINTF>, C<PUSH>, C<READ>, |
| 272 | C<READLINE>, C<SCALAR>, C<SEEK>, C<SHIFT>, C<SPLICE>, C<STORE>, |
| 273 | C<STORESIZE>, C<TELL>, C<TIEARRAY>, C<TIEHANDLE>, C<TIEHASH>, |
| 274 | C<TIESCALAR>, C<UNSHIFT>, C<UNTIE>, C<WRITE> |
| 275 | |
| 276 | =item documented in L<PerlIO::via> |
| 277 | |
| 278 | C<BINMODE>, C<CLEARERR>, C<CLOSE>, C<EOF>, C<ERROR>, C<FDOPEN>, C<FILENO>, |
| 279 | C<FILL>, C<FLUSH>, C<OPEN>, C<POPPED>, C<PUSHED>, C<READ>, C<SEEK>, |
| 280 | C<SETLINEBUF>, C<SYSOPEN>, C<TELL>, C<UNREAD>, C<UTF8>, C<WRITE> |
| 281 | |
| 282 | =item documented in L<perlfunc> |
| 283 | |
| 284 | L<< C<import> | perlfunc/use >>, L<< C<unimport> | perlfunc/use >>, |
| 285 | L<< C<INC> | perlfunc/require >> |
| 286 | |
| 287 | =item documented in L<UNIVERSAL> |
| 288 | |
| 289 | C<VERSION> |
| 290 | |
| 291 | =item documented in L<perldebguts> |
| 292 | |
| 293 | C<DB::DB>, C<DB::sub>, C<DB::lsub>, C<DB::goto>, C<DB::postponed> |
| 294 | |
| 295 | =item undocumented, used internally by the L<overload> feature |
| 296 | |
| 297 | any starting with C<(> |
| 298 | |
| 299 | =back |
| 300 | |
| 301 | The C<BEGIN>, C<UNITCHECK>, C<CHECK>, C<INIT> and C<END> subroutines |
| 302 | are not so much subroutines as named special code blocks, of which you |
| 303 | can have more than one in a package, and which you can B<not> call |
| 304 | explicitly. See L<perlmod/"BEGIN, UNITCHECK, CHECK, INIT and END"> |
| 305 | |
| 306 | =head2 Signatures |
| 307 | |
| 308 | B<WARNING>: Subroutine signatures are experimental. The feature may be |
| 309 | modified or removed in future versions of Perl. |
| 310 | |
| 311 | Perl has an experimental facility to allow a subroutine's formal |
| 312 | parameters to be introduced by special syntax, separate from the |
| 313 | procedural code of the subroutine body. The formal parameter list |
| 314 | is known as a I<signature>. The facility must be enabled first by a |
| 315 | pragmatic declaration, C<use feature 'signatures'>, and it will produce |
| 316 | a warning unless the "experimental::signatures" warnings category is |
| 317 | disabled. |
| 318 | |
| 319 | The signature is part of a subroutine's body. Normally the body of a |
| 320 | subroutine is simply a braced block of code. When using a signature, |
| 321 | the signature is a parenthesised list that goes immediately after |
| 322 | the subroutine name (or, for anonymous subroutines, immediately after |
| 323 | the C<sub> keyword). The signature declares lexical variables that are |
| 324 | in scope for the block. When the subroutine is called, the signature |
| 325 | takes control first. It populates the signature variables from the |
| 326 | list of arguments that were passed. If the argument list doesn't meet |
| 327 | the requirements of the signature, then it will throw an exception. |
| 328 | When the signature processing is complete, control passes to the block. |
| 329 | |
| 330 | Positional parameters are handled by simply naming scalar variables in |
| 331 | the signature. For example, |
| 332 | |
| 333 | sub foo ($left, $right) { |
| 334 | return $left + $right; |
| 335 | } |
| 336 | |
| 337 | takes two positional parameters, which must be filled at runtime by |
| 338 | two arguments. By default the parameters are mandatory, and it is |
| 339 | not permitted to pass more arguments than expected. So the above is |
| 340 | equivalent to |
| 341 | |
| 342 | sub foo { |
| 343 | die "Too many arguments for subroutine" unless @_ <= 2; |
| 344 | die "Too few arguments for subroutine" unless @_ >= 2; |
| 345 | my $left = $_[0]; |
| 346 | my $right = $_[1]; |
| 347 | return $left + $right; |
| 348 | } |
| 349 | |
| 350 | An argument can be ignored by omitting the main part of the name from |
| 351 | a parameter declaration, leaving just a bare C<$> sigil. For example, |
| 352 | |
| 353 | sub foo ($first, $, $third) { |
| 354 | return "first=$first, third=$third"; |
| 355 | } |
| 356 | |
| 357 | Although the ignored argument doesn't go into a variable, it is still |
| 358 | mandatory for the caller to pass it. |
| 359 | |
| 360 | A positional parameter is made optional by giving a default value, |
| 361 | separated from the parameter name by C<=>: |
| 362 | |
| 363 | sub foo ($left, $right = 0) { |
| 364 | return $left + $right; |
| 365 | } |
| 366 | |
| 367 | The above subroutine may be called with either one or two arguments. |
| 368 | The default value expression is evaluated when the subroutine is called, |
| 369 | so it may provide different default values for different calls. It is |
| 370 | only evaluated if the argument was actually omitted from the call. |
| 371 | For example, |
| 372 | |
| 373 | my $auto_id = 0; |
| 374 | sub foo ($thing, $id = $auto_id++) { |
| 375 | print "$thing has ID $id"; |
| 376 | } |
| 377 | |
| 378 | automatically assigns distinct sequential IDs to things for which no |
| 379 | ID was supplied by the caller. A default value expression may also |
| 380 | refer to parameters earlier in the signature, making the default for |
| 381 | one parameter vary according to the earlier parameters. For example, |
| 382 | |
| 383 | sub foo ($first_name, $surname, $nickname = $first_name) { |
| 384 | print "$first_name $surname is known as \"$nickname\""; |
| 385 | } |
| 386 | |
| 387 | An optional parameter can be nameless just like a mandatory parameter. |
| 388 | For example, |
| 389 | |
| 390 | sub foo ($thing, $ = 1) { |
| 391 | print $thing; |
| 392 | } |
| 393 | |
| 394 | The parameter's default value will still be evaluated if the corresponding |
| 395 | argument isn't supplied, even though the value won't be stored anywhere. |
| 396 | This is in case evaluating it has important side effects. However, it |
| 397 | will be evaluated in void context, so if it doesn't have side effects |
| 398 | and is not trivial it will generate a warning if the "void" warning |
| 399 | category is enabled. If a nameless optional parameter's default value |
| 400 | is not important, it may be omitted just as the parameter's name was: |
| 401 | |
| 402 | sub foo ($thing, $=) { |
| 403 | print $thing; |
| 404 | } |
| 405 | |
| 406 | Optional positional parameters must come after all mandatory positional |
| 407 | parameters. (If there are no mandatory positional parameters then an |
| 408 | optional positional parameters can be the first thing in the signature.) |
| 409 | If there are multiple optional positional parameters and not enough |
| 410 | arguments are supplied to fill them all, they will be filled from left |
| 411 | to right. |
| 412 | |
| 413 | After positional parameters, additional arguments may be captured in a |
| 414 | slurpy parameter. The simplest form of this is just an array variable: |
| 415 | |
| 416 | sub foo ($filter, @inputs) { |
| 417 | print $filter->($_) foreach @inputs; |
| 418 | } |
| 419 | |
| 420 | With a slurpy parameter in the signature, there is no upper limit on how |
| 421 | many arguments may be passed. A slurpy array parameter may be nameless |
| 422 | just like a positional parameter, in which case its only effect is to |
| 423 | turn off the argument limit that would otherwise apply: |
| 424 | |
| 425 | sub foo ($thing, @) { |
| 426 | print $thing; |
| 427 | } |
| 428 | |
| 429 | A slurpy parameter may instead be a hash, in which case the arguments |
| 430 | available to it are interpreted as alternating keys and values. |
| 431 | There must be as many keys as values: if there is an odd argument then |
| 432 | an exception will be thrown. Keys will be stringified, and if there are |
| 433 | duplicates then the later instance takes precedence over the earlier, |
| 434 | as with standard hash construction. |
| 435 | |
| 436 | sub foo ($filter, %inputs) { |
| 437 | print $filter->($_, $inputs{$_}) foreach sort keys %inputs; |
| 438 | } |
| 439 | |
| 440 | A slurpy hash parameter may be nameless just like other kinds of |
| 441 | parameter. It still insists that the number of arguments available to |
| 442 | it be even, even though they're not being put into a variable. |
| 443 | |
| 444 | sub foo ($thing, %) { |
| 445 | print $thing; |
| 446 | } |
| 447 | |
| 448 | A slurpy parameter, either array or hash, must be the last thing in the |
| 449 | signature. It may follow mandatory and optional positional parameters; |
| 450 | it may also be the only thing in the signature. Slurpy parameters cannot |
| 451 | have default values: if no arguments are supplied for them then you get |
| 452 | an empty array or empty hash. |
| 453 | |
| 454 | A signature may be entirely empty, in which case all it does is check |
| 455 | that the caller passed no arguments: |
| 456 | |
| 457 | sub foo () { |
| 458 | return 123; |
| 459 | } |
| 460 | |
| 461 | When using a signature, the arguments are still available in the special |
| 462 | array variable C<@_>, in addition to the lexical variables of the |
| 463 | signature. There is a difference between the two ways of accessing the |
| 464 | arguments: C<@_> I<aliases> the arguments, but the signature variables |
| 465 | get I<copies> of the arguments. So writing to a signature variable |
| 466 | only changes that variable, and has no effect on the caller's variables, |
| 467 | but writing to an element of C<@_> modifies whatever the caller used to |
| 468 | supply that argument. |
| 469 | |
| 470 | There is a potential syntactic ambiguity between signatures and prototypes |
| 471 | (see L</Prototypes>), because both start with an opening parenthesis and |
| 472 | both can appear in some of the same places, such as just after the name |
| 473 | in a subroutine declaration. For historical reasons, when signatures |
| 474 | are not enabled, any opening parenthesis in such a context will trigger |
| 475 | very forgiving prototype parsing. Most signatures will be interpreted |
| 476 | as prototypes in those circumstances, but won't be valid prototypes. |
| 477 | (A valid prototype cannot contain any alphabetic character.) This will |
| 478 | lead to somewhat confusing error messages. |
| 479 | |
| 480 | To avoid ambiguity, when signatures are enabled the special syntax |
| 481 | for prototypes is disabled. There is no attempt to guess whether a |
| 482 | parenthesised group was intended to be a prototype or a signature. |
| 483 | To give a subroutine a prototype under these circumstances, use a |
| 484 | L<prototype attribute|attributes/Built-in Attributes>. For example, |
| 485 | |
| 486 | sub foo :prototype($) { $_[0] } |
| 487 | |
| 488 | It is entirely possible for a subroutine to have both a prototype and |
| 489 | a signature. They do different jobs: the prototype affects compilation |
| 490 | of calls to the subroutine, and the signature puts argument values into |
| 491 | lexical variables at runtime. You can therefore write |
| 492 | |
| 493 | sub foo ($left, $right) : prototype($$) { |
| 494 | return $left + $right; |
| 495 | } |
| 496 | |
| 497 | The prototype attribute, and any other attributes, come after |
| 498 | the signature. |
| 499 | |
| 500 | =head2 Private Variables via my() |
| 501 | X<my> X<variable, lexical> X<lexical> X<lexical variable> X<scope, lexical> |
| 502 | X<lexical scope> X<attributes, my> |
| 503 | |
| 504 | Synopsis: |
| 505 | |
| 506 | my $foo; # declare $foo lexically local |
| 507 | my (@wid, %get); # declare list of variables local |
| 508 | my $foo = "flurp"; # declare $foo lexical, and init it |
| 509 | my @oof = @bar; # declare @oof lexical, and init it |
| 510 | my $x : Foo = $y; # similar, with an attribute applied |
| 511 | |
| 512 | B<WARNING>: The use of attribute lists on C<my> declarations is still |
| 513 | evolving. The current semantics and interface are subject to change. |
| 514 | See L<attributes> and L<Attribute::Handlers>. |
| 515 | |
| 516 | The C<my> operator declares the listed variables to be lexically |
| 517 | confined to the enclosing block, conditional |
| 518 | (C<if>/C<unless>/C<elsif>/C<else>), loop |
| 519 | (C<for>/C<foreach>/C<while>/C<until>/C<continue>), subroutine, C<eval>, |
| 520 | or C<do>/C<require>/C<use>'d file. If more than one value is listed, the |
| 521 | list must be placed in parentheses. All listed elements must be |
| 522 | legal lvalues. Only alphanumeric identifiers may be lexically |
| 523 | scoped--magical built-ins like C<$/> must currently be C<local>ized |
| 524 | with C<local> instead. |
| 525 | |
| 526 | Unlike dynamic variables created by the C<local> operator, lexical |
| 527 | variables declared with C<my> are totally hidden from the outside |
| 528 | world, including any called subroutines. This is true if it's the |
| 529 | same subroutine called from itself or elsewhere--every call gets |
| 530 | its own copy. |
| 531 | X<local> |
| 532 | |
| 533 | This doesn't mean that a C<my> variable declared in a statically |
| 534 | enclosing lexical scope would be invisible. Only dynamic scopes |
| 535 | are cut off. For example, the C<bumpx()> function below has access |
| 536 | to the lexical $x variable because both the C<my> and the C<sub> |
| 537 | occurred at the same scope, presumably file scope. |
| 538 | |
| 539 | my $x = 10; |
| 540 | sub bumpx { $x++ } |
| 541 | |
| 542 | An C<eval()>, however, can see lexical variables of the scope it is |
| 543 | being evaluated in, so long as the names aren't hidden by declarations within |
| 544 | the C<eval()> itself. See L<perlref>. |
| 545 | X<eval, scope of> |
| 546 | |
| 547 | The parameter list to my() may be assigned to if desired, which allows you |
| 548 | to initialize your variables. (If no initializer is given for a |
| 549 | particular variable, it is created with the undefined value.) Commonly |
| 550 | this is used to name input parameters to a subroutine. Examples: |
| 551 | |
| 552 | $arg = "fred"; # "global" variable |
| 553 | $n = cube_root(27); |
| 554 | print "$arg thinks the root is $n\n"; |
| 555 | fred thinks the root is 3 |
| 556 | |
| 557 | sub cube_root { |
| 558 | my $arg = shift; # name doesn't matter |
| 559 | $arg **= 1/3; |
| 560 | return $arg; |
| 561 | } |
| 562 | |
| 563 | The C<my> is simply a modifier on something you might assign to. So when |
| 564 | you do assign to variables in its argument list, C<my> doesn't |
| 565 | change whether those variables are viewed as a scalar or an array. So |
| 566 | |
| 567 | my ($foo) = <STDIN>; # WRONG? |
| 568 | my @FOO = <STDIN>; |
| 569 | |
| 570 | both supply a list context to the right-hand side, while |
| 571 | |
| 572 | my $foo = <STDIN>; |
| 573 | |
| 574 | supplies a scalar context. But the following declares only one variable: |
| 575 | |
| 576 | my $foo, $bar = 1; # WRONG |
| 577 | |
| 578 | That has the same effect as |
| 579 | |
| 580 | my $foo; |
| 581 | $bar = 1; |
| 582 | |
| 583 | The declared variable is not introduced (is not visible) until after |
| 584 | the current statement. Thus, |
| 585 | |
| 586 | my $x = $x; |
| 587 | |
| 588 | can be used to initialize a new $x with the value of the old $x, and |
| 589 | the expression |
| 590 | |
| 591 | my $x = 123 and $x == 123 |
| 592 | |
| 593 | is false unless the old $x happened to have the value C<123>. |
| 594 | |
| 595 | Lexical scopes of control structures are not bounded precisely by the |
| 596 | braces that delimit their controlled blocks; control expressions are |
| 597 | part of that scope, too. Thus in the loop |
| 598 | |
| 599 | while (my $line = <>) { |
| 600 | $line = lc $line; |
| 601 | } continue { |
| 602 | print $line; |
| 603 | } |
| 604 | |
| 605 | the scope of $line extends from its declaration throughout the rest of |
| 606 | the loop construct (including the C<continue> clause), but not beyond |
| 607 | it. Similarly, in the conditional |
| 608 | |
| 609 | if ((my $answer = <STDIN>) =~ /^yes$/i) { |
| 610 | user_agrees(); |
| 611 | } elsif ($answer =~ /^no$/i) { |
| 612 | user_disagrees(); |
| 613 | } else { |
| 614 | chomp $answer; |
| 615 | die "'$answer' is neither 'yes' nor 'no'"; |
| 616 | } |
| 617 | |
| 618 | the scope of $answer extends from its declaration through the rest |
| 619 | of that conditional, including any C<elsif> and C<else> clauses, |
| 620 | but not beyond it. See L<perlsyn/"Simple Statements"> for information |
| 621 | on the scope of variables in statements with modifiers. |
| 622 | |
| 623 | The C<foreach> loop defaults to scoping its index variable dynamically |
| 624 | in the manner of C<local>. However, if the index variable is |
| 625 | prefixed with the keyword C<my>, or if there is already a lexical |
| 626 | by that name in scope, then a new lexical is created instead. Thus |
| 627 | in the loop |
| 628 | X<foreach> X<for> |
| 629 | |
| 630 | for my $i (1, 2, 3) { |
| 631 | some_function(); |
| 632 | } |
| 633 | |
| 634 | the scope of $i extends to the end of the loop, but not beyond it, |
| 635 | rendering the value of $i inaccessible within C<some_function()>. |
| 636 | X<foreach> X<for> |
| 637 | |
| 638 | Some users may wish to encourage the use of lexically scoped variables. |
| 639 | As an aid to catching implicit uses to package variables, |
| 640 | which are always global, if you say |
| 641 | |
| 642 | use strict 'vars'; |
| 643 | |
| 644 | then any variable mentioned from there to the end of the enclosing |
| 645 | block must either refer to a lexical variable, be predeclared via |
| 646 | C<our> or C<use vars>, or else must be fully qualified with the package name. |
| 647 | A compilation error results otherwise. An inner block may countermand |
| 648 | this with C<no strict 'vars'>. |
| 649 | |
| 650 | A C<my> has both a compile-time and a run-time effect. At compile |
| 651 | time, the compiler takes notice of it. The principal usefulness |
| 652 | of this is to quiet C<use strict 'vars'>, but it is also essential |
| 653 | for generation of closures as detailed in L<perlref>. Actual |
| 654 | initialization is delayed until run time, though, so it gets executed |
| 655 | at the appropriate time, such as each time through a loop, for |
| 656 | example. |
| 657 | |
| 658 | Variables declared with C<my> are not part of any package and are therefore |
| 659 | never fully qualified with the package name. In particular, you're not |
| 660 | allowed to try to make a package variable (or other global) lexical: |
| 661 | |
| 662 | my $pack::var; # ERROR! Illegal syntax |
| 663 | |
| 664 | In fact, a dynamic variable (also known as package or global variables) |
| 665 | are still accessible using the fully qualified C<::> notation even while a |
| 666 | lexical of the same name is also visible: |
| 667 | |
| 668 | package main; |
| 669 | local $x = 10; |
| 670 | my $x = 20; |
| 671 | print "$x and $::x\n"; |
| 672 | |
| 673 | That will print out C<20> and C<10>. |
| 674 | |
| 675 | You may declare C<my> variables at the outermost scope of a file |
| 676 | to hide any such identifiers from the world outside that file. This |
| 677 | is similar in spirit to C's static variables when they are used at |
| 678 | the file level. To do this with a subroutine requires the use of |
| 679 | a closure (an anonymous function that accesses enclosing lexicals). |
| 680 | If you want to create a private subroutine that cannot be called |
| 681 | from outside that block, it can declare a lexical variable containing |
| 682 | an anonymous sub reference: |
| 683 | |
| 684 | my $secret_version = '1.001-beta'; |
| 685 | my $secret_sub = sub { print $secret_version }; |
| 686 | &$secret_sub(); |
| 687 | |
| 688 | As long as the reference is never returned by any function within the |
| 689 | module, no outside module can see the subroutine, because its name is not in |
| 690 | any package's symbol table. Remember that it's not I<REALLY> called |
| 691 | C<$some_pack::secret_version> or anything; it's just $secret_version, |
| 692 | unqualified and unqualifiable. |
| 693 | |
| 694 | This does not work with object methods, however; all object methods |
| 695 | have to be in the symbol table of some package to be found. See |
| 696 | L<perlref/"Function Templates"> for something of a work-around to |
| 697 | this. |
| 698 | |
| 699 | =head2 Persistent Private Variables |
| 700 | X<state> X<state variable> X<static> X<variable, persistent> X<variable, static> X<closure> |
| 701 | |
| 702 | There are two ways to build persistent private variables in Perl 5.10. |
| 703 | First, you can simply use the C<state> feature. Or, you can use closures, |
| 704 | if you want to stay compatible with releases older than 5.10. |
| 705 | |
| 706 | =head3 Persistent variables via state() |
| 707 | |
| 708 | Beginning with Perl 5.10.0, you can declare variables with the C<state> |
| 709 | keyword in place of C<my>. For that to work, though, you must have |
| 710 | enabled that feature beforehand, either by using the C<feature> pragma, or |
| 711 | by using C<-E> on one-liners (see L<feature>). Beginning with Perl 5.16, |
| 712 | the C<CORE::state> form does not require the |
| 713 | C<feature> pragma. |
| 714 | |
| 715 | The C<state> keyword creates a lexical variable (following the same scoping |
| 716 | rules as C<my>) that persists from one subroutine call to the next. If a |
| 717 | state variable resides inside an anonymous subroutine, then each copy of |
| 718 | the subroutine has its own copy of the state variable. However, the value |
| 719 | of the state variable will still persist between calls to the same copy of |
| 720 | the anonymous subroutine. (Don't forget that C<sub { ... }> creates a new |
| 721 | subroutine each time it is executed.) |
| 722 | |
| 723 | For example, the following code maintains a private counter, incremented |
| 724 | each time the gimme_another() function is called: |
| 725 | |
| 726 | use feature 'state'; |
| 727 | sub gimme_another { state $x; return ++$x } |
| 728 | |
| 729 | And this example uses anonymous subroutines to create separate counters: |
| 730 | |
| 731 | use feature 'state'; |
| 732 | sub create_counter { |
| 733 | return sub { state $x; return ++$x } |
| 734 | } |
| 735 | |
| 736 | Also, since C<$x> is lexical, it can't be reached or modified by any Perl |
| 737 | code outside. |
| 738 | |
| 739 | When combined with variable declaration, simple scalar assignment to C<state> |
| 740 | variables (as in C<state $x = 42>) is executed only the first time. When such |
| 741 | statements are evaluated subsequent times, the assignment is ignored. The |
| 742 | behavior of this sort of assignment to non-scalar variables is undefined. |
| 743 | |
| 744 | =head3 Persistent variables with closures |
| 745 | |
| 746 | Just because a lexical variable is lexically (also called statically) |
| 747 | scoped to its enclosing block, C<eval>, or C<do> FILE, this doesn't mean that |
| 748 | within a function it works like a C static. It normally works more |
| 749 | like a C auto, but with implicit garbage collection. |
| 750 | |
| 751 | Unlike local variables in C or C++, Perl's lexical variables don't |
| 752 | necessarily get recycled just because their scope has exited. |
| 753 | If something more permanent is still aware of the lexical, it will |
| 754 | stick around. So long as something else references a lexical, that |
| 755 | lexical won't be freed--which is as it should be. You wouldn't want |
| 756 | memory being free until you were done using it, or kept around once you |
| 757 | were done. Automatic garbage collection takes care of this for you. |
| 758 | |
| 759 | This means that you can pass back or save away references to lexical |
| 760 | variables, whereas to return a pointer to a C auto is a grave error. |
| 761 | It also gives us a way to simulate C's function statics. Here's a |
| 762 | mechanism for giving a function private variables with both lexical |
| 763 | scoping and a static lifetime. If you do want to create something like |
| 764 | C's static variables, just enclose the whole function in an extra block, |
| 765 | and put the static variable outside the function but in the block. |
| 766 | |
| 767 | { |
| 768 | my $secret_val = 0; |
| 769 | sub gimme_another { |
| 770 | return ++$secret_val; |
| 771 | } |
| 772 | } |
| 773 | # $secret_val now becomes unreachable by the outside |
| 774 | # world, but retains its value between calls to gimme_another |
| 775 | |
| 776 | If this function is being sourced in from a separate file |
| 777 | via C<require> or C<use>, then this is probably just fine. If it's |
| 778 | all in the main program, you'll need to arrange for the C<my> |
| 779 | to be executed early, either by putting the whole block above |
| 780 | your main program, or more likely, placing merely a C<BEGIN> |
| 781 | code block around it to make sure it gets executed before your program |
| 782 | starts to run: |
| 783 | |
| 784 | BEGIN { |
| 785 | my $secret_val = 0; |
| 786 | sub gimme_another { |
| 787 | return ++$secret_val; |
| 788 | } |
| 789 | } |
| 790 | |
| 791 | See L<perlmod/"BEGIN, UNITCHECK, CHECK, INIT and END"> about the |
| 792 | special triggered code blocks, C<BEGIN>, C<UNITCHECK>, C<CHECK>, |
| 793 | C<INIT> and C<END>. |
| 794 | |
| 795 | If declared at the outermost scope (the file scope), then lexicals |
| 796 | work somewhat like C's file statics. They are available to all |
| 797 | functions in that same file declared below them, but are inaccessible |
| 798 | from outside that file. This strategy is sometimes used in modules |
| 799 | to create private variables that the whole module can see. |
| 800 | |
| 801 | =head2 Temporary Values via local() |
| 802 | X<local> X<scope, dynamic> X<dynamic scope> X<variable, local> |
| 803 | X<variable, temporary> |
| 804 | |
| 805 | B<WARNING>: In general, you should be using C<my> instead of C<local>, because |
| 806 | it's faster and safer. Exceptions to this include the global punctuation |
| 807 | variables, global filehandles and formats, and direct manipulation of the |
| 808 | Perl symbol table itself. C<local> is mostly used when the current value |
| 809 | of a variable must be visible to called subroutines. |
| 810 | |
| 811 | Synopsis: |
| 812 | |
| 813 | # localization of values |
| 814 | |
| 815 | local $foo; # make $foo dynamically local |
| 816 | local (@wid, %get); # make list of variables local |
| 817 | local $foo = "flurp"; # make $foo dynamic, and init it |
| 818 | local @oof = @bar; # make @oof dynamic, and init it |
| 819 | |
| 820 | local $hash{key} = "val"; # sets a local value for this hash entry |
| 821 | delete local $hash{key}; # delete this entry for the current block |
| 822 | local ($cond ? $v1 : $v2); # several types of lvalues support |
| 823 | # localization |
| 824 | |
| 825 | # localization of symbols |
| 826 | |
| 827 | local *FH; # localize $FH, @FH, %FH, &FH ... |
| 828 | local *merlyn = *randal; # now $merlyn is really $randal, plus |
| 829 | # @merlyn is really @randal, etc |
| 830 | local *merlyn = 'randal'; # SAME THING: promote 'randal' to *randal |
| 831 | local *merlyn = \$randal; # just alias $merlyn, not @merlyn etc |
| 832 | |
| 833 | A C<local> modifies its listed variables to be "local" to the |
| 834 | enclosing block, C<eval>, or C<do FILE>--and to I<any subroutine |
| 835 | called from within that block>. A C<local> just gives temporary |
| 836 | values to global (meaning package) variables. It does I<not> create |
| 837 | a local variable. This is known as dynamic scoping. Lexical scoping |
| 838 | is done with C<my>, which works more like C's auto declarations. |
| 839 | |
| 840 | Some types of lvalues can be localized as well: hash and array elements |
| 841 | and slices, conditionals (provided that their result is always |
| 842 | localizable), and symbolic references. As for simple variables, this |
| 843 | creates new, dynamically scoped values. |
| 844 | |
| 845 | If more than one variable or expression is given to C<local>, they must be |
| 846 | placed in parentheses. This operator works |
| 847 | by saving the current values of those variables in its argument list on a |
| 848 | hidden stack and restoring them upon exiting the block, subroutine, or |
| 849 | eval. This means that called subroutines can also reference the local |
| 850 | variable, but not the global one. The argument list may be assigned to if |
| 851 | desired, which allows you to initialize your local variables. (If no |
| 852 | initializer is given for a particular variable, it is created with an |
| 853 | undefined value.) |
| 854 | |
| 855 | Because C<local> is a run-time operator, it gets executed each time |
| 856 | through a loop. Consequently, it's more efficient to localize your |
| 857 | variables outside the loop. |
| 858 | |
| 859 | =head3 Grammatical note on local() |
| 860 | X<local, context> |
| 861 | |
| 862 | A C<local> is simply a modifier on an lvalue expression. When you assign to |
| 863 | a C<local>ized variable, the C<local> doesn't change whether its list is viewed |
| 864 | as a scalar or an array. So |
| 865 | |
| 866 | local($foo) = <STDIN>; |
| 867 | local @FOO = <STDIN>; |
| 868 | |
| 869 | both supply a list context to the right-hand side, while |
| 870 | |
| 871 | local $foo = <STDIN>; |
| 872 | |
| 873 | supplies a scalar context. |
| 874 | |
| 875 | =head3 Localization of special variables |
| 876 | X<local, special variable> |
| 877 | |
| 878 | If you localize a special variable, you'll be giving a new value to it, |
| 879 | but its magic won't go away. That means that all side-effects related |
| 880 | to this magic still work with the localized value. |
| 881 | |
| 882 | This feature allows code like this to work : |
| 883 | |
| 884 | # Read the whole contents of FILE in $slurp |
| 885 | { local $/ = undef; $slurp = <FILE>; } |
| 886 | |
| 887 | Note, however, that this restricts localization of some values ; for |
| 888 | example, the following statement dies, as of perl 5.10.0, with an error |
| 889 | I<Modification of a read-only value attempted>, because the $1 variable is |
| 890 | magical and read-only : |
| 891 | |
| 892 | local $1 = 2; |
| 893 | |
| 894 | One exception is the default scalar variable: starting with perl 5.14 |
| 895 | C<local($_)> will always strip all magic from $_, to make it possible |
| 896 | to safely reuse $_ in a subroutine. |
| 897 | |
| 898 | B<WARNING>: Localization of tied arrays and hashes does not currently |
| 899 | work as described. |
| 900 | This will be fixed in a future release of Perl; in the meantime, avoid |
| 901 | code that relies on any particular behavior of localising tied arrays |
| 902 | or hashes (localising individual elements is still okay). |
| 903 | See L<perl58delta/"Localising Tied Arrays and Hashes Is Broken"> for more |
| 904 | details. |
| 905 | X<local, tie> |
| 906 | |
| 907 | =head3 Localization of globs |
| 908 | X<local, glob> X<glob> |
| 909 | |
| 910 | The construct |
| 911 | |
| 912 | local *name; |
| 913 | |
| 914 | creates a whole new symbol table entry for the glob C<name> in the |
| 915 | current package. That means that all variables in its glob slot ($name, |
| 916 | @name, %name, &name, and the C<name> filehandle) are dynamically reset. |
| 917 | |
| 918 | This implies, among other things, that any magic eventually carried by |
| 919 | those variables is locally lost. In other words, saying C<local */> |
| 920 | will not have any effect on the internal value of the input record |
| 921 | separator. |
| 922 | |
| 923 | =head3 Localization of elements of composite types |
| 924 | X<local, composite type element> X<local, array element> X<local, hash element> |
| 925 | |
| 926 | It's also worth taking a moment to explain what happens when you |
| 927 | C<local>ize a member of a composite type (i.e. an array or hash element). |
| 928 | In this case, the element is C<local>ized I<by name>. This means that |
| 929 | when the scope of the C<local()> ends, the saved value will be |
| 930 | restored to the hash element whose key was named in the C<local()>, or |
| 931 | the array element whose index was named in the C<local()>. If that |
| 932 | element was deleted while the C<local()> was in effect (e.g. by a |
| 933 | C<delete()> from a hash or a C<shift()> of an array), it will spring |
| 934 | back into existence, possibly extending an array and filling in the |
| 935 | skipped elements with C<undef>. For instance, if you say |
| 936 | |
| 937 | %hash = ( 'This' => 'is', 'a' => 'test' ); |
| 938 | @ary = ( 0..5 ); |
| 939 | { |
| 940 | local($ary[5]) = 6; |
| 941 | local($hash{'a'}) = 'drill'; |
| 942 | while (my $e = pop(@ary)) { |
| 943 | print "$e . . .\n"; |
| 944 | last unless $e > 3; |
| 945 | } |
| 946 | if (@ary) { |
| 947 | $hash{'only a'} = 'test'; |
| 948 | delete $hash{'a'}; |
| 949 | } |
| 950 | } |
| 951 | print join(' ', map { "$_ $hash{$_}" } sort keys %hash),".\n"; |
| 952 | print "The array has ",scalar(@ary)," elements: ", |
| 953 | join(', ', map { defined $_ ? $_ : 'undef' } @ary),"\n"; |
| 954 | |
| 955 | Perl will print |
| 956 | |
| 957 | 6 . . . |
| 958 | 4 . . . |
| 959 | 3 . . . |
| 960 | This is a test only a test. |
| 961 | The array has 6 elements: 0, 1, 2, undef, undef, 5 |
| 962 | |
| 963 | The behavior of local() on non-existent members of composite |
| 964 | types is subject to change in future. |
| 965 | |
| 966 | =head3 Localized deletion of elements of composite types |
| 967 | X<delete> X<local, composite type element> X<local, array element> X<local, hash element> |
| 968 | |
| 969 | You can use the C<delete local $array[$idx]> and C<delete local $hash{key}> |
| 970 | constructs to delete a composite type entry for the current block and restore |
| 971 | it when it ends. They return the array/hash value before the localization, |
| 972 | which means that they are respectively equivalent to |
| 973 | |
| 974 | do { |
| 975 | my $val = $array[$idx]; |
| 976 | local $array[$idx]; |
| 977 | delete $array[$idx]; |
| 978 | $val |
| 979 | } |
| 980 | |
| 981 | and |
| 982 | |
| 983 | do { |
| 984 | my $val = $hash{key}; |
| 985 | local $hash{key}; |
| 986 | delete $hash{key}; |
| 987 | $val |
| 988 | } |
| 989 | |
| 990 | except that for those the C<local> is |
| 991 | scoped to the C<do> block. Slices are |
| 992 | also accepted. |
| 993 | |
| 994 | my %hash = ( |
| 995 | a => [ 7, 8, 9 ], |
| 996 | b => 1, |
| 997 | ) |
| 998 | |
| 999 | { |
| 1000 | my $a = delete local $hash{a}; |
| 1001 | # $a is [ 7, 8, 9 ] |
| 1002 | # %hash is (b => 1) |
| 1003 | |
| 1004 | { |
| 1005 | my @nums = delete local @$a[0, 2] |
| 1006 | # @nums is (7, 9) |
| 1007 | # $a is [ undef, 8 ] |
| 1008 | |
| 1009 | $a[0] = 999; # will be erased when the scope ends |
| 1010 | } |
| 1011 | # $a is back to [ 7, 8, 9 ] |
| 1012 | |
| 1013 | } |
| 1014 | # %hash is back to its original state |
| 1015 | |
| 1016 | =head2 Lvalue subroutines |
| 1017 | X<lvalue> X<subroutine, lvalue> |
| 1018 | |
| 1019 | It is possible to return a modifiable value from a subroutine. |
| 1020 | To do this, you have to declare the subroutine to return an lvalue. |
| 1021 | |
| 1022 | my $val; |
| 1023 | sub canmod : lvalue { |
| 1024 | $val; # or: return $val; |
| 1025 | } |
| 1026 | sub nomod { |
| 1027 | $val; |
| 1028 | } |
| 1029 | |
| 1030 | canmod() = 5; # assigns to $val |
| 1031 | nomod() = 5; # ERROR |
| 1032 | |
| 1033 | The scalar/list context for the subroutine and for the right-hand |
| 1034 | side of assignment is determined as if the subroutine call is replaced |
| 1035 | by a scalar. For example, consider: |
| 1036 | |
| 1037 | data(2,3) = get_data(3,4); |
| 1038 | |
| 1039 | Both subroutines here are called in a scalar context, while in: |
| 1040 | |
| 1041 | (data(2,3)) = get_data(3,4); |
| 1042 | |
| 1043 | and in: |
| 1044 | |
| 1045 | (data(2),data(3)) = get_data(3,4); |
| 1046 | |
| 1047 | all the subroutines are called in a list context. |
| 1048 | |
| 1049 | Lvalue subroutines are convenient, but you have to keep in mind that, |
| 1050 | when used with objects, they may violate encapsulation. A normal |
| 1051 | mutator can check the supplied argument before setting the attribute |
| 1052 | it is protecting, an lvalue subroutine cannot. If you require any |
| 1053 | special processing when storing and retrieving the values, consider |
| 1054 | using the CPAN module Sentinel or something similar. |
| 1055 | |
| 1056 | =head2 Lexical Subroutines |
| 1057 | X<my sub> X<state sub> X<our sub> X<subroutine, lexical> |
| 1058 | |
| 1059 | Beginning with Perl 5.18, you can declare a private subroutine with C<my> |
| 1060 | or C<state>. As with state variables, the C<state> keyword is only |
| 1061 | available under C<use feature 'state'> or C<use 5.010> or higher. |
| 1062 | |
| 1063 | Prior to Perl 5.26, lexical subroutines were deemed experimental and were |
| 1064 | available only under the C<use feature 'lexical_subs'> pragma. They also |
| 1065 | produced a warning unless the "experimental::lexical_subs" warnings |
| 1066 | category was disabled. |
| 1067 | |
| 1068 | These subroutines are only visible within the block in which they are |
| 1069 | declared, and only after that declaration: |
| 1070 | |
| 1071 | # Include these two lines if your code is intended to run under Perl |
| 1072 | # versions earlier than 5.26. |
| 1073 | no warnings "experimental::lexical_subs"; |
| 1074 | use feature 'lexical_subs'; |
| 1075 | |
| 1076 | foo(); # calls the package/global subroutine |
| 1077 | state sub foo { |
| 1078 | foo(); # also calls the package subroutine |
| 1079 | } |
| 1080 | foo(); # calls "state" sub |
| 1081 | my $ref = \&foo; # take a reference to "state" sub |
| 1082 | |
| 1083 | my sub bar { ... } |
| 1084 | bar(); # calls "my" sub |
| 1085 | |
| 1086 | To use a lexical subroutine from inside the subroutine itself, you must |
| 1087 | predeclare it. The C<sub foo {...}> subroutine definition syntax respects |
| 1088 | any previous C<my sub;> or C<state sub;> declaration. |
| 1089 | |
| 1090 | my sub baz; # predeclaration |
| 1091 | sub baz { # define the "my" sub |
| 1092 | baz(); # recursive call |
| 1093 | } |
| 1094 | |
| 1095 | =head3 C<state sub> vs C<my sub> |
| 1096 | |
| 1097 | What is the difference between "state" subs and "my" subs? Each time that |
| 1098 | execution enters a block when "my" subs are declared, a new copy of each |
| 1099 | sub is created. "State" subroutines persist from one execution of the |
| 1100 | containing block to the next. |
| 1101 | |
| 1102 | So, in general, "state" subroutines are faster. But "my" subs are |
| 1103 | necessary if you want to create closures: |
| 1104 | |
| 1105 | sub whatever { |
| 1106 | my $x = shift; |
| 1107 | my sub inner { |
| 1108 | ... do something with $x ... |
| 1109 | } |
| 1110 | inner(); |
| 1111 | } |
| 1112 | |
| 1113 | In this example, a new C<$x> is created when C<whatever> is called, and |
| 1114 | also a new C<inner>, which can see the new C<$x>. A "state" sub will only |
| 1115 | see the C<$x> from the first call to C<whatever>. |
| 1116 | |
| 1117 | =head3 C<our> subroutines |
| 1118 | |
| 1119 | Like C<our $variable>, C<our sub> creates a lexical alias to the package |
| 1120 | subroutine of the same name. |
| 1121 | |
| 1122 | The two main uses for this are to switch back to using the package sub |
| 1123 | inside an inner scope: |
| 1124 | |
| 1125 | sub foo { ... } |
| 1126 | |
| 1127 | sub bar { |
| 1128 | my sub foo { ... } |
| 1129 | { |
| 1130 | # need to use the outer foo here |
| 1131 | our sub foo; |
| 1132 | foo(); |
| 1133 | } |
| 1134 | } |
| 1135 | |
| 1136 | and to make a subroutine visible to other packages in the same scope: |
| 1137 | |
| 1138 | package MySneakyModule; |
| 1139 | |
| 1140 | our sub do_something { ... } |
| 1141 | |
| 1142 | sub do_something_with_caller { |
| 1143 | package DB; |
| 1144 | () = caller 1; # sets @DB::args |
| 1145 | do_something(@args); # uses MySneakyModule::do_something |
| 1146 | } |
| 1147 | |
| 1148 | =head2 Passing Symbol Table Entries (typeglobs) |
| 1149 | X<typeglob> X<*> |
| 1150 | |
| 1151 | B<WARNING>: The mechanism described in this section was originally |
| 1152 | the only way to simulate pass-by-reference in older versions of |
| 1153 | Perl. While it still works fine in modern versions, the new reference |
| 1154 | mechanism is generally easier to work with. See below. |
| 1155 | |
| 1156 | Sometimes you don't want to pass the value of an array to a subroutine |
| 1157 | but rather the name of it, so that the subroutine can modify the global |
| 1158 | copy of it rather than working with a local copy. In perl you can |
| 1159 | refer to all objects of a particular name by prefixing the name |
| 1160 | with a star: C<*foo>. This is often known as a "typeglob", because the |
| 1161 | star on the front can be thought of as a wildcard match for all the |
| 1162 | funny prefix characters on variables and subroutines and such. |
| 1163 | |
| 1164 | When evaluated, the typeglob produces a scalar value that represents |
| 1165 | all the objects of that name, including any filehandle, format, or |
| 1166 | subroutine. When assigned to, it causes the name mentioned to refer to |
| 1167 | whatever C<*> value was assigned to it. Example: |
| 1168 | |
| 1169 | sub doubleary { |
| 1170 | local(*someary) = @_; |
| 1171 | foreach $elem (@someary) { |
| 1172 | $elem *= 2; |
| 1173 | } |
| 1174 | } |
| 1175 | doubleary(*foo); |
| 1176 | doubleary(*bar); |
| 1177 | |
| 1178 | Scalars are already passed by reference, so you can modify |
| 1179 | scalar arguments without using this mechanism by referring explicitly |
| 1180 | to C<$_[0]> etc. You can modify all the elements of an array by passing |
| 1181 | all the elements as scalars, but you have to use the C<*> mechanism (or |
| 1182 | the equivalent reference mechanism) to C<push>, C<pop>, or change the size of |
| 1183 | an array. It will certainly be faster to pass the typeglob (or reference). |
| 1184 | |
| 1185 | Even if you don't want to modify an array, this mechanism is useful for |
| 1186 | passing multiple arrays in a single LIST, because normally the LIST |
| 1187 | mechanism will merge all the array values so that you can't extract out |
| 1188 | the individual arrays. For more on typeglobs, see |
| 1189 | L<perldata/"Typeglobs and Filehandles">. |
| 1190 | |
| 1191 | =head2 When to Still Use local() |
| 1192 | X<local> X<variable, local> |
| 1193 | |
| 1194 | Despite the existence of C<my>, there are still three places where the |
| 1195 | C<local> operator still shines. In fact, in these three places, you |
| 1196 | I<must> use C<local> instead of C<my>. |
| 1197 | |
| 1198 | =over 4 |
| 1199 | |
| 1200 | =item 1. |
| 1201 | |
| 1202 | You need to give a global variable a temporary value, especially $_. |
| 1203 | |
| 1204 | The global variables, like C<@ARGV> or the punctuation variables, must be |
| 1205 | C<local>ized with C<local()>. This block reads in F</etc/motd>, and splits |
| 1206 | it up into chunks separated by lines of equal signs, which are placed |
| 1207 | in C<@Fields>. |
| 1208 | |
| 1209 | { |
| 1210 | local @ARGV = ("/etc/motd"); |
| 1211 | local $/ = undef; |
| 1212 | local $_ = <>; |
| 1213 | @Fields = split /^\s*=+\s*$/; |
| 1214 | } |
| 1215 | |
| 1216 | It particular, it's important to C<local>ize $_ in any routine that assigns |
| 1217 | to it. Look out for implicit assignments in C<while> conditionals. |
| 1218 | |
| 1219 | =item 2. |
| 1220 | |
| 1221 | You need to create a local file or directory handle or a local function. |
| 1222 | |
| 1223 | A function that needs a filehandle of its own must use |
| 1224 | C<local()> on a complete typeglob. This can be used to create new symbol |
| 1225 | table entries: |
| 1226 | |
| 1227 | sub ioqueue { |
| 1228 | local (*READER, *WRITER); # not my! |
| 1229 | pipe (READER, WRITER) or die "pipe: $!"; |
| 1230 | return (*READER, *WRITER); |
| 1231 | } |
| 1232 | ($head, $tail) = ioqueue(); |
| 1233 | |
| 1234 | See the Symbol module for a way to create anonymous symbol table |
| 1235 | entries. |
| 1236 | |
| 1237 | Because assignment of a reference to a typeglob creates an alias, this |
| 1238 | can be used to create what is effectively a local function, or at least, |
| 1239 | a local alias. |
| 1240 | |
| 1241 | { |
| 1242 | local *grow = \&shrink; # only until this block exits |
| 1243 | grow(); # really calls shrink() |
| 1244 | move(); # if move() grow()s, it shrink()s too |
| 1245 | } |
| 1246 | grow(); # get the real grow() again |
| 1247 | |
| 1248 | See L<perlref/"Function Templates"> for more about manipulating |
| 1249 | functions by name in this way. |
| 1250 | |
| 1251 | =item 3. |
| 1252 | |
| 1253 | You want to temporarily change just one element of an array or hash. |
| 1254 | |
| 1255 | You can C<local>ize just one element of an aggregate. Usually this |
| 1256 | is done on dynamics: |
| 1257 | |
| 1258 | { |
| 1259 | local $SIG{INT} = 'IGNORE'; |
| 1260 | funct(); # uninterruptible |
| 1261 | } |
| 1262 | # interruptibility automatically restored here |
| 1263 | |
| 1264 | But it also works on lexically declared aggregates. |
| 1265 | |
| 1266 | =back |
| 1267 | |
| 1268 | =head2 Pass by Reference |
| 1269 | X<pass by reference> X<pass-by-reference> X<reference> |
| 1270 | |
| 1271 | If you want to pass more than one array or hash into a function--or |
| 1272 | return them from it--and have them maintain their integrity, then |
| 1273 | you're going to have to use an explicit pass-by-reference. Before you |
| 1274 | do that, you need to understand references as detailed in L<perlref>. |
| 1275 | This section may not make much sense to you otherwise. |
| 1276 | |
| 1277 | Here are a few simple examples. First, let's pass in several arrays |
| 1278 | to a function and have it C<pop> all of then, returning a new list |
| 1279 | of all their former last elements: |
| 1280 | |
| 1281 | @tailings = popmany ( \@a, \@b, \@c, \@d ); |
| 1282 | |
| 1283 | sub popmany { |
| 1284 | my $aref; |
| 1285 | my @retlist; |
| 1286 | foreach $aref ( @_ ) { |
| 1287 | push @retlist, pop @$aref; |
| 1288 | } |
| 1289 | return @retlist; |
| 1290 | } |
| 1291 | |
| 1292 | Here's how you might write a function that returns a |
| 1293 | list of keys occurring in all the hashes passed to it: |
| 1294 | |
| 1295 | @common = inter( \%foo, \%bar, \%joe ); |
| 1296 | sub inter { |
| 1297 | my ($k, $href, %seen); # locals |
| 1298 | foreach $href (@_) { |
| 1299 | while ( $k = each %$href ) { |
| 1300 | $seen{$k}++; |
| 1301 | } |
| 1302 | } |
| 1303 | return grep { $seen{$_} == @_ } keys %seen; |
| 1304 | } |
| 1305 | |
| 1306 | So far, we're using just the normal list return mechanism. |
| 1307 | What happens if you want to pass or return a hash? Well, |
| 1308 | if you're using only one of them, or you don't mind them |
| 1309 | concatenating, then the normal calling convention is ok, although |
| 1310 | a little expensive. |
| 1311 | |
| 1312 | Where people get into trouble is here: |
| 1313 | |
| 1314 | (@a, @b) = func(@c, @d); |
| 1315 | or |
| 1316 | (%a, %b) = func(%c, %d); |
| 1317 | |
| 1318 | That syntax simply won't work. It sets just C<@a> or C<%a> and |
| 1319 | clears the C<@b> or C<%b>. Plus the function didn't get passed |
| 1320 | into two separate arrays or hashes: it got one long list in C<@_>, |
| 1321 | as always. |
| 1322 | |
| 1323 | If you can arrange for everyone to deal with this through references, it's |
| 1324 | cleaner code, although not so nice to look at. Here's a function that |
| 1325 | takes two array references as arguments, returning the two array elements |
| 1326 | in order of how many elements they have in them: |
| 1327 | |
| 1328 | ($aref, $bref) = func(\@c, \@d); |
| 1329 | print "@$aref has more than @$bref\n"; |
| 1330 | sub func { |
| 1331 | my ($cref, $dref) = @_; |
| 1332 | if (@$cref > @$dref) { |
| 1333 | return ($cref, $dref); |
| 1334 | } else { |
| 1335 | return ($dref, $cref); |
| 1336 | } |
| 1337 | } |
| 1338 | |
| 1339 | It turns out that you can actually do this also: |
| 1340 | |
| 1341 | (*a, *b) = func(\@c, \@d); |
| 1342 | print "@a has more than @b\n"; |
| 1343 | sub func { |
| 1344 | local (*c, *d) = @_; |
| 1345 | if (@c > @d) { |
| 1346 | return (\@c, \@d); |
| 1347 | } else { |
| 1348 | return (\@d, \@c); |
| 1349 | } |
| 1350 | } |
| 1351 | |
| 1352 | Here we're using the typeglobs to do symbol table aliasing. It's |
| 1353 | a tad subtle, though, and also won't work if you're using C<my> |
| 1354 | variables, because only globals (even in disguise as C<local>s) |
| 1355 | are in the symbol table. |
| 1356 | |
| 1357 | If you're passing around filehandles, you could usually just use the bare |
| 1358 | typeglob, like C<*STDOUT>, but typeglobs references work, too. |
| 1359 | For example: |
| 1360 | |
| 1361 | splutter(\*STDOUT); |
| 1362 | sub splutter { |
| 1363 | my $fh = shift; |
| 1364 | print $fh "her um well a hmmm\n"; |
| 1365 | } |
| 1366 | |
| 1367 | $rec = get_rec(\*STDIN); |
| 1368 | sub get_rec { |
| 1369 | my $fh = shift; |
| 1370 | return scalar <$fh>; |
| 1371 | } |
| 1372 | |
| 1373 | If you're planning on generating new filehandles, you could do this. |
| 1374 | Notice to pass back just the bare *FH, not its reference. |
| 1375 | |
| 1376 | sub openit { |
| 1377 | my $path = shift; |
| 1378 | local *FH; |
| 1379 | return open (FH, $path) ? *FH : undef; |
| 1380 | } |
| 1381 | |
| 1382 | =head2 Prototypes |
| 1383 | X<prototype> X<subroutine, prototype> |
| 1384 | |
| 1385 | Perl supports a very limited kind of compile-time argument checking |
| 1386 | using function prototyping. This can be declared in either the PROTO |
| 1387 | section or with a L<prototype attribute|attributes/Built-in Attributes>. |
| 1388 | If you declare either of |
| 1389 | |
| 1390 | sub mypush (\@@) |
| 1391 | sub mypush :prototype(\@@) |
| 1392 | |
| 1393 | then C<mypush()> takes arguments exactly like C<push()> does. |
| 1394 | |
| 1395 | If subroutine signatures are enabled (see L</Signatures>), then |
| 1396 | the shorter PROTO syntax is unavailable, because it would clash with |
| 1397 | signatures. In that case, a prototype can only be declared in the form |
| 1398 | of an attribute. |
| 1399 | |
| 1400 | The |
| 1401 | function declaration must be visible at compile time. The prototype |
| 1402 | affects only interpretation of new-style calls to the function, |
| 1403 | where new-style is defined as not using the C<&> character. In |
| 1404 | other words, if you call it like a built-in function, then it behaves |
| 1405 | like a built-in function. If you call it like an old-fashioned |
| 1406 | subroutine, then it behaves like an old-fashioned subroutine. It |
| 1407 | naturally falls out from this rule that prototypes have no influence |
| 1408 | on subroutine references like C<\&foo> or on indirect subroutine |
| 1409 | calls like C<&{$subref}> or C<< $subref->() >>. |
| 1410 | |
| 1411 | Method calls are not influenced by prototypes either, because the |
| 1412 | function to be called is indeterminate at compile time, since |
| 1413 | the exact code called depends on inheritance. |
| 1414 | |
| 1415 | Because the intent of this feature is primarily to let you define |
| 1416 | subroutines that work like built-in functions, here are prototypes |
| 1417 | for some other functions that parse almost exactly like the |
| 1418 | corresponding built-in. |
| 1419 | |
| 1420 | Declared as Called as |
| 1421 | |
| 1422 | sub mylink ($$) mylink $old, $new |
| 1423 | sub myvec ($$$) myvec $var, $offset, 1 |
| 1424 | sub myindex ($$;$) myindex &getstring, "substr" |
| 1425 | sub mysyswrite ($$$;$) mysyswrite $buf, 0, length($buf) - $off, $off |
| 1426 | sub myreverse (@) myreverse $a, $b, $c |
| 1427 | sub myjoin ($@) myjoin ":", $a, $b, $c |
| 1428 | sub mypop (\@) mypop @array |
| 1429 | sub mysplice (\@$$@) mysplice @array, 0, 2, @pushme |
| 1430 | sub mykeys (\[%@]) mykeys %{$hashref} |
| 1431 | sub myopen (*;$) myopen HANDLE, $name |
| 1432 | sub mypipe (**) mypipe READHANDLE, WRITEHANDLE |
| 1433 | sub mygrep (&@) mygrep { /foo/ } $a, $b, $c |
| 1434 | sub myrand (;$) myrand 42 |
| 1435 | sub mytime () mytime |
| 1436 | |
| 1437 | Any backslashed prototype character represents an actual argument |
| 1438 | that must start with that character (optionally preceded by C<my>, |
| 1439 | C<our> or C<local>), with the exception of C<$>, which will |
| 1440 | accept any scalar lvalue expression, such as C<$foo = 7> or |
| 1441 | C<< my_function()->[0] >>. The value passed as part of C<@_> will be a |
| 1442 | reference to the actual argument given in the subroutine call, |
| 1443 | obtained by applying C<\> to that argument. |
| 1444 | |
| 1445 | You can use the C<\[]> backslash group notation to specify more than one |
| 1446 | allowed argument type. For example: |
| 1447 | |
| 1448 | sub myref (\[$@%&*]) |
| 1449 | |
| 1450 | will allow calling myref() as |
| 1451 | |
| 1452 | myref $var |
| 1453 | myref @array |
| 1454 | myref %hash |
| 1455 | myref &sub |
| 1456 | myref *glob |
| 1457 | |
| 1458 | and the first argument of myref() will be a reference to |
| 1459 | a scalar, an array, a hash, a code, or a glob. |
| 1460 | |
| 1461 | Unbackslashed prototype characters have special meanings. Any |
| 1462 | unbackslashed C<@> or C<%> eats all remaining arguments, and forces |
| 1463 | list context. An argument represented by C<$> forces scalar context. An |
| 1464 | C<&> requires an anonymous subroutine, which, if passed as the first |
| 1465 | argument, does not require the C<sub> keyword or a subsequent comma. |
| 1466 | |
| 1467 | A C<*> allows the subroutine to accept a bareword, constant, scalar expression, |
| 1468 | typeglob, or a reference to a typeglob in that slot. The value will be |
| 1469 | available to the subroutine either as a simple scalar, or (in the latter |
| 1470 | two cases) as a reference to the typeglob. If you wish to always convert |
| 1471 | such arguments to a typeglob reference, use Symbol::qualify_to_ref() as |
| 1472 | follows: |
| 1473 | |
| 1474 | use Symbol 'qualify_to_ref'; |
| 1475 | |
| 1476 | sub foo (*) { |
| 1477 | my $fh = qualify_to_ref(shift, caller); |
| 1478 | ... |
| 1479 | } |
| 1480 | |
| 1481 | The C<+> prototype is a special alternative to C<$> that will act like |
| 1482 | C<\[@%]> when given a literal array or hash variable, but will otherwise |
| 1483 | force scalar context on the argument. This is useful for functions which |
| 1484 | should accept either a literal array or an array reference as the argument: |
| 1485 | |
| 1486 | sub mypush (+@) { |
| 1487 | my $aref = shift; |
| 1488 | die "Not an array or arrayref" unless ref $aref eq 'ARRAY'; |
| 1489 | push @$aref, @_; |
| 1490 | } |
| 1491 | |
| 1492 | When using the C<+> prototype, your function must check that the argument |
| 1493 | is of an acceptable type. |
| 1494 | |
| 1495 | A semicolon (C<;>) separates mandatory arguments from optional arguments. |
| 1496 | It is redundant before C<@> or C<%>, which gobble up everything else. |
| 1497 | |
| 1498 | As the last character of a prototype, or just before a semicolon, a C<@> |
| 1499 | or a C<%>, you can use C<_> in place of C<$>: if this argument is not |
| 1500 | provided, C<$_> will be used instead. |
| 1501 | |
| 1502 | Note how the last three examples in the table above are treated |
| 1503 | specially by the parser. C<mygrep()> is parsed as a true list |
| 1504 | operator, C<myrand()> is parsed as a true unary operator with unary |
| 1505 | precedence the same as C<rand()>, and C<mytime()> is truly without |
| 1506 | arguments, just like C<time()>. That is, if you say |
| 1507 | |
| 1508 | mytime +2; |
| 1509 | |
| 1510 | you'll get C<mytime() + 2>, not C<mytime(2)>, which is how it would be parsed |
| 1511 | without a prototype. If you want to force a unary function to have the |
| 1512 | same precedence as a list operator, add C<;> to the end of the prototype: |
| 1513 | |
| 1514 | sub mygetprotobynumber($;); |
| 1515 | mygetprotobynumber $a > $b; # parsed as mygetprotobynumber($a > $b) |
| 1516 | |
| 1517 | The interesting thing about C<&> is that you can generate new syntax with it, |
| 1518 | provided it's in the initial position: |
| 1519 | X<&> |
| 1520 | |
| 1521 | sub try (&@) { |
| 1522 | my($try,$catch) = @_; |
| 1523 | eval { &$try }; |
| 1524 | if ($@) { |
| 1525 | local $_ = $@; |
| 1526 | &$catch; |
| 1527 | } |
| 1528 | } |
| 1529 | sub catch (&) { $_[0] } |
| 1530 | |
| 1531 | try { |
| 1532 | die "phooey"; |
| 1533 | } catch { |
| 1534 | /phooey/ and print "unphooey\n"; |
| 1535 | }; |
| 1536 | |
| 1537 | That prints C<"unphooey">. (Yes, there are still unresolved |
| 1538 | issues having to do with visibility of C<@_>. I'm ignoring that |
| 1539 | question for the moment. (But note that if we make C<@_> lexically |
| 1540 | scoped, those anonymous subroutines can act like closures... (Gee, |
| 1541 | is this sounding a little Lispish? (Never mind.)))) |
| 1542 | |
| 1543 | And here's a reimplementation of the Perl C<grep> operator: |
| 1544 | X<grep> |
| 1545 | |
| 1546 | sub mygrep (&@) { |
| 1547 | my $code = shift; |
| 1548 | my @result; |
| 1549 | foreach $_ (@_) { |
| 1550 | push(@result, $_) if &$code; |
| 1551 | } |
| 1552 | @result; |
| 1553 | } |
| 1554 | |
| 1555 | Some folks would prefer full alphanumeric prototypes. Alphanumerics have |
| 1556 | been intentionally left out of prototypes for the express purpose of |
| 1557 | someday in the future adding named, formal parameters. The current |
| 1558 | mechanism's main goal is to let module writers provide better diagnostics |
| 1559 | for module users. Larry feels the notation quite understandable to Perl |
| 1560 | programmers, and that it will not intrude greatly upon the meat of the |
| 1561 | module, nor make it harder to read. The line noise is visually |
| 1562 | encapsulated into a small pill that's easy to swallow. |
| 1563 | |
| 1564 | If you try to use an alphanumeric sequence in a prototype you will |
| 1565 | generate an optional warning - "Illegal character in prototype...". |
| 1566 | Unfortunately earlier versions of Perl allowed the prototype to be |
| 1567 | used as long as its prefix was a valid prototype. The warning may be |
| 1568 | upgraded to a fatal error in a future version of Perl once the |
| 1569 | majority of offending code is fixed. |
| 1570 | |
| 1571 | It's probably best to prototype new functions, not retrofit prototyping |
| 1572 | into older ones. That's because you must be especially careful about |
| 1573 | silent impositions of differing list versus scalar contexts. For example, |
| 1574 | if you decide that a function should take just one parameter, like this: |
| 1575 | |
| 1576 | sub func ($) { |
| 1577 | my $n = shift; |
| 1578 | print "you gave me $n\n"; |
| 1579 | } |
| 1580 | |
| 1581 | and someone has been calling it with an array or expression |
| 1582 | returning a list: |
| 1583 | |
| 1584 | func(@foo); |
| 1585 | func( split /:/ ); |
| 1586 | |
| 1587 | Then you've just supplied an automatic C<scalar> in front of their |
| 1588 | argument, which can be more than a bit surprising. The old C<@foo> |
| 1589 | which used to hold one thing doesn't get passed in. Instead, |
| 1590 | C<func()> now gets passed in a C<1>; that is, the number of elements |
| 1591 | in C<@foo>. And the C<split> gets called in scalar context so it |
| 1592 | starts scribbling on your C<@_> parameter list. Ouch! |
| 1593 | |
| 1594 | If a sub has both a PROTO and a BLOCK, the prototype is not applied |
| 1595 | until after the BLOCK is completely defined. This means that a recursive |
| 1596 | function with a prototype has to be predeclared for the prototype to take |
| 1597 | effect, like so: |
| 1598 | |
| 1599 | sub foo($$); |
| 1600 | sub foo($$) { |
| 1601 | foo 1, 2; |
| 1602 | } |
| 1603 | |
| 1604 | This is all very powerful, of course, and should be used only in moderation |
| 1605 | to make the world a better place. |
| 1606 | |
| 1607 | =head2 Constant Functions |
| 1608 | X<constant> |
| 1609 | |
| 1610 | Functions with a prototype of C<()> are potential candidates for |
| 1611 | inlining. If the result after optimization and constant folding |
| 1612 | is either a constant or a lexically-scoped scalar which has no other |
| 1613 | references, then it will be used in place of function calls made |
| 1614 | without C<&>. Calls made using C<&> are never inlined. (See |
| 1615 | F<constant.pm> for an easy way to declare most constants.) |
| 1616 | |
| 1617 | The following functions would all be inlined: |
| 1618 | |
| 1619 | sub pi () { 3.14159 } # Not exact, but close. |
| 1620 | sub PI () { 4 * atan2 1, 1 } # As good as it gets, |
| 1621 | # and it's inlined, too! |
| 1622 | sub ST_DEV () { 0 } |
| 1623 | sub ST_INO () { 1 } |
| 1624 | |
| 1625 | sub FLAG_FOO () { 1 << 8 } |
| 1626 | sub FLAG_BAR () { 1 << 9 } |
| 1627 | sub FLAG_MASK () { FLAG_FOO | FLAG_BAR } |
| 1628 | |
| 1629 | sub OPT_BAZ () { not (0x1B58 & FLAG_MASK) } |
| 1630 | |
| 1631 | sub N () { int(OPT_BAZ) / 3 } |
| 1632 | |
| 1633 | sub FOO_SET () { 1 if FLAG_MASK & FLAG_FOO } |
| 1634 | sub FOO_SET2 () { if (FLAG_MASK & FLAG_FOO) { 1 } } |
| 1635 | |
| 1636 | (Be aware that the last example was not always inlined in Perl 5.20 and |
| 1637 | earlier, which did not behave consistently with subroutines containing |
| 1638 | inner scopes.) You can countermand inlining by using an explicit |
| 1639 | C<return>: |
| 1640 | |
| 1641 | sub baz_val () { |
| 1642 | if (OPT_BAZ) { |
| 1643 | return 23; |
| 1644 | } |
| 1645 | else { |
| 1646 | return 42; |
| 1647 | } |
| 1648 | } |
| 1649 | sub bonk_val () { return 12345 } |
| 1650 | |
| 1651 | As alluded to earlier you can also declare inlined subs dynamically at |
| 1652 | BEGIN time if their body consists of a lexically-scoped scalar which |
| 1653 | has no other references. Only the first example here will be inlined: |
| 1654 | |
| 1655 | BEGIN { |
| 1656 | my $var = 1; |
| 1657 | no strict 'refs'; |
| 1658 | *INLINED = sub () { $var }; |
| 1659 | } |
| 1660 | |
| 1661 | BEGIN { |
| 1662 | my $var = 1; |
| 1663 | my $ref = \$var; |
| 1664 | no strict 'refs'; |
| 1665 | *NOT_INLINED = sub () { $var }; |
| 1666 | } |
| 1667 | |
| 1668 | A not so obvious caveat with this (see [RT #79908]) is that the |
| 1669 | variable will be immediately inlined, and will stop behaving like a |
| 1670 | normal lexical variable, e.g. this will print C<79907>, not C<79908>: |
| 1671 | |
| 1672 | BEGIN { |
| 1673 | my $x = 79907; |
| 1674 | *RT_79908 = sub () { $x }; |
| 1675 | $x++; |
| 1676 | } |
| 1677 | print RT_79908(); # prints 79907 |
| 1678 | |
| 1679 | As of Perl 5.22, this buggy behavior, while preserved for backward |
| 1680 | compatibility, is detected and emits a deprecation warning. If you want |
| 1681 | the subroutine to be inlined (with no warning), make sure the variable is |
| 1682 | not used in a context where it could be modified aside from where it is |
| 1683 | declared. |
| 1684 | |
| 1685 | # Fine, no warning |
| 1686 | BEGIN { |
| 1687 | my $x = 54321; |
| 1688 | *INLINED = sub () { $x }; |
| 1689 | } |
| 1690 | # Warns. Future Perl versions will stop inlining it. |
| 1691 | BEGIN { |
| 1692 | my $x; |
| 1693 | $x = 54321; |
| 1694 | *ALSO_INLINED = sub () { $x }; |
| 1695 | } |
| 1696 | |
| 1697 | Perl 5.22 also introduces the experimental "const" attribute as an |
| 1698 | alternative. (Disable the "experimental::const_attr" warnings if you want |
| 1699 | to use it.) When applied to an anonymous subroutine, it forces the sub to |
| 1700 | be called when the C<sub> expression is evaluated. The return value is |
| 1701 | captured and turned into a constant subroutine: |
| 1702 | |
| 1703 | my $x = 54321; |
| 1704 | *INLINED = sub : const { $x }; |
| 1705 | $x++; |
| 1706 | |
| 1707 | The return value of C<INLINED> in this example will always be 54321, |
| 1708 | regardless of later modifications to $x. You can also put any arbitrary |
| 1709 | code inside the sub, at it will be executed immediately and its return |
| 1710 | value captured the same way. |
| 1711 | |
| 1712 | If you really want a subroutine with a C<()> prototype that returns a |
| 1713 | lexical variable you can easily force it to not be inlined by adding |
| 1714 | an explicit C<return>: |
| 1715 | |
| 1716 | BEGIN { |
| 1717 | my $x = 79907; |
| 1718 | *RT_79908 = sub () { return $x }; |
| 1719 | $x++; |
| 1720 | } |
| 1721 | print RT_79908(); # prints 79908 |
| 1722 | |
| 1723 | The easiest way to tell if a subroutine was inlined is by using |
| 1724 | L<B::Deparse>. Consider this example of two subroutines returning |
| 1725 | C<1>, one with a C<()> prototype causing it to be inlined, and one |
| 1726 | without (with deparse output truncated for clarity): |
| 1727 | |
| 1728 | $ perl -MO=Deparse -le 'sub ONE { 1 } if (ONE) { print ONE if ONE }' |
| 1729 | sub ONE { |
| 1730 | 1; |
| 1731 | } |
| 1732 | if (ONE ) { |
| 1733 | print ONE() if ONE ; |
| 1734 | } |
| 1735 | $ perl -MO=Deparse -le 'sub ONE () { 1 } if (ONE) { print ONE if ONE }' |
| 1736 | sub ONE () { 1 } |
| 1737 | do { |
| 1738 | print 1 |
| 1739 | }; |
| 1740 | |
| 1741 | If you redefine a subroutine that was eligible for inlining, you'll |
| 1742 | get a warning by default. You can use this warning to tell whether or |
| 1743 | not a particular subroutine is considered inlinable, since it's |
| 1744 | different than the warning for overriding non-inlined subroutines: |
| 1745 | |
| 1746 | $ perl -e 'sub one () {1} sub one () {2}' |
| 1747 | Constant subroutine one redefined at -e line 1. |
| 1748 | $ perl -we 'sub one {1} sub one {2}' |
| 1749 | Subroutine one redefined at -e line 1. |
| 1750 | |
| 1751 | The warning is considered severe enough not to be affected by the |
| 1752 | B<-w> switch (or its absence) because previously compiled invocations |
| 1753 | of the function will still be using the old value of the function. If |
| 1754 | you need to be able to redefine the subroutine, you need to ensure |
| 1755 | that it isn't inlined, either by dropping the C<()> prototype (which |
| 1756 | changes calling semantics, so beware) or by thwarting the inlining |
| 1757 | mechanism in some other way, e.g. by adding an explicit C<return>, as |
| 1758 | mentioned above: |
| 1759 | |
| 1760 | sub not_inlined () { return 23 } |
| 1761 | |
| 1762 | =head2 Overriding Built-in Functions |
| 1763 | X<built-in> X<override> X<CORE> X<CORE::GLOBAL> |
| 1764 | |
| 1765 | Many built-in functions may be overridden, though this should be tried |
| 1766 | only occasionally and for good reason. Typically this might be |
| 1767 | done by a package attempting to emulate missing built-in functionality |
| 1768 | on a non-Unix system. |
| 1769 | |
| 1770 | Overriding may be done only by importing the name from a module at |
| 1771 | compile time--ordinary predeclaration isn't good enough. However, the |
| 1772 | C<use subs> pragma lets you, in effect, predeclare subs |
| 1773 | via the import syntax, and these names may then override built-in ones: |
| 1774 | |
| 1775 | use subs 'chdir', 'chroot', 'chmod', 'chown'; |
| 1776 | chdir $somewhere; |
| 1777 | sub chdir { ... } |
| 1778 | |
| 1779 | To unambiguously refer to the built-in form, precede the |
| 1780 | built-in name with the special package qualifier C<CORE::>. For example, |
| 1781 | saying C<CORE::open()> always refers to the built-in C<open()>, even |
| 1782 | if the current package has imported some other subroutine called |
| 1783 | C<&open()> from elsewhere. Even though it looks like a regular |
| 1784 | function call, it isn't: the CORE:: prefix in that case is part of Perl's |
| 1785 | syntax, and works for any keyword, regardless of what is in the CORE |
| 1786 | package. Taking a reference to it, that is, C<\&CORE::open>, only works |
| 1787 | for some keywords. See L<CORE>. |
| 1788 | |
| 1789 | Library modules should not in general export built-in names like C<open> |
| 1790 | or C<chdir> as part of their default C<@EXPORT> list, because these may |
| 1791 | sneak into someone else's namespace and change the semantics unexpectedly. |
| 1792 | Instead, if the module adds that name to C<@EXPORT_OK>, then it's |
| 1793 | possible for a user to import the name explicitly, but not implicitly. |
| 1794 | That is, they could say |
| 1795 | |
| 1796 | use Module 'open'; |
| 1797 | |
| 1798 | and it would import the C<open> override. But if they said |
| 1799 | |
| 1800 | use Module; |
| 1801 | |
| 1802 | they would get the default imports without overrides. |
| 1803 | |
| 1804 | The foregoing mechanism for overriding built-in is restricted, quite |
| 1805 | deliberately, to the package that requests the import. There is a second |
| 1806 | method that is sometimes applicable when you wish to override a built-in |
| 1807 | everywhere, without regard to namespace boundaries. This is achieved by |
| 1808 | importing a sub into the special namespace C<CORE::GLOBAL::>. Here is an |
| 1809 | example that quite brazenly replaces the C<glob> operator with something |
| 1810 | that understands regular expressions. |
| 1811 | |
| 1812 | package REGlob; |
| 1813 | require Exporter; |
| 1814 | @ISA = 'Exporter'; |
| 1815 | @EXPORT_OK = 'glob'; |
| 1816 | |
| 1817 | sub import { |
| 1818 | my $pkg = shift; |
| 1819 | return unless @_; |
| 1820 | my $sym = shift; |
| 1821 | my $where = ($sym =~ s/^GLOBAL_// ? 'CORE::GLOBAL' : caller(0)); |
| 1822 | $pkg->export($where, $sym, @_); |
| 1823 | } |
| 1824 | |
| 1825 | sub glob { |
| 1826 | my $pat = shift; |
| 1827 | my @got; |
| 1828 | if (opendir my $d, '.') { |
| 1829 | @got = grep /$pat/, readdir $d; |
| 1830 | closedir $d; |
| 1831 | } |
| 1832 | return @got; |
| 1833 | } |
| 1834 | 1; |
| 1835 | |
| 1836 | And here's how it could be (ab)used: |
| 1837 | |
| 1838 | #use REGlob 'GLOBAL_glob'; # override glob() in ALL namespaces |
| 1839 | package Foo; |
| 1840 | use REGlob 'glob'; # override glob() in Foo:: only |
| 1841 | print for <^[a-z_]+\.pm\$>; # show all pragmatic modules |
| 1842 | |
| 1843 | The initial comment shows a contrived, even dangerous example. |
| 1844 | By overriding C<glob> globally, you would be forcing the new (and |
| 1845 | subversive) behavior for the C<glob> operator for I<every> namespace, |
| 1846 | without the complete cognizance or cooperation of the modules that own |
| 1847 | those namespaces. Naturally, this should be done with extreme caution--if |
| 1848 | it must be done at all. |
| 1849 | |
| 1850 | The C<REGlob> example above does not implement all the support needed to |
| 1851 | cleanly override perl's C<glob> operator. The built-in C<glob> has |
| 1852 | different behaviors depending on whether it appears in a scalar or list |
| 1853 | context, but our C<REGlob> doesn't. Indeed, many perl built-in have such |
| 1854 | context sensitive behaviors, and these must be adequately supported by |
| 1855 | a properly written override. For a fully functional example of overriding |
| 1856 | C<glob>, study the implementation of C<File::DosGlob> in the standard |
| 1857 | library. |
| 1858 | |
| 1859 | When you override a built-in, your replacement should be consistent (if |
| 1860 | possible) with the built-in native syntax. You can achieve this by using |
| 1861 | a suitable prototype. To get the prototype of an overridable built-in, |
| 1862 | use the C<prototype> function with an argument of C<"CORE::builtin_name"> |
| 1863 | (see L<perlfunc/prototype>). |
| 1864 | |
| 1865 | Note however that some built-ins can't have their syntax expressed by a |
| 1866 | prototype (such as C<system> or C<chomp>). If you override them you won't |
| 1867 | be able to fully mimic their original syntax. |
| 1868 | |
| 1869 | The built-ins C<do>, C<require> and C<glob> can also be overridden, but due |
| 1870 | to special magic, their original syntax is preserved, and you don't have |
| 1871 | to define a prototype for their replacements. (You can't override the |
| 1872 | C<do BLOCK> syntax, though). |
| 1873 | |
| 1874 | C<require> has special additional dark magic: if you invoke your |
| 1875 | C<require> replacement as C<require Foo::Bar>, it will actually receive |
| 1876 | the argument C<"Foo/Bar.pm"> in @_. See L<perlfunc/require>. |
| 1877 | |
| 1878 | And, as you'll have noticed from the previous example, if you override |
| 1879 | C<glob>, the C<< <*> >> glob operator is overridden as well. |
| 1880 | |
| 1881 | In a similar fashion, overriding the C<readline> function also overrides |
| 1882 | the equivalent I/O operator C<< <FILEHANDLE> >>. Also, overriding |
| 1883 | C<readpipe> also overrides the operators C<``> and C<qx//>. |
| 1884 | |
| 1885 | Finally, some built-ins (e.g. C<exists> or C<grep>) can't be overridden. |
| 1886 | |
| 1887 | =head2 Autoloading |
| 1888 | X<autoloading> X<AUTOLOAD> |
| 1889 | |
| 1890 | If you call a subroutine that is undefined, you would ordinarily |
| 1891 | get an immediate, fatal error complaining that the subroutine doesn't |
| 1892 | exist. (Likewise for subroutines being used as methods, when the |
| 1893 | method doesn't exist in any base class of the class's package.) |
| 1894 | However, if an C<AUTOLOAD> subroutine is defined in the package or |
| 1895 | packages used to locate the original subroutine, then that |
| 1896 | C<AUTOLOAD> subroutine is called with the arguments that would have |
| 1897 | been passed to the original subroutine. The fully qualified name |
| 1898 | of the original subroutine magically appears in the global $AUTOLOAD |
| 1899 | variable of the same package as the C<AUTOLOAD> routine. The name |
| 1900 | is not passed as an ordinary argument because, er, well, just |
| 1901 | because, that's why. (As an exception, a method call to a nonexistent |
| 1902 | C<import> or C<unimport> method is just skipped instead. Also, if |
| 1903 | the AUTOLOAD subroutine is an XSUB, there are other ways to retrieve the |
| 1904 | subroutine name. See L<perlguts/Autoloading with XSUBs> for details.) |
| 1905 | |
| 1906 | |
| 1907 | Many C<AUTOLOAD> routines load in a definition for the requested |
| 1908 | subroutine using eval(), then execute that subroutine using a special |
| 1909 | form of goto() that erases the stack frame of the C<AUTOLOAD> routine |
| 1910 | without a trace. (See the source to the standard module documented |
| 1911 | in L<AutoLoader>, for example.) But an C<AUTOLOAD> routine can |
| 1912 | also just emulate the routine and never define it. For example, |
| 1913 | let's pretend that a function that wasn't defined should just invoke |
| 1914 | C<system> with those arguments. All you'd do is: |
| 1915 | |
| 1916 | sub AUTOLOAD { |
| 1917 | my $program = $AUTOLOAD; |
| 1918 | $program =~ s/.*:://; |
| 1919 | system($program, @_); |
| 1920 | } |
| 1921 | date(); |
| 1922 | who('am', 'i'); |
| 1923 | ls('-l'); |
| 1924 | |
| 1925 | In fact, if you predeclare functions you want to call that way, you don't |
| 1926 | even need parentheses: |
| 1927 | |
| 1928 | use subs qw(date who ls); |
| 1929 | date; |
| 1930 | who "am", "i"; |
| 1931 | ls '-l'; |
| 1932 | |
| 1933 | A more complete example of this is the Shell module on CPAN, which |
| 1934 | can treat undefined subroutine calls as calls to external programs. |
| 1935 | |
| 1936 | Mechanisms are available to help modules writers split their modules |
| 1937 | into autoloadable files. See the standard AutoLoader module |
| 1938 | described in L<AutoLoader> and in L<AutoSplit>, the standard |
| 1939 | SelfLoader modules in L<SelfLoader>, and the document on adding C |
| 1940 | functions to Perl code in L<perlxs>. |
| 1941 | |
| 1942 | =head2 Subroutine Attributes |
| 1943 | X<attribute> X<subroutine, attribute> X<attrs> |
| 1944 | |
| 1945 | A subroutine declaration or definition may have a list of attributes |
| 1946 | associated with it. If such an attribute list is present, it is |
| 1947 | broken up at space or colon boundaries and treated as though a |
| 1948 | C<use attributes> had been seen. See L<attributes> for details |
| 1949 | about what attributes are currently supported. |
| 1950 | Unlike the limitation with the obsolescent C<use attrs>, the |
| 1951 | C<sub : ATTRLIST> syntax works to associate the attributes with |
| 1952 | a pre-declaration, and not just with a subroutine definition. |
| 1953 | |
| 1954 | The attributes must be valid as simple identifier names (without any |
| 1955 | punctuation other than the '_' character). They may have a parameter |
| 1956 | list appended, which is only checked for whether its parentheses ('(',')') |
| 1957 | nest properly. |
| 1958 | |
| 1959 | Examples of valid syntax (even though the attributes are unknown): |
| 1960 | |
| 1961 | sub fnord (&\%) : switch(10,foo(7,3)) : expensive; |
| 1962 | sub plugh () : Ugly('\(") :Bad; |
| 1963 | sub xyzzy : _5x5 { ... } |
| 1964 | |
| 1965 | Examples of invalid syntax: |
| 1966 | |
| 1967 | sub fnord : switch(10,foo(); # ()-string not balanced |
| 1968 | sub snoid : Ugly('('); # ()-string not balanced |
| 1969 | sub xyzzy : 5x5; # "5x5" not a valid identifier |
| 1970 | sub plugh : Y2::north; # "Y2::north" not a simple identifier |
| 1971 | sub snurt : foo + bar; # "+" not a colon or space |
| 1972 | |
| 1973 | The attribute list is passed as a list of constant strings to the code |
| 1974 | which associates them with the subroutine. In particular, the second example |
| 1975 | of valid syntax above currently looks like this in terms of how it's |
| 1976 | parsed and invoked: |
| 1977 | |
| 1978 | use attributes __PACKAGE__, \&plugh, q[Ugly('\(")], 'Bad'; |
| 1979 | |
| 1980 | For further details on attribute lists and their manipulation, |
| 1981 | see L<attributes> and L<Attribute::Handlers>. |
| 1982 | |
| 1983 | =head1 SEE ALSO |
| 1984 | |
| 1985 | See L<perlref/"Function Templates"> for more about references and closures. |
| 1986 | See L<perlxs> if you'd like to learn about calling C subroutines from Perl. |
| 1987 | See L<perlembed> if you'd like to learn about calling Perl subroutines from C. |
| 1988 | See L<perlmod> to learn about bundling up your functions in separate files. |
| 1989 | See L<perlmodlib> to learn what library modules come standard on your system. |
| 1990 | See L<perlootut> to learn how to make object method calls. |