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