X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlsub.pod;h=2969341ca12d183935d162b79f30ab5d482d8893;hb=b30f304ae36b3931349d7d5816f5a5646afe5397;hp=4ec11f99d46e5daf1248d49504bdf200d070af86;hpb=0df79f0ce1a641c23eb6b9df44bd792c1c4400e1;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlsub.pod b/pod/perlsub.pod index 4ec11f9..2969341 100644 --- a/pod/perlsub.pod +++ b/pod/perlsub.pod @@ -39,7 +39,7 @@ To call subroutines: Like many languages, Perl provides for user-defined subroutines. These may be located anywhere in the main program, loaded in from other files via the C, C, or C keywords, or -generated on the fly using C or anonymous subroutines (closures). +generated on the fly using C or anonymous subroutines. You can even call a function indirectly using a variable containing its name or a CODE reference. @@ -154,7 +154,7 @@ of changing them in place: } Notice how this (unprototyped) function doesn't care whether it was -passed real scalars or arrays. Perl sees all arugments as one big, +passed real scalars or arrays. Perl sees all arguments as one big, long, flat parameter list in C<@_>. This is one area where Perl's simple argument-passing style shines. The C function would work perfectly well without changing the C @@ -169,8 +169,8 @@ 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 L for alternatives. +everything in C<@a> and made C<@b> empty. See +L for alternatives. A subroutine may be called using an explicit C<&> prefix. The C<&> is optional in modern Perl, as are parentheses if the @@ -179,7 +179,7 @@ when just naming the subroutine, such as when it's used as an argument to defined() or undef(). Nor is it optional when you 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-E()> notation solves that problem. +although the C<< $subref->() >> notation solves that problem. See L for more about all that. Subroutines may be called recursively. If a subroutine is called @@ -207,8 +207,8 @@ 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, and -C--plus all functions mentioned in L. +things include C, C, C, C, C, +C and C--plus all functions mentioned in L. =head2 Private Variables via my() @@ -220,9 +220,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), @@ -325,11 +325,8 @@ 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. - -None of the foregoing text applies to C or C -modifiers appended to simple statements. Such modifiers are not -control structures and have no effect on scoping. +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 @@ -357,7 +354,7 @@ A compilation error results otherwise. An inner block may countermand this with C. A C has both a compile-time and a run-time effect. At compile -time, the compiler takes notice of it. The principle usefulness +time, the compiler takes notice of it. The principal usefulness of this is to quiet C, but it is also essential for generation of closures as detailed in L. Actual initialization is delayed until run time, though, so it gets executed @@ -454,7 +451,7 @@ starts to run: } See L about the -special triggered functions, C, C, C and C. +special triggered functions, 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 @@ -560,6 +557,13 @@ hash to some other implementation: } [..%ahash back to its initial tied self again..] +B The code example above 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. + As another example, a custom implementation of C<%ENV> might look like this: @@ -612,14 +616,15 @@ types is subject to change in future. =head2 Lvalue subroutines -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 { @@ -645,9 +650,38 @@ and in: all the subroutines are called in a list context. -The current implementation does not allow arrays and hashes to be -returned from lvalue subroutines directly. You may return a -reference instead. This restriction may be lifted in future. +=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) @@ -697,9 +731,11 @@ Despite the existence of C, there are still three places where the C operator still shines. In fact, in these three places, you I use C instead of C. -=over +=over 4 + +=item 1. -=item 1. You need to give a global variable a temporary value, especially $_. +You need to give a global variable a temporary value, especially $_. The global variables, like C<@ARGV> or the punctuation variables, must be Cized with C. This block reads in F, and splits @@ -716,7 +752,9 @@ in C<@Fields>. It particular, it's important to Cize $_ in any routine that assigns to it. Look out for implicit assignments in C conditionals. -=item 2. You need to create a local file or directory handle or a local function. +=item 2. + +You need to create a local file or directory handle or a local function. A function that needs a filehandle of its own must use C on a complete typeglob. This can be used to create new symbol @@ -724,7 +762,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(); @@ -746,7 +784,9 @@ a local alias. See L for more about manipulating functions by name in this way. -=item 3. You want to temporarily change just one element of an array or hash. +=item 3. + +You want to temporarily change just one element of an array or hash. You can Cize just one element of an aggregate. Usually this is done on dynamics: @@ -891,7 +931,7 @@ like a built-in function. If you call it like an old-fashioned subroutine, then it behaves like an old-fashioned subroutine. It naturally falls out from this rule that prototypes have no influence on subroutine references like C<\&foo> or on indirect subroutine -calls like C<&{$subref}> or C<$subref-E()>. +calls like C<&{$subref}> or C<< $subref->() >>. Method calls are not influenced by prototypes either, because the function to be called is indeterminate at compile time, since @@ -924,6 +964,22 @@ that absolutely must start with that character. The value passed as part of C<@_> will be a reference to the actual argument given in the subroutine call, obtained by applying C<\> to that argument. +You can also backslash several argument types simultaneously by using +the C<\[]> notation: + + sub myref (\[$@%&*]) + +will allow calling myref() as + + myref $var + myref @array + myref %hash + myref &sub + myref *glob + +and the first argument of myref() will be a reference to +a scalar, an array, a hash, a code, or a glob. + Unbackslashed prototype characters have special meanings. Any unbackslashed C<@> or C<%> eats all remaining arguments, and forces list context. An argument represented by C<$> forces scalar context. An @@ -1003,6 +1059,13 @@ programmers, and that it will not intrude greatly upon the meat of the module, nor make it harder to read. The line noise is visually encapsulated into a small pill that's easy to swallow. +If you try to use an alphanumeric sequence in a prototype you will +generate an optional warning - "Illegal character in prototype...". +Unfortunately earlier versions of Perl allowed the prototype to be +used as long as its prefix was a valid prototype. The warning may be +upgraded to a fatal error in a future version of Perl once the +majority of offending code is fixed. + It's probably best to prototype new functions, not retrofit prototyping into older ones. That's because you must be especially careful about silent impositions of differing list versus scalar contexts. For example, @@ -1088,8 +1151,8 @@ 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: @@ -1176,6 +1239,33 @@ a properly written override. For a fully functional example of overriding C, study the implementation of C in the standard library. +When you override a built-in, your replacement should be consistent (if +possible) with the built-in native syntax. You can achieve this by using +a suitable prototype. To get the prototype of an overridable built-in, +use the C function with an argument of C<"CORE::builtin_name"> +(see L). + +Note however that some built-ins can't have their syntax expressed by a +prototype (such as C or C). If you override them you won't +be able to fully mimic their original syntax. + +The built-ins C, C and C can also be overridden, but due +to special magic, their original syntax is preserved, and you don't have +to define a prototype for their replacements. (You can't override the +C syntax, though). + +C has special additional dark magic: if you invoke your +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. + +In a similar fashion, overriding the C function also overrides +the equivalent I/O operator C<< >>. + +Finally, some built-ins (e.g. C or C) can't be overridden. + =head2 Autoloading If you call a subroutine that is undefined, you would ordinarily @@ -1230,7 +1320,7 @@ functions to Perl code in L. A subroutine declaration or definition may have a list of attributes associated with it. If such an attribute list is present, it is -broken up at space or comma boundaries and treated as though a +broken up at space or colon boundaries and treated as though a C had been seen. See L for details about what attributes are currently supported. Unlike the limitation with the obsolescent C, the @@ -1244,8 +1334,8 @@ 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: @@ -1254,7 +1344,7 @@ Examples of invalid syntax: 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 comma or space + 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 @@ -1264,13 +1354,13 @@ 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 See L for more about references and closures. See L if you'd like to learn about calling C subroutines from Perl. -See L if you'd like to learn about calling PErl subroutines from C. +See L if you'd like to learn about calling Perl subroutines from C. See L to learn about bundling up your functions in separate files. See L to learn what library modules come standard on your system. See L to learn how to make object method calls.