X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlsub.pod;h=ce3b120633e87370984d99a71e034999785b5f78;hb=83272a45226e83bd136d713158e9b44ace2dbc8d;hp=b440cd1d93021ceb68a16e774a353e0073d0cd14;hpb=847a5fae45dac396d0f9e1bb61d5b4ff9d94cdcd;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlsub.pod b/pod/perlsub.pod index b440cd1..ce3b120 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), @@ -327,9 +327,12 @@ 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. +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. The C loop defaults to scoping its index variable dynamically in the manner of C. However, if the index variable is @@ -560,6 +563,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 +622,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,6 +656,39 @@ 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) B: The mechanism described in this section was originally @@ -724,7 +768,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(); @@ -926,6 +970,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 @@ -1005,6 +1065,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, @@ -1178,6 +1245,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 @@ -1266,7 +1360,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