Front page | perl.perl5.porters |
Postings from May 2003
Re: [PATCH] perlsyn.pod Revamp (take 2)
From:
Casey West
Date:
May 12, 2003 14:44
Subject:
Re: [PATCH] perlsyn.pod Revamp (take 2)
Message ID:
20030512214854.GB72887@geeknest.com
It was Saturday, May 10, 2003 when Shlomi Fish took the soap box, saying:
: --- bleadperl/pod/perlsyn.pod 2003-04-27 03:07:07.000000000 +0300
: +++ modified/pod/perlsyn.pod 2003-05-10 09:43:20.000000000 +0300
: @@ -5,28 +5,26 @@
: =head1 DESCRIPTION
:
: A Perl script consists of a sequence of declarations and statements.
: -The sequence of statements is executed just once, unlike in B<sed>
: -and B<awk> scripts, where the sequence of statements is executed
: -for each input line. While this means that you must explicitly
: -loop over the lines of your input file (or files), it also means
: -you have much more control over which files and which lines you look at.
: -(Actually, I'm lying--it is possible to do an implicit loop with
: -either the B<-n> or B<-p> switch. It's just not the mandatory
: -default like it is in B<sed> and B<awk>.)
: +The statements are executed one by one. This is unlike B<awk> or
: +B<sed> (in case you are familiar with these tools) where the sequence
: +of statements is executed for each input line. While it is possible
: +to emulate this behavior, using the B<-n> or B<-p> switches, the
: +default is to follow the standard of traditional imperative
: +languages.
Well, you're trying to change the meaning completley. perlsyn is
currently trying to say that "the program" will be executed once in
its entirety, and that set and awk execute the program multiple times
in its entirety. Your change would lead me to believe that sed and
awk do not execute their statements one-by-one, and that's just not
true.
: Perl is, for the most part, a free-form language. (The only exception
: to this is format declarations, for obvious reasons.) Text from a
: C<"#"> character until the end of the line is a comment, and is
: -ignored. If you attempt to use C</* */> C-style comments, it will be
: -interpreted either as division or pattern matching, depending on the
: -context, and C++ C<//> comments just look like a null regular
: -expression, so don't do that.
: +ignored. C-style C</* */> or C++ C<//> comments will do something else
: +entirely, so don't use them (and I mean it).
This removed important details that explain why you shouldn't use C or
C++ style comments. It's probably not a good idea to remove details
from documentation.
: =head2 Declarations
:
: The only things you need to declare in Perl are report formats
: -and subroutines--and even undefined subroutines can be handled
: -through AUTOLOAD. A variable holds the undefined value (C<undef>)
: +and subroutines. (Undefined subroutines can be handled
: +through the AUTOLOAD feature as documented in L<perlsub>)
: +
: +A variable holds the undefined value (C<undef>)
: until it has been assigned a defined value, which is anything
: other than C<undef>. When used as a number, C<undef> is treated
: as C<0>; when used as a string, it is treated the empty string,
This is good.
: @@ -100,6 +98,23 @@
: until EXPR
: foreach EXPR
:
: +C<if> executes a block of statements (or a single statement) once
: +if C<EXPR> evaluated to a true value. C<unless> executes it once if
: +it did not. A false value is C<undef>, 0, the empty string, and the
Specify "it".
: +floating number 0.0. A true value is everything else. Normally,
: +you'll wish to use comparison operators (C<==>, C<eq>, C<<<=>>, C<gt>
: +or friends), regular expression matches or other mechanisms that
: +explicitly return a true or false value as a boolean expression
: +there.
Overall this paragraph seems to narrow the scope of possibilities in a
program too much. That is, the description tries to second guess the
programmer and that will confuse the reader.
: +
: +C<while> and C<until> repeat the same block of statements while or
: +until it is true. (I.e.: C<until> iterates while it is false)
: +The C<while> and C<until> modifiers have the usual "C<while> loop"
: +semantics (conditional evaluated first), except when applied to a
: +C<do>-BLOCK (or to the deprecated C<do>-SUBROUTINE statement), in
: +which case the block executes once before the
: +conditional is evaluated. This is so that you can write loops like:
What is "it?". Do we need to document deprications in new
documenatation patches? Loops like what?
: +
: The C<if> and C<unless> modifiers have the expected semantics,
: presuming you're a speaker of English. The C<foreach> modifier is an
: iterator: For each value in EXPR, it aliases C<$_> to the value and
: @@ -141,6 +156,10 @@
: it. Future versions of perl might do something different from the
: version of perl you try it out on. Here be dragons.
:
: +Finally, the C<foreach> modifier is an iterator: For each value
: +in EXPR, it aliases the special "default" variable C<$_> to the
: +value and executes the statement.
: +
This is already documented in perlsyn. You added the same wording
here but did not remove it's use earlier in the file.
: =head2 Compound statements
:
: In Perl, a sequence of statements that defines a scope is called a block.
: @@ -195,7 +214,10 @@
: conditional is about to be evaluated again, just like the third part of a
: C<for> loop in C. Thus it can be used to increment a loop variable, even
: when the loop has been continued via the C<next> statement (which is
: -similar to the C C<continue> statement).
: +similar to the C C<continue> statement). Note that C<continue> in C
: +and C<continue> in Perl do entirely different things. Fortunately, if
: +one is used in place of the other by mistake it is likely to be a syntax
: +error.
We don't really need to mention that Perl and C are different at the
syntax level, that's given. Furter, we already talk about the
differences (and similarities) between Perl and C continue within
perlsyn.
:
: =head2 Loop Control
:
: @@ -558,7 +580,8 @@
: The C<goto>-LABEL form finds the statement labeled with LABEL and resumes
: execution there. It may not be used to go into any construct that
: requires initialization, such as a subroutine or a C<foreach> loop. It
: -also can't be used to go into a construct that is optimized away. It
: +also can't be used to go into a construct that is optimized away at
: +the compilation stage, like an C<if (0) { ... }> block. It
: can be used to go almost anywhere else within the dynamic scope,
: including out of subroutines, but it's usually better to use some other
: construct such as C<last> or C<die>. The author of Perl has never felt the
Again, you're trying to remove important details.
Casey West
--
Shooting yourself in the foot with MasPar
You shoot all of your friends' feet simultaneously.