NaturalDocs::LineReader

An object to handle reading text files line by line in a cross platform manner.  Using this class instead of the standard angle brackets approach has the following benefits:

  • It strips all three types of line breaks automatically: CR/LF (Windows) LF (Unix) and CR (Classic Mac).  You do not need to call chomp().  Perl’s chomp() fails when parsing Windows-format line breaks on a Unix platform anyway.  It leaves the /r on, which screws everything up.
  • It reads Classic Mac files line by line correctly, whereas the Perl version returns it all as one line.
  • It abstracts away ignoring the Unicode BOM on the first line, if present.
Summary
NaturalDocs::LineReaderAn object to handle reading text files line by line in a cross platform manner.
Constants
Members
Functions
NewCreates and returns a new object.
ChompRemoves any line breaks from the end of a value.
StripBOMRemoves the Unicode BOM from the line if present.
GetReturns the next line of text from the file, or undef if there are no more.
GetAllReturns an array of all the lines from the file.

Constants

Members

LINEREADER_FILEHANDLEThe file handle being used to read the file.  Has the LINEREADER_ prefix to make sure it doesn’t conflict with any actual filehandles named FILEHANDLE in the program.
CACHED_LINESAn arrayref of lines already read into memory.
ON_FIRST_LINEWhether we’re about to return the first line or not.

Functions

New

sub New #(filehandle)

Creates and returns a new object.

Parameters

filehandleThe file handle being used to read the file.

Chomp

sub Chomp #(lineRef)

Removes any line breaks from the end of a value.  It does not remove any that are in the middle of it.

Parameters

lineRefA reference to the line to chomp.

StripBOM

sub StripBOM #(lineRef)

Removes the Unicode BOM from the line if present.  Information on it is available at http://www.unicode.org/faq/utf_bom.html#BOM

Parameters

lineRefA reference to the line to strip.

Get

sub Get

Returns the next line of text from the file, or undef if there are no more.  The line break will be removed automatically.  If the first line contains a Unicode BOM, that will also be removed automatically.

GetAll

sub GetAll

Returns an array of all the lines from the file.  The line breaks will be removed automatically.  If the first line contains a Unicode BOM, that will also be removed automatically.

sub New #(filehandle)
Creates and returns a new object.
sub Chomp #(lineRef)
Removes any line breaks from the end of a value.
sub StripBOM #(lineRef)
Removes the Unicode BOM from the line if present.
sub Get
Returns the next line of text from the file, or undef if there are no more.
sub GetAll
Returns an array of all the lines from the file.
Close