| Subject: | Documentation bugs |
I am new to Switch and have not used it. I was trying to understand it from the documentation and found some points of confusion. Attempts to contact the module maintainer directly have been unsuccessful, so I'm adding these here for posterity.
1. The use of $_[0] is never discussed. As someone who realises this is being done with a source filter and that the case options are probably being rewritten as subroutines, I can guess that $_[0] refers to the thing we're switching on rather than the first element of the subroutine this statement is included in but this is unclear
2. In the example which includes this section:
case { $_[0] >= 10 } { # if $_ >= 10
my $age = <>;
switch (sub{ $_[0] < $age } ) {
case 20 { print "teens\n"; } # if 20 < $age
case 30 { print "twenties\n"; } # if 30 < $age
else { print "history\n"; }
}
}
Doesn't this contract to:
# assume $_ = 15
case { $_[0] >= 10 } { # true
my $age = 25; # for example
switch ( 1 ) { # 15 is < 25
...
...
else { print "history\n" }
}
}
I can't test it because I can't get the example to compile (Switch version 2.09, Perl 5.8.4). Since this is the same example as in POD for my version of Switch I presume that this would compile on my version if the code was not in error.
Attempting to correct(?) the case statement to create an anon sub
(as suggested later in the document doesn't seem to help either).
3.
sub classify_digit
{
switch ($_[0]) { case 0 { return 'zero' }
case [2,4,6,8] { return 'even' }
case [1,3,4,7,9] { return 'odd' }
Should the second 4 actually be a 5?
4. s/thrid/third/
5. More needs to be said about __. The documentation says:
__ < 2 + __
is equivalent to:
sub { $_[0] < 2 + $_[1] }
what is $_[1] and how do I set it? Is this a typo, or if I use __ a third time will it compare to $_[2]?
6. At the very start of the documentation, 18 different ways are enumerated as ways that two values could be matched. The description then goes on to say that:
The Switch.pm module implements a generalized case mechanism that
covers the numerous possible combinations of switch and case values
described above.
but I'm not convinced that it does.
For example the table says:
array scalar array entry existence match if 0<=$c && $c<@$s;
ref array entry definition match if defined $s->[$c];
array entry truth match if $s->[$c];
and I realise that I can write:
case @array { ... } # and
case \@array { ... }
but unless I'm greatly mistaken that only tests the first part: array entry
existence. Without writing a subroutine for my case statement I can't work out how Switch makes it easy for me to test array entry definition or array entry truth.
This could be improved by explaining early in the documentation that other forms of tests can be done by using a subroutine etc rather than making the reader have to deduce that.