Browse files

Merge remote branch 'upstream/master'

Conflicts:
	CREDITS
	sections/scope.pod
  • Loading branch information...
2 parents a6329ff + c9259df commit bff0097ab7665a20e7dcb7761a81f55935f0c036 Ed Santiago committed Nov 8, 2011
View
9 CREDITS
@@ -221,3 +221,12 @@ E: celtic@sairyx.org
N: Eduardo Santiago
E: esm@cpan.org
+
+N: Andy Lester
+E: andy@petdance.com
+
+N: Steve Dickinson
+E: dsdickinson@gmail.com
+
+N: Kurt Edmiston
+E: hurdlecrew@gmail.com
View
3 sections/anonymous_functions.pod
@@ -22,12 +22,13 @@ input with behavior:
(
plus => \&add_two_numbers,
minus => \&subtract_two_numbers,
+ times => \&multiply_two_numbers,
# ... and so on
);
sub add_two_numbers { $_[0] + $_[1] }
-
sub subtract_two_numbers { $_[0] - $_[1] }
+ sub multiply_two_numbers { $_[0] * $_[1] }
sub dispatch
{
View
4 sections/arrays.pod
@@ -227,7 +227,7 @@ used as its index:
=begin programlisting
# function called in list context
- my @cats = @cats[ get_cat_indices() ];
+ my @hungry_cats = @cats[ get_cat_indices() ];
=end programlisting
@@ -267,7 +267,7 @@ X<builtins; C<shift>>
X<builtins; C<unshift>>
Similarly, C<unshift> and C<shift> add elements to and remove an element from
-the start of an array:
+the start of an array, respectively:
=begin programlisting
View
2 sections/autoload.pod
@@ -8,7 +8,7 @@ program:
=begin programlisting
- #! perl
+ #!/usr/bin/perl
use Modern::Perl;
View
2 sections/chapter_02.pod
@@ -13,7 +13,7 @@ people. I<People> make a community worth joining and preserving and expanding.
The Perl community is strong and healthy. It welcomes willing participants at
all levels, from novices to core developers. Take advantage of the knowledge
and experience of countless other Perl programmers, and you'll become a better
-programmer.
+programmer.
L<perl_community>
View
2 sections/closures.pod
@@ -84,8 +84,6 @@ lexical environment:
=end programlisting
-=begin sidebar
-
Because C<make_iterator()> does not return these lexicals by value or by
reference, no other Perl code besides the closure can access them. They're
encapsulated as effectively as any other lexical encapsulation, although any
View
4 sections/context_philosophy.pod
@@ -162,7 +162,7 @@ data. You've probably already noticed that Perl's flexible about figuring out
if you have a number or a string and converting between the two as you want
them. In exchange for not having to declare (or at least track) explicitly what
I<type> of data a variable contains or a function produces, Perl's type
-contexts that tell the compiler how to treat data.
+contexts provide hints that tell the compiler how to treat data.
X<builtins; C<eq>>
@@ -197,7 +197,7 @@ X<builtins; C<==>>
The C<eq> operator treats its operands as strings by enforcing I<string
context> on them. The C<==> operator imposes I<numeric context>. In numeric
-context, both strings evaluate to numbers C<0> (L<numeric_coercion>).
+context, both strings evaluate to C<0> (L<numeric_coercion>).
X<boolean context>
X<context; boolean>
View
22 sections/control_flow.pod
@@ -346,6 +346,7 @@ using an undefined value might raise a warning:
=begin programlisting
+ my $barbeque;
if (defined $barbeque and $barbeque eq 'pork shoulder') { ... }
=end programlisting
@@ -710,13 +711,34 @@ C<@values> array by modifying the array with each loop iteration:
=begin programlisting
+ while (@values)
+ {
+ my $value = shift @values;
+ say $value;
+ }
+
+=end programlisting
+
+=begin sidebar
+
+Modifying C<@values> inside of the C<while> condition check also works, but it
+has some subtleties related to the truthiness of each value.
+
+=begin programlisting
+
while (my $value = shift @values)
{
say $value;
}
=end programlisting
+This loop will exit as soon as it reaches an element that evaluates to a false
+value, not necessarily when it has exhausted the array. That may be the desired
+behavior, but is often surprising to novices.
+
+=end sidebar
+
X<loops; C<until>>
The I<until> loop reverses the sense of the test of the C<while> loop.
View
40 sections/cpan.pod
@@ -69,26 +69,34 @@ X<CPAN; C<CPAN.pm>>
X<CPAN; C<CPANPLUS>>
Modern Perl installations include two clients to connect to, search, download,
-build, test, and install CPAN distributions, CPAN.pm and CPANPLUS. A newer
-alternative is also available, though it is not part of the core distribution.
-For the most part, each of these clients is equivalent for basic installation.
-This book recommends the use of CPAN.pm solely due to its ubiquity. With a
-recent version (as of this writing, 1.9800 is the latest stable release),
-module installation is reasonably easy. Start the client with:
+build, test, and install CPAN distributions, CPAN.pm and CPANPLUS. For the most
+part, each of these clients is equivalent for basic installation. This book
+recommends the use of CPAN.pm solely due to its ubiquity. With a recent version
+(as of this writing, 1.9800 is the latest stable release), module installation
+is reasonably easy. Start the client with:
-=begin programlisting
+=begin screen
$ B<cpan>
-=end programlisting
+=end screen
-To install a distribution:
+To install a distribution within the client:
-=begin programlisting
+=begin screen
+
+ $ B<cpan>
+ cpan[1]> B<install Modern::Perl>
+
+=end screen
+
+... or to install directly from the command line:
+
+=begin screen
$ B<cpan Modern::Perl>
-=end programlisting
+=end screen
X<CPAN; C<CPAN.pm>>
@@ -118,25 +126,25 @@ projects help to make this possible.
C<App::cpanminus> is a relatively new CPAN client with goals of speed,
simplicity, and zero configuration. Install it with C<cpan App::cpanminus>, or:
-=begin programlisting
+=begin screen
$ B<curl -LO http://xrl.us/cpanm>
$ B<chmod +x cpanm>
-=end programlisting
+=end screen
C<App::perlbrew> is a system to manage and to switch between your own
installations of multiple versions and configurations of Perl. Installation is
as easy as:
-=begin programlisting
+=begin screen
$ B<curl -LO http://xrl.us/perlbrew>
$ B<chmod +x perlbrew>
$ B<./perlbrew install>
$ B<perldoc App::perlbrew>
-=end programlisting
+=end screen
X<CPAN; local::lib>
X<CPAN; App::local::lib::helper>
@@ -145,7 +153,7 @@ The C<local::lib> CPAN distribution allows you to install and to manage
distributions in your own user directory, rather than for the system as a
whole. This is an effective way to maintain CPAN distributions without
affecting other users. Installation is somewhat more involved than the previous
-two distributions, though C<App::local::lib::helper> can simplify. See
+two distributions, though C<App::local::lib::helper> can simplify the process. See
U<http://search.cpan.org/perldoc?local::lib> and
U<http://search.cpan.org/perldoc?App::local::lib::helper> for more details.
View
32 sections/expressivity.pod
@@ -64,24 +64,19 @@ X<baby Perl>
Perl's expressivity also allows novices to write useful programs without having
to understand everything. The resulting code is often called I<baby Perl>, in
the sense that most everyone wants to help babies learn to communicate well.
-Everyone begins as a novice. Through practice and leaning from more experienced
+Everyone begins as a novice. Through practice and learning from more experienced
programmers, you will understand and adopt more powerful idioms and techniques.
-For example, a Perl novice might triple a list of numbers by writing:
+For example, an experienced Perl hacker might triple a list of numbers by
+writing:
=begin programlisting
- my @tripled;
- my $count = @numbers;
-
- for (my $i = 0; $i < $count; $i++)
- {
- $tripled[$i] = $numbers[$i] * 3;
- }
+ my @tripled = map { $_ * 3 } @numbers;
=end programlisting
-A Perl adept might write:
+... and a Perl adept might write:
=begin programlisting
@@ -94,17 +89,26 @@ A Perl adept might write:
=end programlisting
-An experienced Perl hacker might write:
+... while a novice might start with:
=begin programlisting
- my @tripled = map { $_ * 3 } @numbers;
+ my @tripled;
+ my $count = @numbers;
+
+ for (my $i = 0; $i < $count; $i++)
+ {
+ $tripled[$i] = $numbers[$i] * 3;
+ }
=end programlisting
+All three approaches accomplish the same thing, but each takes advantage of
+Perl in a different way.
+
Experience writing Perl will help you to focus on I<what> you want to do rather
than I<how> to do it. Even so, Perl will happily run simple programs. You can
design and refine your programs for clarity, expressivity, reuse, and
maintainability, in part or in whole. Take advantage of this flexibility and
-pragmatism: it's far better to accomplish your task effectively now than to write a
-conceptually pure and beautiful program next year.
+pragmatism: it's far better to accomplish your task effectively now than to
+write a conceptually pure and beautiful program next year.
View
2 sections/files.pod
@@ -65,8 +65,6 @@ Z<file_modes_table>
=headrow
-=row
-
=cell Symbols
=cell Explanation
View
6 sections/functions.pod
@@ -133,8 +133,8 @@ code uses C<shift> or list unpacking:
=begin sidebar
-Remember that the array builtins default to C<@_> as operand within functions.
-Take advantage of this idiom.
+Remember that the array builtins use C<@_> as the default operand I<within
+functions>. Take advantage of this idiom.
=end sidebar
@@ -245,7 +245,7 @@ immediately followed by its value. Hash assignment inside C<show_pets()> works
essentially as the more explicit assignment to C<%pet_names_and_types> does.
This flattening is often useful, but beware of mixing scalars with flattened
-aggregates in parameter lists. To write C<show_pets_of_type()> function, where
+aggregates in parameter lists. To write a C<show_pets_of_type()> function, where
one parameter is the type of pet to display, pass that type as the I<first>
parameter (or use C<pop> to remove it from the end of C<@_>):
View
4 sections/globals.pod
@@ -123,7 +123,9 @@ reading input a line at a time. By default, this is your platform-specific
newline character sequence. If you undefine this value, Perl will attempt to
read the entire file into memory. If you set this value to a I<reference> to an
integer, Perl will try to read that many I<bytes> per record (so beware of
-Unicode concerns).
+Unicode concerns). If you set this value to an empty string (C<''>), Perl will
+read in a paragraph at a time, where a paragraph is a chunk of text followed by
+an arbitrary number of newlines.
X<C<$.>>
X<global variables; C<$.>>
View
4 sections/handling_warnings.pod
@@ -57,11 +57,11 @@ X<C<Carp>; verbose>
C<Carp>'s verbose mode adds backtraces to all warnings produced by C<carp()> and C<croak()> (L<reporting_errors>) throughout the entire program:
-=begin programlisting
+=begin screen
$ perl -MCarp=verbose my_prog.pl
-=end programlisting
+=end screen
Use C<Carp> when writing modules (L<modules>) instead of C<warn> or C<die>.
View
10 sections/hashes.pod
@@ -7,9 +7,9 @@ X<hashes>
A I<hash> is a first-class Perl data structure which associates string keys
with scalar values. In the same way that the name of a variable corresponds to
a storage location, a key in a hash refers to a value. Think of a hash like you
-would a telephone book: use your friend's name to look up her number. Other
-languages call hashes I<tables>, I<associative arrays>, I<dictionaries>, or
-I<maps>.
+would a telephone book: use the names of your friends to look up their numbers.
+Other languages call hashes I<tables>, I<associative arrays>, I<dictionaries>,
+or I<maps>.
Hashes have two important properties: they store one scalar per unique key and
they provide no specific ordering of keys.
@@ -438,7 +438,7 @@ you can safely ignore.
In list context, a hash evaluates to a list of key/value pairs similar to what
you receive from the C<each> operator. However, you I<cannot> iterate over
this list the same way you can iterate over the list produced by C<each>, lest
-the loop never terminate:
+the loop will never terminate:
=begin programlisting
@@ -621,7 +621,7 @@ To prevent someone from accidentally adding a hash key you did not intend
(whether as a typo or from untrusted user input), use the C<lock_keys()>
function to restrict the hash to its current set of keys. Any attempt to add a
new key to the hash will raise an exception. This is lax security suitable only
-for preventing accidents; anyone can use theC<unlock_keys()> function to remove
+for preventing accidents; anyone can use the C<unlock_keys()> function to remove
this protection.
Similarly you can lock or unlock the existing value for a given key in the hash
View
4 sections/idioms.pod
@@ -462,9 +462,7 @@ This technique works on other in-place modification operators:
=begin tip /r in Perl 5.14
Perl 5.14 added the non-destructive substitution modifier C</r>, so that you
-can write:
-
- C<my $normalized_name = $name =~ tr/A-Za-z//dcB<r>;>
+can write C<my $normalized_name = $name =~ tr/A-Za-z//dcB<r>;>.
=end tip
View
2 sections/implicit_ideas.pod
@@ -24,7 +24,7 @@ C<$_> as the variable, but it's often unnecessary.
X<builtins; C<chomp>>
For example, the C<chomp> builtin removes any trailing newline sequence from
-the given stringN<See C<$/> for more precise details of its behavior.>:
+the given stringN<See C<perldoc -f chomp> and C<$/> for more precise details of its behavior.>:
=begin programlisting
View
2 sections/indirect_objects.pod
@@ -109,7 +109,7 @@ For the limited case of filehandle operations, the dative use is so prevalent
that you can use the indirect invocation approach if you surround your intended
invocant with curly brackets. If you're using Perl 5.14 (or if you load
C<IO::File> or C<IO::Handle>), you can use methods on lexical
-filehandlesN<<Almost no one does this for C<print> and C<say> though.>>.
+filehandlesN<Almost no one does this for C<print> and C<say> though.>.
X<CPAN; C<Perl::Critic>>
X<CPAN; C<Perl::Critic::Policy::Dynamic::NoIndirect>>
View
4 sections/packages.pod
@@ -122,11 +122,11 @@ argument:
# require at least 2.1
Some::Plugin->VERSION( 2.1 );
-=end programlisting
-
die "Your plugin $version is too old"
unless $version > 2;
+=end programlisting
+
=head2 Packages and Namespaces
X<namespaces>
View
2 sections/perldoc.pod
@@ -39,7 +39,7 @@ The first example displays the documentation embedded within the C<List::Util>
module. The second example displays a pure documentation file, in this case the
table of contents of the core documentation. The third example displays a pure
documentation file included as part of a CPAN distribution (L<moose>).
-C<perldoc> hides these details; here's no distinction between reading the
+C<perldoc> hides these details; there's no distinction between reading the
documentation for a core library such as C<Data::Dumper> or one installed from
the CPAN.
View
12 sections/prototypes.pod
@@ -38,7 +38,7 @@ The builtin C<prototype> takes the name of a function and returns a string
representing its prototype. Use the C<CORE::> form to see the prototype of a
builtin:
-=begin programlisting
+=begin screen
$ B<perl -E "say prototype 'CORE::push';">
\@@
@@ -47,12 +47,12 @@ builtin:
$ B<perl -E "say prototype 'CORE::open';">
*;$@
-=end programlisting
+=end screen
C<prototype> will return C<undef> for those builtins whose functions you cannot
emulate:
-=begin programlisting
+=begin screen
$ B<perl -E "say prototype 'CORE::system' // 'undef' ">
undef
@@ -62,16 +62,16 @@ emulate:
undef
# Builtin function C<prototype> has no prototype.
-=end programlisting
+=end screen
Remember C<push>?
-=begin programlisting
+=begin screen
$ B<perl -E "say prototype 'CORE::push';">
\@@
-=end programlisting
+=end screen
The C<@> character represents a list. The backslash forces the use of a
I<reference> to the corresponding argument. This prototype means that C<push>
View
10 sections/references.pod
@@ -28,8 +28,8 @@ Consider the alternative. If you had to make copies of every value before
anything could possibly change them out from under you, you'd have to write
lots of extra defensive code.
-Yet sometimes it's useful to modify values in place. If you want to pash a hash
-full of data to a function to modify, creating and returning a new hash for
+Yet sometimes it's useful to modify values in place. If you want to pass a hash
+full of data to a function to modify it, creating and returning a new hash for
each change could be troublesome (to say nothing of inefficient).
X<references>
@@ -82,7 +82,7 @@ dereferencing:
=end programlisting
-The double scalar sigil dereferences a scalar reference.
+The double scalar sigil (C<$$>) dereferences a scalar reference.
=begin sidebar
@@ -217,7 +217,7 @@ scoping. For example:
=begin programlisting
- my @meals = qw( waffles sandwiches pizza );
+ my @meals = qw( soup sandwiches pizza );
my $sunday_ref = \@meals;
my $monday_ref = \@meals;
@@ -229,7 +229,7 @@ scoping. For example:
=begin programlisting
- my @meals = qw( waffles sandwiches pizza );
+ my @meals = qw( soup sandwiches pizza );
my $sunday_ref = [ @meals ];
my $monday_ref = [ @meals ];
View
6 sections/scope.pod
@@ -108,9 +108,9 @@ outer scope hides, or I<shadows>, the outer lexical:
=end programlisting
This program prints C<Edward> and then C<Jacob>N<Family members, not
-vampires.>. Even though redeclaring a lexical variable with the same name and
-type I<in the same lexical scope> produces a warning message, shadowing a
-lexical FIXME. This is a feature of encapsulation.
+vampires.>, even though redeclaring a lexical variable with the same name and
+type I<in the same lexical scope> produces a warning message. Shadowing a
+lexical is a feature of encapsulation.
=begin sidebar
View
4 sections/testing.pod
@@ -116,7 +116,7 @@ that everything passed or the specifics of any failures. The core module
C<Test::Harness> interprets TAP, and its related program C<prove> runs tests
and displays only the most pertinent information:
-=begin programlisting
+=begin screen
$ B<prove truth_values.t>
truth_values.t .. 1/?
@@ -134,7 +134,7 @@ and displays only the most pertinent information:
truth_values.t (Wstat: 512 Tests: 4 Failed: 2)
Failed tests: 2-3
-=end programlisting
+=end screen
That's a lot of output to display what is already obvious: the second and third
tests fail because zero and the empty string evaluate to false. It's easy to
View
18 sections/values.pod
@@ -12,10 +12,10 @@ Where variables allow the abstract manipulation of data, the values they hold
make programs concrete and useful. The more accurate your values, the better
your programs. These values are data--your aunt's name and address, the
distance between your office and a golf course on the moon, or the weight of
-all cookies you've eaten in the past year. Within your program, the rules
-regarding the format of that data are often strict. Effective programs need
-effective (simple, fast, most compact, most efficient) ways of representing
-their data.
+all of the cookies you've eaten in the past year. Within your program, the
+rules regarding the format of that data are often strict. Effective programs
+need effective (simple, fast, most compact, most efficient) ways of
+representing their data.
=head2 Strings
@@ -298,7 +298,7 @@ X<IO layers>
When you tell Perl that a specific filehandle (L<files>) works with encoded
text, Perl will convert the incoming octets to Unicode strings automatically.
-To do this, add a IO layer to the mode of the C<open> builtin. An I<IO layer>
+To do this, add an IO layer to the mode of the C<open> builtin. An I<IO layer>
wraps around input or output and converts the data. In this case, the C<:utf8>
layer decodes UTF-8 data:
@@ -509,8 +509,8 @@ produce another Unicode string.
If both strings are octet streams, Perl will concatenate them into a new octet
string. If both values are octets of the same encoding--both Latin-1, for
example, the concatenation will work correctly. If the octets do not share an
-encoding, the concatenation append UTF-8 data to Latin-1 data, producing a
-sequence of octets which makes sense in I<neither> encoding. This could happen
+encoding, for example a concatenation appending UTF-8 data to Latin-1 data, then the
+resulting sequence of octets makes sense in I<neither> encoding. This could happen
if the user entered a name as UTF-8 data and the greeting were a Latin-1 string
literal, but the program decoded neither.
@@ -567,8 +567,8 @@ X<C<0>>
X<C<0x>>
The emboldened characters are the numeric prefixes for binary, octal, and hex
-notation respectively. Be aware that a leading zero I<always> indicates octal
-mode.
+notation respectively. Be aware that a leading zero on an integer I<always>
+indicates octal mode.
X<numbers; underscore separator>
X<underscore>

0 comments on commit bff0097

Please sign in to comment.