develooper Front page | perl.perl5.porters | Postings from August 2001

[PATCH perlvar.pod] Rewrite $. entry and switch to -> syntax

From:
Ilmari Karonen
Date:
August 19, 2001 20:41
Subject:
[PATCH perlvar.pod] Rewrite $. entry and switch to -> syntax
Message ID:
Pine.SOL.3.96.1010820063126.28048A-100000@simpukka

The following docpatch, based on discussion in comp.lang.perl.misc,
attempts to rewrite the documentation of $. to better match reality and
to be less confusing.

It also changes all the OO syntax entries to use -> instead of indirect
object syntax.  One reason for this is that IMHO the latter should be
considered harmful, but more importantly here, -> gives a syntactic clue
that the items indeed describe method calls.  Something like

  input_line_number HANDLE EXPR

is just three odd words in a row, while

  HANDLE->input_line_number(EXPR) 

looks obviously like a Perl expression, and at least stands out from the
variable names that follow it.  That makes it IMHO much more readable.


--- pod/perlvar.pod.orig	Mon Aug 20 06:28:27 2001
+++ pod/perlvar.pod	Mon Aug 20 06:50:38 2001
@@ -242,7 +242,7 @@
 C<$*> act if C<$* == 0>), while assigning a numerical value to C<$*>
 makes that an implicit C<int> is applied on the value.
 
-=item input_line_number HANDLE EXPR
+=item HANDLE->input_line_number(EXPR)
 
 =item $INPUT_LINE_NUMBER
 
@@ -250,20 +250,33 @@
 
 =item $.
 
-The current input record number for the last file handle from which
-you just read() (or called a C<seek> or C<tell> on).  The value
-may be different from the actual physical line number in the file,
-depending on what notion of "line" is in effect--see C<$/> on how
-to change that.  An explicit close on a filehandle resets the line
-number.  Because C<< <> >> never does an explicit close, line
-numbers increase across ARGV files (but see examples in L<perlfunc/eof>).
-Consider this variable read-only: setting it does not reposition
-the seek pointer; you'll have to do that on your own.  Localizing C<$.>
-has the effect of also localizing Perl's notion of "the last read
-filehandle".  (Mnemonic: many programs use "." to mean the current line
-number.)
+Current line number for the last filehandle accessed. 
 
-=item IO::Handle->input_record_separator EXPR
+Each filehandle in Perl counts the number of lines that have been read
+from it.  (Depending on the value of C<$/>, Perl's idea of what
+constitutes a line may not match yours.)  When a line is read from a
+filehandle (via readline() or C<< <> >>), or when tell() or seek() is
+called on it, C<$.> becomes an alias to the line counter for that
+filehandle.
+
+You can adjust the counter by assigning to C<$.>, but this will not
+actually move the seek pointer.  I<Localizing C<$.> will not localize
+the filehandle's line count>.  Instead, it will localize perl's notion
+of which filehandle C<$.> is currently aliased to.
+
+C<$.> is reset when the filehandle is closed, but B<not> when an open
+filehandle is reopened without an intervening close().  For more
+details, see L<perlop/"I/O Operators">.  Because C<< <> >> never does
+an explicit close, line numbers increase across ARGV files (but see
+examples in L<perlfunc/eof>).
+
+You can also use C<< HANDLE->input_line_number(EXPR) >> to access the
+line counter for a given filehandle without having to worry about
+which handle you last accessed.
+
+(Mnemonic: many programs use "." to mean the current line number.)
+
+=item IO::Handle->input_record_separator(EXPR)
 
 =item $INPUT_RECORD_SEPARATOR
 
@@ -316,7 +329,7 @@
 
 See also L<perlport/"Newlines">.  Also see C<$.>.
 
-=item autoflush HANDLE EXPR
+=item HANDLE->autoflush(EXPR)
 
 =item $OUTPUT_AUTOFLUSH
 
@@ -420,7 +433,7 @@
 
 Use of C<$#> is deprecated.
 
-=item format_page_number HANDLE EXPR
+=item HANDLE->format_page_number(EXPR)
 
 =item $FORMAT_PAGE_NUMBER
 
@@ -430,7 +443,7 @@
 Used with formats.
 (Mnemonic: % is page number in B<nroff>.)
 
-=item format_lines_per_page HANDLE EXPR
+=item HANDLE->format_lines_per_page(EXPR)
 
 =item $FORMAT_LINES_PER_PAGE
 
@@ -441,7 +454,7 @@
 Used with formats.
 (Mnemonic: = has horizontal lines.)
 
-=item format_lines_left HANDLE EXPR
+=item HANDLE->format_lines_left(EXPR)
 
 =item $FORMAT_LINES_LEFT
 
@@ -493,7 +506,7 @@
 
 =back
 
-=item format_name HANDLE EXPR
+=item HANDLE->format_name(EXPR)
 
 =item $FORMAT_NAME
 
@@ -503,7 +516,7 @@
 channel.  Default is the name of the filehandle.  (Mnemonic: brother to
 C<$^>.)
 
-=item format_top_name HANDLE EXPR
+=item HANDLE->format_top_name(EXPR)
 
 =item $FORMAT_TOP_NAME
 

-- 
# Ilmari Karonen -- http://www.sci.fi/~iltzu/
s''n4|9|21|3|n1\2||2|(_-<2_|4_`1|3\3_1\2_|3\3-_)2_|n\__/\_,_|___/\__|2\__,_|_|
1_|\___/\__|_|1_|\___|_|nn4_1\9|3|14|n4__/1-_)2_|1|5\3_`1|2_|1!1/2-_)2_|n3_|1\
___|_|2_|2_|1_|\__,_|\__|_i_\\\___|_|1)n45/n',y/n\n/\n/d,s/\d+/$"x$&/eg,print;






nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About