X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/bc92d8c04127b7dfc16c456beb86f6b7d195458b..2b32d74cef00e0bba7871a1c7dc3f66b07049e2c:/pod/perlsub.pod diff --git a/pod/perlsub.pod b/pod/perlsub.pod index 7933dc2..325c823 100644 --- a/pod/perlsub.pod +++ b/pod/perlsub.pod @@ -1,10 +1,12 @@ =head1 NAME +X X perlsub - Perl subroutines =head1 SYNOPSIS To declare subroutines: +X X sub NAME; # A "forward" declaration. sub NAME(PROTO); # ditto, but with prototypes @@ -17,6 +19,7 @@ To declare subroutines: sub NAME(PROTO) : ATTRS BLOCK # with prototypes and attributes To define an anonymous subroutine at runtime: +X $subref = sub BLOCK; # no proto $subref = sub (PROTO) BLOCK; # with proto @@ -24,10 +27,12 @@ To define an anonymous subroutine at runtime: $subref = sub (PROTO) : ATTRS BLOCK; # with proto and attributes To import subroutines: +X use MODULE qw(NAME1 NAME2 NAME3); To call subroutines: +X X NAME(LIST); # & is optional with parentheses. NAME LIST; # Parentheses optional if predeclared/imported. @@ -52,6 +57,7 @@ pass-by-reference instead to avoid this. Both call and return lists may contain as many or as few scalar elements as you'd like. (Often a function without an explicit return statement is called a subroutine, but there's really no difference from Perl's perspective.) +X X Any arguments passed in show up in the array C<@_>. Therefore, if you called a function with two arguments, those would be stored in @@ -65,16 +71,22 @@ or a reference to it is taken. (Some earlier versions of Perl created the element whether or not the element was assigned to.) Assigning to the whole array C<@_> removes that aliasing, and does not update any arguments. - -The return value of a subroutine is the value of the last expression -evaluated. More explicitly, a C statement may be used to exit the -subroutine, optionally specifying the returned value, which will be -evaluated in the appropriate context (list, scalar, or void) depending -on the context of the subroutine call. If you specify no return value, -the subroutine returns an empty list in list context, the undefined -value in scalar context, or nothing in void context. If you return -one or more aggregates (arrays and hashes), these will be flattened -together into one large indistinguishable list. +X X X<@_> + +A C statement may be used to exit a subroutine, optionally +specifying the returned value, which will be evaluated in the +appropriate context (list, scalar, or void) depending on the context of +the subroutine call. If you specify no return value, the subroutine +returns an empty list in list context, the undefined value in scalar +context, or nothing in void context. If you return one or more +aggregates (arrays and hashes), these will be flattened together into +one large indistinguishable list. + +If no C is found and if the last statement is an expression, its +value is returned. If the last statement is a loop control structure +like a C or a C, the returned value is unspecified. The +empty sub returns the empty list. +X X X Perl does not have named formal parameters. In practice all you do is assign to a C list of these. Variables that aren't @@ -83,6 +95,7 @@ on creating private variables, see L<"Private Variables via my()"> and L<"Temporary Values via local()">. To create protected environments for a set of functions in a separate package (and probably a separate file), see L. +X X Example: @@ -129,6 +142,7 @@ Because the assignment copies the values, this also has the effect of turning call-by-reference into call-by-value. Otherwise a function is free to do in-place modifications of C<@_> and change its caller's values. +X X upcase_in($v1, $v2); # this changes $v1 and $v2 sub upcase_in { @@ -138,6 +152,7 @@ its caller's values. You aren't allowed to modify constants in this way, of course. If an argument were actually literal and you tried to change it, you'd take a (presumably fatal) exception. For example, this won't work: +X X upcase_in("frederick"); @@ -169,7 +184,7 @@ Do not, however, be tempted to do this: Like the flattened incoming parameter list, the return list is also flattened on return. So all you have managed to do here is stored -everything in C<@a> and made C<@b> an empty list. See +everything in C<@a> and made C<@b> empty. See L for alternatives. A subroutine may be called using an explicit C<&> prefix. The @@ -181,12 +196,14 @@ want to do an indirect subroutine call with a subroutine name or reference using the C<&$subref()> or C<&{$subref}()> constructs, although the C<< $subref->() >> notation solves that problem. See L for more about all that. +X<&> Subroutines may be called recursively. If a subroutine is called using the C<&> form, the argument list is optional, and if omitted, no C<@_> array is set up for the subroutine: the C<@_> array at the time of the call is visible to subroutine instead. This is an efficiency mechanism that new users may wish to avoid. +X &foo(1,2,3); # pass three arguments foo(1,2,3); # the same @@ -201,16 +218,23 @@ Not only does the C<&> form make the argument list optional, it also disables any prototype checking on arguments you do provide. This is partly for historical reasons, and partly for having a convenient way to cheat if you know what you're doing. See L below. +X<&> + +Subroutines whose names are in all upper case are reserved to the Perl +core, as are modules whose names are in all lower case. A subroutine in +all capitals is a loosely-held convention meaning it will be called +indirectly by the run-time system itself, usually due to a triggered event. +Subroutines that do special, pre-defined things include C, C, +C plus all functions mentioned in L and L. -Functions whose names are in all upper case are reserved to the Perl -core, as are modules whose names are in all lower case. A -function in all capitals is a loosely-held convention meaning it -will be called indirectly by the run-time system itself, usually -due to a triggered event. Functions that do special, pre-defined -things include C, C, C, C, C, -C and C--plus all functions mentioned in L. +The C, C, C, C and C subroutines +are not so much subroutines as named special code blocks, of which you +can have more than one in a package, and which you can B call +explicitly. See L =head2 Private Variables via my() +X X X X X +X X Synopsis: @@ -220,9 +244,9 @@ Synopsis: my @oof = @bar; # declare @oof lexical, and init it my $x : Foo = $y; # similar, with an attribute applied -B: The use of attribute lists on C declarations is -experimental. This feature should not be relied upon. It may -change or disappear in future releases of Perl. See L. +B: The use of attribute lists on C declarations is still +evolving. The current semantics and interface are subject to change. +See L and L. The C operator declares the listed variables to be lexically confined to the enclosing block, conditional (C), @@ -230,7 +254,7 @@ loop (C), subroutine, C, or C'd file. If more than one value is listed, the list must be placed in parentheses. All listed elements must be legal lvalues. Only alphanumeric identifiers may be lexically -scoped--magical built-ins like C<$/> must currently be Cize +scoped--magical built-ins like C<$/> must currently be Cized with C instead. Unlike dynamic variables created by the C operator, lexical @@ -238,6 +262,7 @@ variables declared with C are totally hidden from the outside world, including any called subroutines. This is true if it's the same subroutine called from itself or elsewhere--every call gets its own copy. +X This doesn't mean that a C variable declared in a statically enclosing lexical scope would be invisible. Only dynamic scopes @@ -251,6 +276,7 @@ occurred at the same scope, presumably file scope. An C, however, can see lexical variables of the scope it is being evaluated in, so long as the names aren't hidden by declarations within the C itself. See L. +X The parameter list to my() may be assigned to if desired, which allows you to initialize your variables. (If no initializer is given for a @@ -325,20 +351,15 @@ it. Similarly, in the conditional the scope of $answer extends from its declaration through the rest of that conditional, including any C and C clauses, -but not beyond it. - -B The behaviour of a C statement modified with a statement -modifier conditional or loop construct (e.g. C) is -B. The value of the C variable may be C, any -previously assigned value, or possibly anything else. Don't rely on -it. Future versions of perl might do something different from the -version of perl you try it out on. Here be dragons. +but not beyond it. See L for information +on the scope of variables in statements with modifiers. The C loop defaults to scoping its index variable dynamically in the manner of C. However, if the index variable is prefixed with the keyword C, or if there is already a lexical by that name in scope, then a new lexical is created instead. Thus in the loop +X X for my $i (1, 2, 3) { some_function(); @@ -346,6 +367,7 @@ in the loop the scope of $i extends to the end of the loop, but not beyond it, rendering the value of $i inaccessible within C. +X X Some users may wish to encourage the use of lexically scoped variables. As an aid to catching implicit uses to package variables, @@ -372,7 +394,6 @@ never fully qualified with the package name. In particular, you're not allowed to try to make a package variable (or other global) lexical: my $pack::var; # ERROR! Illegal syntax - my $_; # also illegal (currently) In fact, a dynamic variable (also known as package or global variables) are still accessible using the fully qualified C<::> notation even while a @@ -410,6 +431,34 @@ L for something of a work-around to this. =head2 Persistent Private Variables +X X X X X X + +There are two ways to build persistent private variables in Perl 5.10. +First, you can simply use the C feature. Or, you can use closures, +if you want to stay compatible with releases older than 5.10. + +=head3 Persistent variables via state() + +Beginning with perl 5.9.4, you can declare variables with the C +keyword in place of C. For that to work, though, you must have +enabled that feature beforehand, either by using the C pragma, or +by using C<-E> on one-liners. (see L) + +For example, the following code maintains a private counter, incremented +each time the gimme_another() function is called: + + use feature 'state'; + sub gimme_another { state $x; return ++$x } + +Also, since C<$x> is lexical, it can't be reached or modified by any Perl +code outside. + +When combined with variable declaration, simple scalar assignment to C +variables (as in C) is executed only the first time. When such +statements are evaluated subsequent times, the assignment is ignored. The +behavior of this sort of assignment to non-scalar variables is undefined. + +=head3 Persistent variables with closures Just because a lexical variable is lexically (also called statically) scoped to its enclosing block, C, or C FILE, this doesn't mean that @@ -446,18 +495,19 @@ via C or C, then this is probably just fine. If it's all in the main program, you'll need to arrange for the C to be executed early, either by putting the whole block above your main program, or more likely, placing merely a C -sub around it to make sure it gets executed before your program +code block around it to make sure it gets executed before your program starts to run: - sub BEGIN { + BEGIN { my $secret_val = 0; sub gimme_another { return ++$secret_val; } } -See L about the -special triggered functions, C, C, C and C. +See L about the +special triggered code blocks, C, C, C, +C and C. If declared at the outermost scope (the file scope), then lexicals work somewhat like C's file statics. They are available to all @@ -466,20 +516,30 @@ from outside that file. This strategy is sometimes used in modules to create private variables that the whole module can see. =head2 Temporary Values via local() +X X X X +X B: In general, you should be using C instead of C, because it's faster and safer. Exceptions to this include the global punctuation -variables, filehandles and formats, and direct manipulation of the Perl -symbol table itself. Format variables often use C though, as do -other variables whose current value must be visible to called -subroutines. +variables, global filehandles and formats, and direct manipulation of the +Perl symbol table itself. C is mostly used when the current value +of a variable must be visible to called subroutines. Synopsis: - local $foo; # declare $foo dynamically local - local (@wid, %get); # declare list of variables local - local $foo = "flurp"; # declare $foo dynamic, and init it - local @oof = @bar; # declare @oof dynamic, and init it + # localization of values + + local $foo; # make $foo dynamically local + local (@wid, %get); # make list of variables local + local $foo = "flurp"; # make $foo dynamic, and init it + local @oof = @bar; # make @oof dynamic, and init it + + local $hash{key} = "val"; # sets a local value for this hash entry + delete local $hash{key}; # delete this entry for the current block + local ($cond ? $v1 : $v2); # several types of lvalues support + # localization + + # localization of symbols local *FH; # localize $FH, @FH, %FH, &FH ... local *merlyn = *randal; # now $merlyn is really $randal, plus @@ -494,36 +554,27 @@ values to global (meaning package) variables. It does I create a local variable. This is known as dynamic scoping. Lexical scoping is done with C, which works more like C's auto declarations. -If more than one variable is given to C, they must be placed in -parentheses. All listed elements must be legal lvalues. This operator works +Some types of lvalues can be localized as well : hash and array elements +and slices, conditionals (provided that their result is always +localizable), and symbolic references. As for simple variables, this +creates new, dynamically scoped values. + +If more than one variable or expression is given to C, they must be +placed in parentheses. This operator works by saving the current values of those variables in its argument list on a hidden stack and restoring them upon exiting the block, subroutine, or eval. This means that called subroutines can also reference the local variable, but not the global one. The argument list may be assigned to if desired, which allows you to initialize your local variables. (If no initializer is given for a particular variable, it is created with an -undefined value.) Commonly this is used to name the parameters to a -subroutine. Examples: - - for $i ( 0 .. 9 ) { - $digits{$i} = $i; - } - # assume this function uses global %digits hash - parse_num(); - - # now temporarily add to %digits hash - if ($base12) { - # (NOTE: not claiming this is efficient!) - local %digits = (%digits, 't' => 10, 'e' => 11); - parse_num(); # parse_num gets this new %digits! - } - # old %digits restored here +undefined value.) Because C is a run-time operator, it gets executed each time -through a loop. In releases of Perl previous to 5.0, this used more stack -storage each time until the loop was exited. Perl now reclaims the space -each time through, but it's still more efficient to declare your variables -outside the loop. +through a loop. Consequently, it's more efficient to localize your +variables outside the loop. + +=head3 Grammatical note on local() +X A C is simply a modifier on an lvalue expression. When you assign to a Cized variable, the C doesn't change whether its list is viewed @@ -538,40 +589,69 @@ both supply a list context to the right-hand side, while supplies a scalar context. -A note about C and composite types is in order. Something -like C works by temporarily placing a brand new hash in -the symbol table. The old hash is left alone, but is hidden "behind" -the new one. +=head3 Localization of special variables +X -This means the old variable is completely invisible via the symbol -table (i.e. the hash entry in the C<*foo> typeglob) for the duration -of the dynamic scope within which the C was seen. This -has the effect of allowing one to temporarily occlude any magic on -composite types. For instance, this will briefly alter a tied -hash to some other implementation: +If you localize a special variable, you'll be giving a new value to it, +but its magic won't go away. That means that all side-effects related +to this magic still work with the localized value. - tie %ahash, 'APackage'; - [...] - { - local %ahash; - tie %ahash, 'BPackage'; - [..called code will see %ahash tied to 'BPackage'..] - { - local %ahash; - [..%ahash is a normal (untied) hash here..] - } - } - [..%ahash back to its initial tied self again..] +This feature allows code like this to work : -As another example, a custom implementation of C<%ENV> might look -like this: + # Read the whole contents of FILE in $slurp + { local $/ = undef; $slurp = ; } - { - local %ENV; - tie %ENV, 'MyOwnEnv'; - [..do your own fancy %ENV manipulation here..] +Note, however, that this restricts localization of some values ; for +example, the following statement dies, as of perl 5.9.0, with an error +I, because the $1 variable is +magical and read-only : + + local $1 = 2; + +Similarly, but in a way more difficult to spot, the following snippet will +die in perl 5.9.0 : + + sub f { local $_ = "foo"; print } + for ($1) { + # now $_ is aliased to $1, thus is magic and readonly + f(); } - [..normal %ENV behavior here..] + +See next section for an alternative to this situation. + +B: Localization of tied arrays and hashes does not currently +work as described. +This will be fixed in a future release of Perl; in the meantime, avoid +code that relies on any particular behaviour of localising tied arrays +or hashes (localising individual elements is still okay). +See L for more +details. +X + +=head3 Localization of globs +X X + +The construct + + local *name; + +creates a whole new symbol table entry for the glob C in the +current package. That means that all variables in its glob slot ($name, +@name, %name, &name, and the C filehandle) are dynamically reset. + +This implies, among other things, that any magic eventually carried by +those variables is locally lost. In other words, saying C +will not have any effect on the internal value of the input record +separator. + +Notably, if you want to work with a brand new value of the default scalar +$_, and avoid the potential problem listed above about $_ previously +carrying a magic value, you should use C instead of C. +As of perl 5.9.1, you can also use the lexical form of C<$_> (declaring it +with C), which avoids completely this problem. + +=head3 Localization of elements of composite types +X X X It's also worth taking a moment to explain what happens when you Cize a member of a composite type (i.e. an array or hash element). @@ -613,16 +693,67 @@ Perl will print The behavior of local() on non-existent members of composite types is subject to change in future. +=head3 Localized deletion of elements of composite types +X X X X + +You can use the C and C +constructs to delete a composite type entry for the current block and restore +it when it ends. They return the array/hash value before the localization, +which means that they are respectively equivalent to + + do { + my $val = $array[$idx]; + local $array[$idx]; + delete $array[$idx]; + $val + } + +and + + do { + my $val = $hash{key}; + local $hash{key}; + delete $hash{key}; + $val + } + +except that for those the C is scoped to the C block. Slices are +also accepted. + + my %hash = ( + a => [ 7, 8, 9 ], + b => 1, + ) + + { + my $a = delete local $hash{a}; + # $a is [ 7, 8, 9 ] + # %hash is (b => 1) + + { + my @nums = delete local @$a[0, 2] + # @nums is (7, 9) + # $a is [ undef, 8 ] + + $a[0] = 999; # will be erased when the scope ends + } + # $a is back to [ 7, 8, 9 ] + + } + # %hash is back to its original state + =head2 Lvalue subroutines +X X -B: Lvalue subroutines are still experimental and the implementation -may change in future versions of Perl. +B: Lvalue subroutines are still experimental and the +implementation may change in future versions of Perl. It is possible to return a modifiable value from a subroutine. To do this, you have to declare the subroutine to return an lvalue. my $val; sub canmod : lvalue { + # return $val; this doesn't work, don't say "return" $val; } sub nomod { @@ -648,7 +779,41 @@ and in: all the subroutines are called in a list context. +=over 4 + +=item Lvalue subroutines are EXPERIMENTAL + +They appear to be convenient, but there are several reasons to be +circumspect. + +You can't use the return keyword, you must pass out the value before +falling out of subroutine scope. (see comment in example above). This +is usually not a problem, but it disallows an explicit return out of a +deeply nested loop, which is sometimes a nice way out. + +They violate encapsulation. A normal mutator can check the supplied +argument before setting the attribute it is protecting, an lvalue +subroutine never gets that chance. Consider; + + my $some_array_ref = []; # protected by mutators ?? + + sub set_arr { # normal mutator + my $val = shift; + die("expected array, you supplied ", ref $val) + unless ref $val eq 'ARRAY'; + $some_array_ref = $val; + } + sub set_arr_lv : lvalue { # lvalue mutator + $some_array_ref; + } + + # set_arr_lv cannot stop this ! + set_arr_lv() = { a => 1 }; + +=back + =head2 Passing Symbol Table Entries (typeglobs) +X X<*> B: The mechanism described in this section was originally the only way to simulate pass-by-reference in older versions of @@ -691,6 +856,7 @@ the individual arrays. For more on typeglobs, see L. =head2 When to Still Use local() +X X Despite the existence of C, there are still three places where the C operator still shines. In fact, in these three places, you @@ -727,7 +893,7 @@ table entries: sub ioqueue { local (*READER, *WRITER); # not my! - pipe (READER, WRITER); or die "pipe: $!"; + pipe (READER, WRITER) or die "pipe: $!"; return (*READER, *WRITER); } ($head, $tail) = ioqueue(); @@ -768,6 +934,7 @@ this operation could on occasion misbehave. =back =head2 Pass by Reference +X X X If you want to pass more than one array or hash into a function--or return them from it--and have them maintain their integrity, then @@ -881,6 +1048,7 @@ Notice to pass back just the bare *FH, not its reference. } =head2 Prototypes +X X Perl supports a very limited kind of compile-time argument checking using function prototyping. If you declare @@ -916,12 +1084,12 @@ corresponding built-in. sub myreverse (@) myreverse $a, $b, $c sub myjoin ($@) myjoin ":", $a, $b, $c sub mypop (\@) mypop @array - sub mysplice (\@$$@) mysplice @array, @array, 0, @pushme + sub mysplice (\@$$@) mysplice @array, 0, 2, @pushme sub mykeys (\%) mykeys %{$hashref} sub myopen (*;$) myopen HANDLE, $name sub mypipe (**) mypipe READHANDLE, WRITEHANDLE sub mygrep (&@) mygrep { /foo/ } $a, $b, $c - sub myrand ($) myrand 42 + sub myrand (;$) myrand 42 sub mytime () mytime Any backslashed prototype character represents an actual argument @@ -965,9 +1133,13 @@ follows: ... } -A semicolon separates mandatory arguments from optional arguments. +A semicolon (C<;>) separates mandatory arguments from optional arguments. It is redundant before C<@> or C<%>, which gobble up everything else. +As the last character of a prototype, or just before a semicolon, you can +use C<_> in place of C<$>: if this argument is not provided, C<$_> will be +used instead. + Note how the last three examples in the table above are treated specially by the parser. C is parsed as a true list operator, C is parsed as a true unary operator with unary @@ -981,6 +1153,7 @@ without a prototype. The interesting thing about C<&> is that you can generate new syntax with it, provided it's in the initial position: +X<&> sub try (&@) { my($try,$catch) = @_; @@ -1005,6 +1178,7 @@ scoped, those anonymous subroutines can act like closures... (Gee, is this sounding a little Lispish? (Never mind.)))) And here's a reimplementation of the Perl C operator: +X sub mygrep (&@) { my $code = shift; @@ -1058,6 +1232,7 @@ This is all very powerful, of course, and should be used only in moderation to make the world a better place. =head2 Constant Functions +X Functions with a prototype of C<()> are potential candidates for inlining. If the result after optimization and constant folding @@ -1079,7 +1254,17 @@ The following functions would all be inlined: sub FLAG_MASK () { FLAG_FOO | FLAG_BAR } sub OPT_BAZ () { not (0x1B58 & FLAG_MASK) } - sub BAZ_VAL () { + + sub N () { int(OPT_BAZ) / 3 } + + sub FOO_SET () { 1 if FLAG_MASK & FLAG_FOO } + +Be aware that these will not be inlined; as they contain inner scopes, +the constant folding doesn't reduce them to a single constant: + + sub foo_set () { if (FLAG_MASK & FLAG_FOO) { 1 } } + + sub baz_val () { if (OPT_BAZ) { return 23; } @@ -1088,13 +1273,6 @@ The following functions would all be inlined: } } - sub N () { int(BAZ_VAL) / 3 } - BEGIN { - my $prod = 1; - for (1..N) { $prod *= $_ } - sub N_FACTORIAL () { $prod } - } - If you redefine a subroutine that was eligible for inlining, you'll get a mandatory warning. (You can use this warning to tell whether or not a particular subroutine is considered constant.) The warning is @@ -1110,14 +1288,15 @@ inlining mechanism in some other way, such as } =head2 Overriding Built-in Functions +X X X X Many built-in functions may be overridden, though this should be tried only occasionally and for good reason. Typically this might be done by a package attempting to emulate missing built-in functionality on a non-Unix system. -Overriding may be done only by importing the name from a -module--ordinary predeclaration isn't good enough. However, the +Overriding may be done only by importing the name from a module at +compile time--ordinary predeclaration isn't good enough. However, the C pragma lets you, in effect, predeclare subs via the import syntax, and these names may then override built-in ones: @@ -1172,10 +1351,9 @@ that understands regular expressions. sub glob { my $pat = shift; my @got; - local *D; - if (opendir D, '.') { - @got = grep /$pat/, readdir D; - closedir D; + if (opendir my $d, '.') { + @got = grep /$pat/, readdir $d; + closedir $d; } return @got; } @@ -1224,14 +1402,16 @@ C replacement as C, it will actually receive the argument C<"Foo/Bar.pm"> in @_. See L. And, as you'll have noticed from the previous example, if you override -C, the C*E> glob operator is overridden as well. +C, the C<< <*> >> glob operator is overridden as well. In a similar fashion, overriding the C function also overrides -the equivalent I/O operator C<< >>. +the equivalent I/O operator C<< >>. Also, overriding +C also overrides the operators C<``> and C. Finally, some built-ins (e.g. C or C) can't be overridden. =head2 Autoloading +X X If you call a subroutine that is undefined, you would ordinarily get an immediate, fatal error complaining that the subroutine doesn't @@ -1244,7 +1424,8 @@ been passed to the original subroutine. The fully qualified name of the original subroutine magically appears in the global $AUTOLOAD variable of the same package as the C routine. The name is not passed as an ordinary argument because, er, well, just -because, that's why... +because, that's why. (As an exception, a method call to a nonexistent +C or C method is just skipped instead.) Many C routines load in a definition for the requested subroutine using eval(), then execute that subroutine using a special @@ -1270,7 +1451,7 @@ even need parentheses: use subs qw(date who ls); date; who "am", "i"; - ls -l; + ls '-l'; A more complete example of this is the standard Shell module, which can treat undefined subroutine calls as calls to external programs. @@ -1282,6 +1463,7 @@ SelfLoader modules in L, and the document on adding C functions to Perl code in L. =head2 Subroutine Attributes +X X X A subroutine declaration or definition may have a list of attributes associated with it. If such an attribute list is present, it is @@ -1299,17 +1481,17 @@ nest properly. Examples of valid syntax (even though the attributes are unknown): - sub fnord (&\%) : switch(10,foo(7,3)) : expensive ; - sub plugh () : Ugly('\(") :Bad ; + sub fnord (&\%) : switch(10,foo(7,3)) : expensive; + sub plugh () : Ugly('\(") :Bad; sub xyzzy : _5x5 { ... } Examples of invalid syntax: - sub fnord : switch(10,foo() ; # ()-string not balanced - sub snoid : Ugly('(') ; # ()-string not balanced - sub xyzzy : 5x5 ; # "5x5" not a valid identifier - sub plugh : Y2::north ; # "Y2::north" not a simple identifier - sub snurt : foo + bar ; # "+" not a colon or space + sub fnord : switch(10,foo(); # ()-string not balanced + sub snoid : Ugly('('); # ()-string not balanced + sub xyzzy : 5x5; # "5x5" not a valid identifier + sub plugh : Y2::north; # "Y2::north" not a simple identifier + sub snurt : foo + bar; # "+" not a colon or space The attribute list is passed as a list of constant strings to the code which associates them with the subroutine. In particular, the second example @@ -1319,7 +1501,7 @@ parsed and invoked: use attributes __PACKAGE__, \&plugh, q[Ugly('\(")], 'Bad'; For further details on attribute lists and their manipulation, -see L. +see L and L. =head1 SEE ALSO