Re: [perl #33095] Misleading documentation for "while (<>)"

"James E Keenan via RT" <perlbug-followup@perl.org> wrote
   on Tue, 31 Jan 2012 18:14:47 PST: 

> On Fri Dec 17 17:57:00 2004, kj789@lycos.com wrote:
>> This is a bug report for perl from kj789@lycos.com,
>> generated with the help of perlbug 1.34 running under perl v5.8.0.
>> 
>> [snip]
>> 
>> Also, "magical" is not defined, and there is no way for a user to
>> determine how to find out what this means.  In light of the first
>> bug, the natural conclusion is that the unexpected behavior of
>> "last" has something to do with ARGV's "magical" properties, but
>> there's no way for the user to confirm or refute this guess.

> Discussion in this ticket petered out seven years ago.  However, I think
> the OP made, in passing, a valid point:  the meaning of "magic" or
> "magical" is nowhere defined in 'perlop':

> #####
> $ grep -inC1 magic pod/perlop.pod
> 162-
> 163:The auto-increment operator has a little extra builtin magic to it.  If
> 164-you increment a variable that is numeric, or that has ever been used in
> --
> 179-
> 180:The auto-decrement operator is not magical.
> 181-
> --
> 897-
> 898:The range operator also works on strings, using the magical
> 899-auto-increment, see below.
> --
> 988-
> 989:The range operator (in list context) makes use of the magical
> 990-auto-increment algorithm if the operands are strings.  You
> --
> 1005-
> 1006:If the final value specified is not in the sequence that the magical
> 1007-increment would produce, the sequence goes until the next value would
> --
> 1009-
> 1010:If the initial value specified isn't part of a magical increment
> 1011-sequence (that is, a non-empty string matching
> C</^[a-zA-Z]*[0-9]*\z/>),
> --
> 1595-corresponding C</STRING/msixpodual> expression. The returned value is a
> 1596:normalized version of the original pattern. It magically differs from
> 1597-a string containing the same characters: C<ref(qr/x/)> returns
> "Regexp";
> --
> 2897-internally. <> is just a synonym for <ARGV>, which
> 2898:is magical.  (The pseudo code above doesn't work because it treats
> 2899:<ARGV> as non-magical.)
> 2900-
> #####

> How should this be rectified?

    % man perlglossary | tcgrep -pi magic
	   dweomer
	       An enchantment, illusion, phantasm, or jugglery.  Said
	       when Perl's magical "dwimmer" effects don't do what
	       you expect, but rather seem to be the product of
	       arcane dweomercraft, sorcery, or wonder working.
	       [From Old English]
    --------------------
	   dwimmer
	       DWIM is an acronym for "Do What I Mean", the principle
	       that something should just do what you want it to do
	       without an undue amount of fuss.  A bit of code that
	       does "dwimming" is a "dwimmer".  Dwimming can require
	       a great deal of behind-the-scenes magic, which (if it
	       doesn't stay properly behind the scenes) is called a
	       "dweomer" instead.
    --------------------
       MM
	   magic
	       Technically speaking, any extra semantics attached to
	       a variable such as $!, $0, %ENV, or %SIG, or to any
	       tied variable.  Magical things happen when you diddle
	       those variables.
    --------------------
	   magical increment
	       An "increment" operator that knows how to bump up
	       alphabetics as well as numbers.
    --------------------
	   magical variables
	       Special variables that have side effects when you
	       access them or assign to them.  For example, in Perl,
	       changing elements of the %ENV array also changes the
	       corresponding environment variables that subprocesses
	       will use.  Reading the $! variable gives you the
	       current system error number or message.
    --------------------
	   tie The bond between a magical variable and its
	       implementation class.  See "tie" in perlfunc and
	       perltie.
    --------------------
	       something that appears on the screen matches how it
	       will eventually look, like Perl's format declarations.
	       Also used to mean the opposite of magic because
	       everything works exactly as it appears, as in the
	       three-argument form of open.
    --------------------

• [perl #33095] Misleading documentation for "while (<>)" by James E Keenan via RT
• Re: [perl #33095] Misleading documentation for "while (<>)" by Tom Christiansen