The short-circuiting sidebar in chapter 3 invites recall of ok() when it has not been previously introduced

$make_cart_sundae() should be $make_cart_sundae->()

The example says "Both true" even when the condition is different, result "Both true" is not printed:

say "Both true!" if ok(0, 'first subexpression')
&& ok(1, 'second subexpression' );

This example prints:

 not ok 1 - first subexpression
Both true!

"is" missing in "It cheap, both in terms of code and memory, to use only the keys of a hash for storage."

Revise sentence "Hashes can also serve many purposes named parameters passed to functions."

Carp::carp( "Can't light a lit light source!" )

is listed twice in "LightSource::Cranky" - it should carp "Can't quench a quiet light" the second time.

This is an overall remark on the whole dynamic scope section.

The section starts with a demonstration of how dynamic scoping works. The variable there is declared with use vars. The section then concludes on a note of "our exists, but there's no reason to actually use it."

Considering how the documentation for vars says it's mostly deprecated in favor of our, I don't know who to believe anymore.

[edit: change markup from POD to markdown so we get a chance at understanding what I meant]

CREDITS currently reads:

N: <name>
E: <email address>

N: chromatic
M: [email protected]

The "M:" on the last line seems wrong, unless it is because chromatic is the Main/Master/Major credit?

raisedto => sub { $[0] ^ $[1] }, should be **

From 21c9513722f9bdf4a4efbae8657fa5f37d5ac114 Mon Sep 17 00:00:00 2001
From: Mark A. Stratman [email protected]
Date: Tue, 29 Jun 2010 11:06:36 -0500
Subject: [PATCH] Fixed "pronounded" typo in Chapter 1

sections/expressivity.pod | 2 +-
1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/sections/expressivity.pod b/sections/expressivity.pod
index 8d9fac5..d471481 100644
--- a/sections/expressivity.pod
+++ b/sections/expressivity.pod
@@ -17,7 +17,7 @@ advanced features.
X
X

-Perl hackers have a slogan for this: I, pronounded "Tim Toady", or
+Perl hackers have a slogan for this: I, pronounced "Tim Toady", or
"There's more than one way to do it!"

Where this expressivity can provide a large palette with which master craftsman

1.7.1

Tail calls are better explained in the Recursion Section. Maybe merge the two?

