Hi, I find the documentation for wantarray in perlfunc.pod a little obscure in its current form (i.e. version 5.8.7).
The obscure passage is the following: wantarray()'s result is unspecified in the top level of a file, in a BEGIN , CHECK , INIT or END block, or in a DESTROY method. All make sense to me except "top level of a file", which is obscure IMHO. Could it be explained more in depth? My very issue regards the use of "do" on a file: it currently seems to support wantarray correctly even "in the top level of a file" (example at http://www.perlmonks.org/?node_id=477801), but I'd like to know if this still falls in the "unspecified behaviour" warning and, if yes, why. To give you some background perspective, I saw some emails here in p5p about the issues regarding END, INIT, etc. (for example at http://www.mail-archive.com/perl5-porters@perl.org/msg83191.html); I tried to ask at Perl Monks first (see http://www.perlmonks.org/?node_id=477759) for explainations and suggestions for a modification proposal, but with no luck. #### Proposals ######### Unfortunately, my Perl Powers are too weak for me to propose something 100% correct and clear. But I want to be proactive and try to propose to change "file" into "program": wantarray()'s result is unspecified in the top level of a program, in a BEGIN , CHECK , INIT or END block, or in a DESTROY method. I think that it would be good to have some self-contained definition of what the "context" is exactly - this is something really beyond my strenghts (but see below for some effort :). Given such an explaination, the docs could change as follows (note that I added the results of some tests of mine): wantarray()'s result is unspecified wherever there is not a user reachable context, which happens in the top level of a program, in a BEGIN, CHECK, INIT or END block, or in a DESTROY method. See blah-blah-blah for the exact definition of context. As I said, giving clear and exact explainations is far beyond my possibilities. But I can write down something that, if true, could be used to provide examples for this C<do> issues regarding the context. Note that you can still get a context in the top level of a file when you use C<do 'file.pl';>. In this case, in fact, the code inside I<file.pl> is provided a context according to the call to C<do>: my @a = do 'file.pl'; # array context provided my $s = do 'file.pl'; # scalar context provided do 'file.pl'; # void or "external" context provided Dealing with context, these calls to C<do 'file.pl'> are equivalent to sub calls; the last line, for example, could "inherit" the context when called as the final statement of a sub or of a file. Excuse my verbosity, but I'm not anglophone - thus I'm not so good in getting understood with fewer words :) Best regards, Flavio.