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