Talk about the following idiom?
for ($var) { s///; s///; ... }

 B<return $year - $self->birth_year();>

that line formats incorrectly, turning the accessor into a subtraction

Sentence is redendered in HTML as : "If you do so, Perl will not set the topic variable C(<$_>) to the iterated values."

I noticed that "void context" has contains a space, while "scalar_context" and "list_context" contain underscores. I assume you meant to use spaces in all three locations.

The following construct fails in a confusing way for new commers to Perl, maybe a note could be added (syntax error near "else if"):

if (...) { ... } else if (...) {...}

Maybe explain the result of "say ( 1 + 2 + 3 ) * 4;" as return of say() multiplied by 4.

"A block block form groups multiple expressions into a single unit" - dupplicate block

Notes on Modern Perl

Chapter 01

On free Unix-like systems you may need to install a package such as
perl-doc.

I know this problem occurs on Debian and Debian-derived distros. Many Ubuntu
users may not be aware that they are on a "free Unix-like system." Perhaps
instead, "On some Linux distributions..."

If you can spot the error in the sentence "Perl are a fun language", you've
trained your mind to spot similar types of errors.

For most people, that sentence sounds wrong as a result of habituation rather
than training. (That is, they haven't actively done anything, they just hear
it as wrong.) This is a small thing, perhaps, except that you may want to
acknowledge that learning Perl is like learning a second (third, fourth)
language. What comes naturally to you for your first language requires a lot
more effort for languages you learn later.

Void, Scalar and List Context

This section plunges into very deep waters very quickly. Consider this:

Remember that argument lists and lists themselves--especially lists used in
hash initializers--propagate list context to the expressions they contain.

You haven't yet said anything about "hash initializers" (or hashes!), so what is
a beginner supposed to make of this?

It may be that you plan to redo context again later, but if so, I would tell the
person just meeting the book (and Perl) that this is a first pass over a very
important concept. That way, they won't worry too much if some details escape
them.

redo example " For example, you could implement a silly file parser that joins lines which end with a backslash with:"

s{.*$}{} should read s{$}{}

In the sentence "... as well as their in-place variants (&=, |=, and ^=)."

Missing <<= and >>=

I was suprised that there's no discussion of file handing in the book. I would have expected a small section on Path::Class and how that can be used to manipulate file paths in a OS independent way.

The example of Cat composed with the LivingBeing role does not have an "age" method as the LivingBeing role requires- it has the birth_year accessor but not the age method shown earlier in the document.

The paragraph reads:

Unlike $, Perl automatically localizes @ for you when you call other subroutines. Array functions such as unshift, push, splice, and pop operate on @_.

As far as I know, only pop (and shift, not mentioned though it could be the most frequent use of default @_) take a default argument; unshift, push and splice do not. perlfunc and crude testing on 5.10.1 seem to agree.

Correct the translation:

my $food_ref = {
    'birthday cake' => 'torta de cumpleaños',
    candy             => 'dulces',
    cupcake          => 'magdalena',
    'ice cream'       => 'helado',
};

$make_cart_sundae() should be $make_cart_sundae->()

$make_cart_sundae() should be $make_cart_sundae->()

Notes for Chapter 2.

Under Development Sites, perhaps mention that Perl 5 Porters is often called p5p.

"and is buildable, installable, updateable, and testable on its own."

Many modules have dependencies that must be met before you can test or install them. Some won't even build without the proper dependencies.

A simple incantation to get a full Perl 5 environment in your home directory would be nice at the end of the chapter. On OS X this is particularly important as Apple has a tendency to break Perl 5 if you install modules in the default locations.

Section "Declaring Anonymous Functions", %dispatch table:

raisedto => sub { $[0] ^ $[1] },

should be

raisedto => sub { $[0] ** $[1] },

build_html.pl uses #! perl while the other uses #!/usr/bin/perl

I'd suggest both use the latter or perhaps using #!/usr/bin/env perl

Within the Store::IceCream package, $num_flavors is available
without a namespace prefix. Outside of that package, it is available
as $Store::IceCream::num_flavors. If $num_flavors were a lexical
variable (declared with my), it would not be available outside of
the package. Inside the package, it would only be available within
the appropriate scope.

Not strictly true: lexical $num_flavors can be accessible from outside
of the package, provided it's still in the same lexical scope. For example:

{ package Store::IceCream; my $num_flavors = 42; package foo; say $num_flavors }

To keep things simple, maybe reword to mention files? "If $num_flavors were a lexical variable, it would not be accessible outside the file defining it," though incomplete, is strictly true.

That may not read as nicely, however. Most of the time you don't
need that syntax, for two reasons. First, you can use negative
offsets to access an array from the end instead of the start. The
final element of an array is available at the index -1. The
penultimate element of the array is available at index -2, and so
on.

The paragraph starts by mentioning two reasons, but only gives one. And ends on an unbalanced note, having said "First, " but omitted to give a "Second, "

This is the error:

$ perl build/tools/build_html.pl
build/chapters/chapter_06.pod around line 247: '=end programlisting X<regular expressions; \d>' is invalid.  (Stack: =begin programlisting)

And the patch is quite simple:

--- a/sections/regular_expressions.pod
+++ b/sections/regular_expressions.pod
@@ -223,6 +223,7 @@ characters and the underscore:
         next unless $word =~ B</lB<\w\w>m/>;

 =end programlisting
+
 X<regular expressions; \d>

 Use the C<\d> metacharacter to match digits:

Yes lack of binmode, hurts every new windows user reading binary files.

In the sentence "The numeric operators enforce numeric contexts on their operands. They consist of the standard arithmetic operators such as addition (+), subtraction (-), multiplication (), division (/), exponentiation (__), modulo (%), their in-place variants (+=, -=, *=, /=, *=, and %=), and auto-decrement (--), whether postfix or prefix."

Maybe explain that ++ is not in the list, because of the magic string increment.

I believe the line

 if ($contact_info =~ /(?<phone>$phone_number))

in Chapter 7 should have a matching / for the regex.

In moose.pod section on "Roles", the package CalculateAgeFromBirthYear is meant to be a role but never declares "use Moose::Role;" in the listed code.

Example on named parameters to functions with defaults should use //= istead of =:

sub make_sundae
{
    my %parameters = @_;
    $parameters{flavor}    = 'Vanilla';
    $parameters{topping}   = 'fudge';
    $parameters{sprinkles} = 100;
    ...
}

Also @_ written as @ in the next example.

sub make_sundae
{
    my %parameters =
    (
        flavor => 'Vanilla',
        topping => 'fudge',
        sprinkles => 100,
        @
    );
    ...
}

I had the same error as issue #1 which I fixed by using "scope" instead of "scoping".

I now get the following output:

$ perl build/tools/build_chapters.pl
Writing 'sections/chapter_01.pod'
Writing 'sections/chapter_02.pod'
Writing 'sections/chapter_03.pod'
Writing 'sections/chapter_04.pod'
Writing 'sections/chapter_05.pod'
Writing 'sections/chapter_06.pod'
Writing 'sections/chapter_07.pod'
Writing 'sections/chapter_08.pod'
Writing 'sections/chapter_09.pod'
Writing 'sections/chapter_10.pod'
Writing 'sections/chapter_11.pod'
Writing 'sections/chapter_12.pod'
Writing 'sections/chapter_13.pod'
Writing 'sections/chapter_14.pod'
Writing 'sections/chapter_15.pod'
Writing 'sections/chapter_16.pod'
Scenes missing from chapters:
universal
testing
handling_warnings
pragmas
modules
autoload
barewords
exceptions
global_variables
blessed_references
coercion
distributions
method_sub_equivalence
references
idioms
moose
packages
missing_defaults
code_generation
hashes at build/tools/build_chapters.pl line 17.

I'm not sure if this is a fatal error or not?

R.

"If you prefer an online version, http://perldoc.perl.org/ hosts recent versions of the Perl documentation."

I would say:

If you prefer an online version, http://perldoc.perl.org/ hosts recent versions of the Core Perl documentation and you can find all of the documentation for CPAN modules at http://search.cpan.org.

Casing question, you are writing POD, but perlpod says Pod. Other things say POD (such as Pod::Parser). And others say pod (perlglossary). I guess just sticking to one is the best course.

"To express this context, evaluate an expression and see what you do with the results."

I think I know what this is saying and I still find it confusing. Perhaps it should be:

To understand this context, look at the what this expression will return to.

In Numeric, String, and Boolean Context. You use the say function. People who are starting Perl may try to use say and be confused when it doesn't work. I would avoid features that don't get turned on until you reach the point where you tell people how to turn them on.

"The best example a linguistic shortcut in Perl is the default scalar variable,"

should probably be

The best example of a linguistic shortcut in Perl is the default scalar variable,

"If you use the three-argument form of print and say, where the first argument is a filehandle to which to print, you cannot omit $_; Perl will interpret this as the two-argument form of both functions."

I think you mean two-argument and one-argument, but even that is inaccurate; print and say can take many arguments. Perhaps it should be:

If you use the versions of print and say that take a filehandle, you cannot omit $_; Perl will interpret this as an attempt to print the value of the filehandle to STDOUT.

"Many of Perl's scalar operators work on the default scalar variable if you do not provide an alternative."

You may want to explain what the scalar operators are before you reference them.

"the name of the class C() as its invocant. This is a I:"

perhaps should have been "the name of the class C" ?

"Should I include a table of escapes here? It's the same as in regexes."

IMHO, include either a table of escapes or a reference to the table.

I cloned the repository and ran build_chapters. It failed with the included message.

OS is Snow Leopard, details:
Darwin Finarfin.local 10.2.0 Darwin Kernel Version 10.2.0: Tue Nov 3 10:37:10 PST 2009; root:xnu-1486.2.11~1/RELEASE_I386 i386

Perl version:
This is perl, v5.10.1 (*) built for darwin-2level

Error message:
vlion$ perl build/tools/build_chapters.pl
Writing 'sections/chapter_01.pod'
Writing 'sections/chapter_02.pod'
Writing 'sections/chapter_03.pod'
Writing 'sections/chapter_04.pod'
Writing 'sections/chapter_05.pod'
Writing 'sections/chapter_06.pod'
Unknown section 'scoping' in 'sections/chapter_07.pod'

The sidebar: "Note that sort does not set $_, as it must process the elements of its
list two at a time."

seems out of place given that no surrounding examples in the section use the function. It could be potentially confusing to newer programmers who aren't familiar with sort.
Those who read this section, and despite no mention of 'sort' could potentially think "gee, why doesn't sort work on $?", will probably be the same people who already know why sort doesn't operate on $. Anyone else may simply get confused.

This is just a thought to consider, if you haven't already.

When I run it:
$ perl build/tools/build_html.pl || echo Failure
Unknown link objects
Failure

It dies and exits with the wrong error code.

Not a major problem since the README explicitly says to call

$ perl build/tools/...

But it seemed strange that build_chapters.pl is 0644 and build_html.pl is 0755.

"If you use the three-argument form of C and C, where the first
argument is a filehandle to which to print, you cannot omit C<$_>; Perl will
interpret this as the two-argument form of both functions."

Not only is this confusing but I think it's also wrong:

perl -E '$_ = "foo"; print STDERR; say STDOUT;'
foofoo

Talking about the three-argument form of print and say seems wrong because they both take an optional filehandle then an optional list of strings..

Just a thought- after the "Inheritance and isa()" section, also mention "Composition and does()". Since "Roles provide composition-time safety, better type checking, and arguably better-factored and less coupled code" it makes sense to show how to do things with roles that are also done with inheritance.

Sentence not clear on a first read: "Consider choosing naming and code-organization schemes which the apparent relationship between the names of these classes or namespaces makes obvious."

$make_cart_sundae() should be $make_cart_sundae->()

Notes for Chapter 3.

"exploit points of genericity wherever possible."

Maybe "exploit points of generality wherever possible."

"Within the Store::IceCream package, $num_flavors is available without a namespace prefix. Outside of that package, it is available as $Store::IceCream::num_flavors."

If only that were true. Variables declared with our are lexically scoped, but packages do not generate scope on their own, so

package Foo;

our $foo = 5;

package Bar;

print "$foo\n";

Prints "5\n" and $foo still is an alias for $Foo::foo (even in the Bar package). Another nasty side effect of our being lexically scoped is that a variable declared in another file, but in the same package is not visible with its short name because a file provides lexical scope.

Characters in a single-quoted string represent themselves literally, with one exception. You may embed a single quote inside a single-quoted string by escaping the quote with a leading backlash:

my $reminder = 'Don\'t forget to escape the single quote!';

There are two exceptions, you may also escape the \ with another , but this is only necessary in two cases: the \ occurs at the end of the string:

my $exception1 = 'foo \\';

and when you want to have more than on \ next to each other:

my $exception2 = 'to get two backslashes (\\\\) you must use four';

Yes, a table of common escapes and the general \x{} form should be mentioned here.

Hopefully the printer does a better job with the UTF-8 than the HTML did.

"looks_like_number which returns true"

This may just be a private pet peeve, but the looks_like_number function returns a true value, not true (there is no true in Perl 5).

"This produces a list. Even though that list never gets assigned to anything, the return value of the second assignment is that list. Perl next evaluates that list in scalar context, due to the scalar assignment to $count in the first assignment. As a result, $count contains the number of elements in the list returned from get_all_clown_hats()."

This should read

This produces a list. The list is assigned to the empty list, which throws away all of the items in the list, but list assignment in scalar context (which is provided by the assignment to $count) returns the number of items on the right hand side of the assignment, so $count is assign the number of items that were produced in the original list.

The way you have written it has at least 3 subtle but important errors:

1. there is no such thing as a list in scalar context (there is only comma operators in scalar context which creates a sequence, not a list).
2. sequences return the last item in scalar context, not the number of items in the sequence
3. list assignment to an empty list returns an empty list in list context

In Lists, you mention that lists and arrays are not interchangeable, but you do not give any examples of where the are not. One simple example is that when indexing into a list, the index is in list context, not scalar:

sub context {
    my $argument = shift;
    my $context  = wantarray;
    say defined $context ? $context ? "list" : "scalar" : "void";
    return $argument;
}

my @a = qw/a b c/;

my $s = $a[context(1)];

$s = ("a", "b", "c")[context(1)];

This can have bad consequences if the function you are calling to get an index returns something different in list context.

"You may not omit the curly braces in block form under any circumstances."

Should this be

Unlike in C, you may not omit the curly braces in block form under any circumstances.

Or is it even necessary?

In short circuiting, you might want to mention the real value of short circuiting: guarding against errors and warnings:

if (exists $h{foo} and $h{foo} eq "bar") {
}

"Scalars containing undef, the values 0 and 0.0, and the empty string evaluate to false. Everything else is true, in the absence of deeper magic."

Any number that evaluates to 0 is false. This includes 0, 0.0, 0e0, 0x0, etc. The strings "" and "0" evaluate to false, but the strings "0.0", "0e0", etc. do not (which leads to the odd idiom of "0 but true" which is treated as the number 0 by math operators with no warning, but tests as true in boolean context). The empty list and undef both evaluate to false. Empty arrays and hashes return the number 0 in scalar context, so are false as well.

If a variable has a string and a numeric value, the string value is used to determine truthiness.

You might want to leave that last sentence out because it drags in the concepts of dualvars and caching of values.

"The for-style loop allows the programmer to manage iteration conditions manually:"

should be

The C-Style for loop allows the programmer to manage iteration conditions manually:

"The simplest infinite loop in Perl 5 is:

1 while 1;"

I would argue that {redo} is a simpler infinite loop, but then again, I am an asshole.

The continue block has a few uses. You can use it to emulate a C-style for loop with a while loop:
# init test mutate
for (my $i = 0; $i < 5; $i++) {}

#init
my $i = 0;
#test
while ($i < 5) {
} continue {
    #mutate
    $i++;
}

It is also useful if you have some block of code that must run even if the body of the loop says next. The -p option expands out to

LINE: while (defined($_ = <ARGV>)) {
    #the -e code
}
continue {
    die "-p destination: $!\n" unless print $_;
}

In Scalars, a scalar can be undef as well. I question the need to say it can be an object and a reference. Objects are references. If you are going to include objects, then you might want to include filehandles.

"Scalars may be lexical or global variables,"

This might be better written

Scalars may be lexical, package, or global variables. You cannot create global variables, but some of the special variables such as $_ do not belong to a given package.

"Perl 5 stringifies references (References) evaluated in scalar string context and numifies references evaluated in scalar numeric context."

Maybe you should add: "Neither the stringified or numified references can be turned back into a real reference."

"Array indices start at 0."

It is probably best to just pretend that $[ doesn't exist.

You might want to mention that assigning to $#array will resize the array (possibly throwing away values.

In Array Slices you might want to mention that a function called in the index is called in list context, not scalar.

"a hash returns false if it's empty (if it contains no keys or values) and true otherwise."

Again, my anal nature causes me to say

a hash returns 0 if it's empty (if it contains no keys) or a string which is guaranteed to be true otherwise.

I removed "or values" because you can't have a value without a key.

"but it also causes the Perl parser to treat the previous bareword"

You might want to define bareword here.

You might want to mention that keys(%h) = 1024; can used to increase size of the hash if you know you are going to stuff it with a bunch of keys.

In Boolean Coercion you define the true and false values for the third time. I do not know if this is a good or bad thing.

"You almost never need to know that this happpens--perhaps once or twice a decade, if anecdotal evidence is admissible."

First, you have the interesting word happpens, I assume this is like iff?

Second, if you write a lot of forking code that tries to take advantage of COW, you will become intimately familiar with all of the ways a variables metadata can change.

In general, this chapter felt repetitive and muddled.