Skip to content
Browse files

Applied edits from Matthias Bloch.

  • Loading branch information...
1 parent 95704ce commit 8de89a07b89415fab4a36ad8f0c76cded8e2dcad @chromatic committed
Showing with 61 additions and 54 deletions.
  1. +3 −0 CREDITS
  2. +7 −23 sections/control_flow.pod
  3. +14 −3 sections/hashes.pod
  4. +1 −1 sections/operator_types.pod
  5. +31 −7 sections/references.pod
  6. +5 −20 sections/values.pod
View
3 CREDITS
@@ -155,3 +155,6 @@ E:-?
N: Alexander Scott-Johns
E: alexander.scott.johns@googlemail.com
+
+N: Matthias Bloch
+E: matthias.bloch@puffin.ch
View
30 sections/control_flow.pod
@@ -424,23 +424,14 @@ prints the squares of the integers.
=begin sidebar
-Note that this is described as a I<foreach>-I<style> loop: Perl treats the
-keywords C<foreach> and C<for> interchangeably. As only the I<type> of the
-loop governs its behavior, there are no drawbacks to using the shorter C<for>
-keyword.
+Perl treats the keywords C<foreach> and C<for> interchangeably. The remainder
+of the syntax of the loop determines the behavior of the loop. Though
+experienced Perl programmers tend to refer to the loop with automatic iteration
+as a C<foreach> loop, you can use C<for> safely and clearly any place you might
+want to use C<foreach>.
=end sidebar
-=for author
-
-Previous paragraph:
- "As only the I<type> of the..."
-
-What does "type" mean here? Whether the variable is scalar or array? Or
-syntactic type? (Whatever that means.)
-
-=end for
-
Like C<if> and C<unless>, the C<for> loop has a postfix form:
=begin programlisting
@@ -1193,15 +1184,8 @@ C<log_and_greet_person()>. Returning directly from C<greet_person()> to the
caller of C<log_and_greet_person()> is an optimization known as I<tailcall
optimization>.
-Perl 5 cannot perform this optimization automatically, but you can perform it
-manually.
-
-=for author
-
-What does that mean? Perl won't automatically rearrange your code into a
-tail recursive form, but will automatically detect when it is in that form?
-
-=end for
+Perl 5 will not detect cases where it could perform this optimization
+automatically.
=begin sidebar
View
17 sections/hashes.pod
@@ -63,7 +63,7 @@ X<fat comma>
If you assign an odd number of elements to the hash, you will receive a warning
that the results are not what you anticipated. It's often more obvious to use
the I<fat comma> operator to associate values with keys, as it makes the
-required pairing more visible:
+required pairing more visible. Compare:
=begin programlisting
@@ -74,6 +74,17 @@ required pairing more visible:
=end programlisting
+... to:
+
+=begin programlisting
+
+ my %favorite_flavors = (
+ 'Jacob', 'anything',
+ 'Floyd', 'Pistachio',
+ );
+
+=end programlisting
+
The fat comma operator acts like the regular comma, but it also causes the Perl
parser to treat the previous bareword (L<barewords>) as if it were a quoted
word. The C<strict> pragma will not warn about the bareword, and if you have
@@ -452,8 +463,8 @@ meaningless to Perl programs. You can safely ignore it.
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>.N<The
-loop will loop forever, unless the hash is empty.>.
+this list the same way you can iterate over the list produced by C<each>, as
+the loop will loop forever, unless the hash is empty.
=head2 Hash Idioms
View
2 sections/operator_types.pod
@@ -312,4 +312,4 @@ right operand. In list context, it evaluates both operands in left-to-right
order.
The fat comma operator (C<< => >>) behaves the same way, except that it
-automatically quotes any bareword used as its left operand.
+automatically quotes any bareword used as its left operand (see L<hashes>).
View
38 sections/references.pod
@@ -94,9 +94,9 @@ The double scalar sigil dereferences a scalar reference.
=begin sidebar
This example isn't useful in the obvious case; why not have the function return
-the modified value directly? Even so, scalar references are useful when
-processing I<large> scalars; copying the contents of those scalars can use a
-lot of time and memory.
+the modified value directly? Scalar references are useful when processing
+I<large> scalars; copying the contents of those scalars can use a lot of time
+and memory.
=end sidebar
@@ -127,7 +127,7 @@ reference is a value used as a mostly-unique identifier, as a reference does
not necessarily have a name. Unlike pointers in a language such as C, you
cannot modify the address or treat it as an address into memory.
-These addresses are only mostly unique because Perl may reuse storage
+These addresses are only I<mostly> unique because Perl may reuse storage
locations if its garbage collector has reclaimed an unreferenced reference.
=end sidebar
@@ -204,8 +204,8 @@ C<< my $first_card = B<$$cards_ref[0]>; >>.
=end sidebar
-You can slice an array through its reference with the curly-brace dereference
-grouping syntax:
+Slice an array through its reference with the curly-brace dereference grouping
+syntax:
=begin programlisting
@@ -521,9 +521,33 @@ the source code refer to it, but there's only one I<reference> to it; C<$fh>
itself.) C<$fh> is only in scope in the block and does not get assigned to
anything outside of the block, so when the block ends, its reference count
reaches zero. The recycling of C<$fh> calls an implicit C<close()> method on
-the filehandle, which closes the file.
+the filehandle, which closes the file.
You don't have to understand the details of how all of this works. You only
need to understand that your actions in taking references and passing them
around affect how Perl manages memory. (Though see L<circular_references> for
one caveat.)
+
+=head3 References and Functions
+
+When you use references as arguments to functions, document your intent
+carefully. Modifying the values of a reference from within a function may
+surprise calling code, which expects no modifications.
+
+If you need to perform a destructive operation on the contents of a reference
+without affecting the reference itself, copy its values to a new variable:
+
+=begin programlisting
+
+ my @new_array = @{ $array_ref };
+ my %new_hash = %{ $hash_ref };
+
+=end programlisting
+
+X<Storable>
+X<dclone; Storable>
+
+This is only necessary in a few cases, but it's good policy to be explicit in
+those cases to avoid surprises for the callers. If your references are more
+complex (L<nested_data_structures>), consider the use of the core module
+C<Storable> and its C<dclone> (I<deep cloning>) function.
View
25 sections/values.pod
@@ -25,26 +25,11 @@ meaningless if they couldn't accurately contain the data itself--the values.
X<strings>
A I<string> is a piece of data with no particular formatting, no particular
-contents, and no semantic meaning beyond the fact that it's a string. It could
-be your name. It could be the contents of an image file read from your hard
-drive. It could be the Perl program itself. A string has no meaning to the
-program until you give it meaning. A string is a fixed amount of data
-delineated by quotes of some form, yet Perl strings can grow or shrink as you
-add to or remove from them.
-
-=for author
-
- "...and no semantic meaning beyond the fact that it's a string."
-Not that any data in any program has intrinsic semantic meaning... Humans
-provide that.
-
-You haven't explained what a string actually _is_ yet: text or binary data.
-It is explained lower down, in the "Unicode and Strings" section.
-
- "...Perl strings can grow or shrink as you add to or remove from them."
-Perl strings are values, and so are immutable, aren't they?
-
-=end for
+contents, and no other meaning to the program. It could be your name. It
+could be the contents of an image file read from your hard drive. It could be
+the Perl program itself. A string has no meaning to the program until you give
+it meaning. A string is a fixed amount of data delineated by quotes of some
+form, yet Perl strings can grow or shrink as you add to or remove from them.
The most common string delimiters are single and double quotes:

0 comments on commit 8de89a0

Please sign in to comment.
Something went wrong with that request. Please try again.