X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlsub.pod;h=2969341ca12d183935d162b79f30ab5d482d8893;hb=b30f304ae36b3931349d7d5816f5a5646afe5397;hp=cef8050731b82a2803d72cd21d9225e53e97266b;hpb=0e06870bf080a38cda51c06c6612359afc2334e1;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlsub.pod b/pod/perlsub.pod index cef8050..2969341 100644 --- a/pod/perlsub.pod +++ b/pod/perlsub.pod @@ -169,7 +169,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 @@ -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 @@ -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) @@ -728,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(); @@ -930,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 @@ -1009,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, @@ -1094,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: @@ -1182,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 @@ -1270,7 +1354,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