X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlsub.pod;h=b440cd1d93021ceb68a16e774a353e0073d0cd14;hb=0c4128adc5f62cd332ae4fa5bc8999c95d611d36;hp=416763f6d8d164fafcd994429f35d106a3b102ce;hpb=1d7c184104c076988718a01b77c8706aae05b092;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlsub.pod b/pod/perlsub.pod index 416763f..b440cd1 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> an empty list. 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,7 +207,7 @@ 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 +things include C, C, C, C, C, and C--plus all functions mentioned in L. =head2 Private Variables via my() @@ -357,7 +357,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 +454,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 @@ -645,10 +645,6 @@ 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. - =head2 Passing Symbol Table Entries (typeglobs) B: The mechanism described in this section was originally @@ -697,9 +693,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 +714,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 @@ -746,7 +746,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 +893,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 @@ -928,11 +930,21 @@ 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 C<&> requires an anonymous subroutine, which, if passed as the first -argument, does not require the C keyword or a subsequent comma. A -C<*> allows the subroutine to accept a bareword, constant, scalar expression, +argument, does not require the C keyword or a subsequent comma. + +A C<*> allows the subroutine to accept a bareword, constant, scalar expression, typeglob, or a reference to a typeglob in that slot. The value will be available to the subroutine either as a simple scalar, or (in the latter -two cases) as a reference to the typeglob. +two cases) as a reference to the typeglob. If you wish to always convert +such arguments to a typeglob reference, use Symbol::qualify_to_ref() as +follows: + + use Symbol 'qualify_to_ref'; + + sub foo (*) { + my $fh = qualify_to_ref(shift, caller); + ... + } A semicolon separates mandatory arguments from optional arguments. It is redundant before C<@> or C<%>, which gobble up everything else. @@ -1220,7 +1232,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 @@ -1234,8 +1246,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: @@ -1244,7 +1256,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 @@ -1260,7 +1272,7 @@ see L. 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.