I think you may be getting your carte blanc before your Camel. :)

I read "the Camel" and I don't believe it mentioned any such thing (probably not the same revision of "the Camel" you refer to, of course). And at the time (quite a while ago) of the coming out party of the "It is documented. Duh!" proclaimers, I don't believe it was documented well in a popular book. In any case, I never saw mention of documentation of that in books in that time frame. I'm not at all surprised that it is documented in some books by now. But I also wouldn't be totally shocked if there was a book that covered it well way back then.

But it is also true that bugs get documented in auxillary reference material. The "It is documented" is more short-hand for the "We can't change it because the standard documentation has always said that it worked that way" claim, and that is the meaning that I call "bull" on.

Let me quote from the Camel, second edition, dating from 1996, shortly after the release of perl 5.003. On page 54, while discussing the angle operator:

Here's how it works: the first time <> is evaluated, the @ARGV array is checked, and if it is null, $ARGV[0] is set to "-", which when opened gives you standard input. The @ARGV array is then processed as a list of filenames. The loop:

    while (<>) {
        ...          # code for each line
    }
[download]

is equivalent to the following Perl-like pseudocode:

    @ARGV = ('-') unless @ARGV;
    while ($ARGV = shift) {
        open(ARGV, $ARGV) or warn "Can't open $ARGV: $!\n";
        while (<ARGV>) {
            ...          # code for each line
        }
    }
[download]

except that it isn't so cumbersome to say, and will actually work. It really does shift @ARGV and put the current filename into variable $ARGV. It also uses filehandle ARGV internally -- <> is just a synonym for <ARGV>, which is magical. (The pseudocode doesn't work because it treats <ARGV> as non-magical.)

If you then switch to pages 191-194, it discusses the open function, including the effects of leading and trailing pipes in the filenames.

Perhaps I should quote from my own node on Perlmonks, in this very thread, from October of 2008?

There is a lot more documentation that <> shouldn't react badly to the file name I close this node with (compared to the so-called "documentation" of the magic behavior by virtue of "is equivalent to the following Perl-like pseudo code" that uses some 'open' which isn't clearly declared to be as magical as Perl's two-arg open).

Yeah, I've heard this justification before. I've been publically laughing at it repeatedly in this thread (and for a long, long time before).

- tye