Simplifies text parsing. Extensible to parse various grammars
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib/Text
t
.gitignore
.mailmap
.perltidyrc
.travis.yml
CODE_OF_CONDUCT.md
CONTRIBUTING.md
Changes
README.pod
dist.ini
tidyall.ini
weaver.ini

README.pod

NAME

Text::Parser - Simplifies text parsing. Easily extensible to parse various text formats.

VERSION

version 0.910

SYNOPSIS

use Text::Parser;

my $parser = Text::Parser->new();
$parser->read(shift @ARGV);
print $parser->get_records, "\n";

The above code reads the first command-line argument as a string, and assuming it is the name of a text file, it will print the content of the file to STDOUT. If the string is not the name of a text file it will throw an exception and exit.

RATIONALE

Text parsing is perhaps the single most common thing that almost every Perl program does. Yet we don't have a lean, flexible, text parser. A simple text parser should have to only specify the "grammar" it intends to interpret and collect records from. Everything else, like opening a file handle, closeing the file handle, tracking line-count, joining continued lines into one, reporting any errors in line continuation, etc., distract from the main goal : getting data records from the text input. Unfortunately, most programmers have to continue writing code that should just have been simple features of every text file parser. And if they have to read a second file with a different grammar, usually, all that code needs to be repeated.

This class automates all "mundane" operations like open, close, line-count, and storage/deletion/retrieval of records, joining continued lines, etc. You don't have to bother with a lot of book-keeping when you write your parser. You focus on specifying a grammar and telling the parser what information to store. To do this, you just inherit this class and override one method (save_record). And voila! you have a parser. Everything else is taken care of by this class. Look at these examples to see how easy this can be. If your text format allows a single line to be split into several lines with a continuation character, you again need to specify only a few additional things, and everything else is taken care of for you. See these examples.

DESCRIPTION

Text::Parser is a bare-bones text parsing class. It is ignorant of the text format, and cannot recognize any grammars, but derived classes that inherit from it can specify this. They can do this usually by overriding just one of the methods in this class. Of course derived classes can create any additional attributes and methods they need to do their task of extracting information records out of each line.

Future versions are expected to include progress-bar support, parsing text from sockets, UTF support, or parsing from a chunk of memory. All these software features are text-format independent and can be re-used in parsing any text format. Derived classes of Text::Parser will be able to take advantage of these features seamlessly and only have to focus on extracting information, while the base class handles the "mundane" parts.

CONSTRUCTOR

new

Takes options in the form of a hash. Throws an exception if you use wrong inputs to create an object. You can thus create an object of a parser like this.

my $parser = Text::Parser->new(
    auto_chomp     => 0,           # 0 (Default) or 1
                                   #   - automatically chomp lines
    multiline_type => 'join_last', # 'join_last'|'join_next'|undef ; Default: undef
    auto_trim      => 'b',         # 'l' (left), 'r' (right), 'b' (both), 'n' (neither) (Default)
                                   #   - automatically trim leading and trailing whitespaces
);

This $parser variable will be used in examples below.

ATTRIBUTES

multiline_type

This method replaces the older setting method. It is a read-write accessor method for the multiline_type attribute.

my $mult = $parser->multiline_type;
print "Parser is a multi-line parser of type: $mult" if defined $mult;

$parser->multiline_type(undef);
                    # setting this to undef will throw an exception if it was previously set to a real value like
                    # 'join_next' or 'join_last'. In this case, since $parser was of 'join_last' type, there will
                    # be an exception
$parser->multiline_type('join_next');
                    # Changes the parser to a multiline parser of type 'join_next'
                    # This is okay.

What value should I choose?

If your text format allows users to break up what should be on a single line into another line using a continuation character, you need to use the multiline_type option. The option tells the parser to join lines back into a single line, so that your save_record method doesn't have to bother about joining the continued lines, stripping any continuation characters, line-feeds etc. There are two variations in this:

  • If your format allows something like a trailing back-slash or some other character to indicate that text on next line is to be joined with this one, then choose join_next. See this example.

  • If your format allows some character to indicate that text on the current line is part of the last line, then choose join_last. See this simple SPICE line-joiner as an example. Note: If you have no continuation character, but you want to just join all the lines into one single line and then call save_record only once for the whole text block, then use join_last. See this trivial line-joiner.

Remember that join_next multi-line parsers will blindly look for input to be continued on the next line, even if EOF has been reached. This means, if you want to "slurp" a file into a single large string, without any continuation characters, you must use the join_last multi-line type.

auto_chomp

This method replaces the older setting method. It is a read-write accessor method for the auto_chomp attribute. It takes a boolean value as parameter.

print "Parser will chomp lines automatically\n" if $parser->auto_chomp;

auto_trim

Read-write accessor method for the auto_trim attribute. The values this can take are shown under the new constructor also.

$parser->auto_trim('l');       # 'l' (left), 'r' (right), 'b' (both), 'n' (neither) (Default)

lines_parsed

Takes no arguments. Returns the number of lines last parsed. A line is reckoned when the \n character is encountered.

print $parser->lines_parsed, " lines were parsed\n";

The value is auto-updated during the execution of read. See this example of how this can be used in derived classes.

Again the information in this is "persistent". But you can also be assured that every time you call read, the value be auto-reset before parsing.

METHODS

read

Takes zero or one argument which could be a string containing the name of the file, or a filehandle reference (a GLOB) like \*STDIN or an object of the FileHandle class. Throws an exception if filename/GLOB provided is either non-existent or cannot be read for any reason.

Note: Normally if you provide the GLOB of a file opened for write, some Operating Systems allow reading from it too, and some don't. Read the documentation for filehandle for more on this.

$parser->read($filename);

# The above is equivalent to the following
$parser->filename($filename);
$parser->read();

# You can also read from a previously opened file handle directly
$parser->filehandle(\*STDIN);
$parser->read();

Returns once all records have been read or if an exception is thrown for any parsing errors, or if reading has been aborted with the abort_reading method.

If you provide a filename as input, the function will handle all open and close operations on files even if any exception is thrown, or if the reading has been aborted. But if you pass a file handle GLOB or FileHandle object instead, then the file handle won't be closed and it will be the responsibility of the calling program to close the filehandle.

$parser->read('myfile.txt');
# Will handle open, parsing, and closing of file automatically.

open MYFH, "<myfile.txt" or die "Can't open file myfile.txt at ";
$parser->read(\*MYFH);
# Will not close MYFH and it is the respo
close MYFH;

When you do read a new file name or file handle with this method, you will lose all the records stored from the previous read operation. So this means that if you want to read a different file with the same parser object, (unless you don't care about the records from the last file you read) you should use the get_records method to retrieve all the read records before parsing a new file. So all those calls to read in the example above were parsing three different files, and each successive call overwrote the records from the previous call.

$parser->read($file1);
my (@records) = $parser->get_records();

$parser->read(\*STDIN);
my (@stdin) = $parser->get_records();

Note: To extend the class to other file formats, override save_record instead of this one.

Future Enhancement

At present the read method takes only two possible inputs argument types, either a file name, or a file handle. In future this may be enhanced to read from sockets, subroutines, or even just a block of memory (a string reference). Suggestions for other forms of input are welcome.

filename

Takes zero or one string argument containing the name of a file. Returns the name of the file that was last opened if any. Returns undef if no file has been opened.

print "Last read ", $parser->filename, "\n";

The file name is "persistent" in the object. Meaning, even after you have called read once, it still remembers the file name. So you can do this:

$parser->read(shift @ARGV);
print $parser->filename(), ":\n",
      "=" x (length($parser->filename())+1),
      "\n",
      $parser->get_records(),
      "\n";

But if you do a read with a filehandle as argument, you'll see that the last filename is lost - which makes sense.

$parser->read(\*MYFH);
print "Last file name is lost\n" if not defined $parser->filename();

filehandle

Takes zero or one argument that must be either a filehandle GLOB (such as \*STDIN) or an object of the FileHandle class. The method saves it for future a read call. Returns the filehandle last saved, or undef if none was saved. Remember that after a successful read call, filehandles are lost.

my $fh = $parser->filehandle();

Like in the case of filename method, if after you read with a filehandle, you call read again, this time with a file name, the last filehandle is lost.

my $lastfh = $parser->filehandle();
## Will return STDOUT

$parser->read('another.txt');
print "No filehandle saved any more\n" if
                    not defined $parser->filehandle();

get_records

Takes no arguments. Returns an array containing all the records saved by the parser.

foreach my $record ( $parser->get_records ) {
    $i++;
    print "Record: $i: ", $record, "\n";
}

has_aborted

Takes no arguments, returns a boolean to indicate if text reading was aborted in the middle.

print "Aborted\n" if $parser->has_aborted();

pop_record

Takes no arguments and pops the last saved record.

my $last_rec = $parser->pop_record;
$uc_last = uc $last_rec;
$parser->save_record($uc_last);

last_record

Takes no arguments and returns the last saved record. Leaves the saved records untouched.

my $last_rec = $parser->last_record;

OVERRIDE IN SUBCLASS

save_record

Takes exactly one argument and that is saved as a record. Additional arguments are ignored. If no arguments are passed, then undef is stored as a record.

In an application that uses a text parser, you will most-likely never call this method directly. It is automatically called within read for each line. In this base class Text::Parser, save_record is simply called with a string containing the raw line of text ; i.e. the line of text will not be chomped or modified in any way. Here is a basic example.

Derived classes can decide to store records in a different form. A derived class could, for example, store the records in the form of hash references (so that when you use get_records, you'd get an array of hashes), or maybe even another array reference (so when you use get_records you'd get an array of arrays). The CSV parser example does the latter.

line_auto_manip

A method that could be overridden to manipulate each line before it gets to save_record method. Because this is called before the save_record method, it is called even before the Text::Parser::Multiline role can be called. You will almost never call this method in a program directly but might use it in subclasses.

The default implementation chomps lines (if auto_chomp is true) and trims leading/trailing whitespace (if auto_trim is not 'n').

If you override this method, remember that it takes a string as input and returns a string.

DON'T OVERRIDE IN SUBCLASS

push_records

Don't override this method unless you know what you're doing. This method is useful if you have to copy the records from another parser. It is a general-purpose method for storing records that have been prepared before-hand. It is not supposed to be used to modify the arguments and make records (like save_record does).

$parser->push_records(
    $another_parser->get_records
);

FOR USE IN SUBCLASS

abort_reading

Takes no arguments. Returns 1. You will probably never call this method in your main program.

This method is usually used only in the derived class. See this example.

FOR MULTI-LINE TEXT PARSING

is_line_continued

Takes a string argument. The default method provided will return 0 if the parser is not a multi-line parser. If it is a multi-line parser, return value depends on the type of multiline parser.

If it is of type 'join_last', then it returns 1 for all lines except the first line. This means all lines continue from the previous line (except the first line, because there is no line before that).

But if it is of type 'join_next', then it returns 1 for all lines unconditionally. This means the parser will expect further lines, even when the last line in the text input has been read. Thus you need to have a way to indicate that there is no further continuation. This is why if you are building a trivial line-joiner, you should use the 'join_last' type. See this example.

$parser->is_line_continued();

join_last_line

This method can be overridden in multi-line text parsing. The method takes two string arguments and joins them in a way that removes the continuation character. The default implementation just concatenates two strings and returns the result without removing anything. You should redefine this method to strip any continuation characters and join the strings with any required spaces etc.

$parser->join_last_line('last line', ' + this line');

DEPRECATED

setting

This method has been deprecated. Use multiline_type and auto_chomp instead.

(Note: This deprecated method cannot be used with the auto_trim attribute)

This method will disappear from version 1.0 onwards.

EXAMPLES

The following examples should illustrate the use of inheritance to parse various types of text file formats.

Basic principle

Derived classes simply need to override one method : save_record. With the help of that any arbitrary file format can be read. save_record should interpret the format of the text and store it in some form by calling SUPER::save_record. The main:: program will then use the records and create an appropriate data structure with it.

Notice that the creation of a data structure is not the objective of a parser. It is simply concerned with collecting data and arranging it in a form that can be used. That's all. Data structures can be created by a different part of your program using the data collected by your parser.

Note: There is support for Moose. So you could use extends 'Text::Parser' instead of the use parent pragma in these examples. The examples in this documentation will show non-Moose classic Perl OO derived classes for ease of understanding. Those who know how to use class automators like Moo/Moose should be able to follow.

Example 1 : A simple CSV Parser

We will write a parser for a simple CSV file that reads each line and stores the records as array references. This example is oversimplified, and does not handle embedded newlines.

package Text::Parser::CSV;
use parent 'Text::Parser';
use Text::CSV;

my $csv;
sub save_record {
    my ($self, $line) = @_;
    $csv //= Text::CSV->new({ binary => 1, auto_diag => 1});
    $csv->parse($line);
    $self->SUPER::save_record([$csv->fields]);
}

That's it! Now in main:: you can write something like this:

use Text::Parser::CSV;

my $csvp = Text::Parser::CSV->new();
$csvp->read(shift @ARGV);
foreach my $aref ($csvp->get_records) {
    my (@arr) = @{$aref};
    print "@arr\n";
}

The above program reads the content of a given CSV file and prints the content out in space-separated form.

Example 2 : Error checking

It is easy to add any error checks using exceptions. One of the easiest ways to do this is to use Exception::Class. We'll modify the CSV parser above to demonstrate that.

package Text::Parser::CSV;
use Exception::Class (
    'Text::Parser::CSV::Error', 
    'Text::Parser::CSV::TooManyFields' => {
        isa => 'Text::Parser::CSV::Error',
    },
);

use parent 'Text::Parser';
use Text::CSV;

my $csv;
sub save_record {
    my ($self, $line) = @_;
    $csv //= Text::CSV->new({ binary => 1, auto_diag => 1});
    $csv->parse($line);
    my @fields = $csv->fields;
    $self->{__csv_header} = \@fields if not scalar($self->get_records);
    Text::Parser::CSV::TooManyFields->throw(error => "Too many fields on line #" . $self->lines_parsed)
        if scalar(@fields) > scalar(@{$self->{__csv_header}});
    $self->SUPER::save_record(\@fields);
}

The Text::Parser class will close all filehandles automatically as soon as an exception is thrown from save_record. You can catch the exception in main:: as you would normally, by useing Try::Tiny or other such class.

Example 3 : Aborting without errors

We can also abort parsing a text file without throwing an exception. This could be if we got the information we needed. For example:

package Text::Parser::SomeFile;
use parent 'Text::Parser';

sub save_record {
    my ($self, $line) = @_;
    my ($leading, $rest) = split /\s+/, $line, 2;
    return $self->abort_reading() if $leading eq '**ABORT';
    return $self->SUPER::save_record($line);
}

In this derived class, we have a parser Text::Parser::SomeFile that would save each line as a record, but would abort reading the rest of the file as soon as it reaches a line with **ABORT as the first word. When this parser is given the following file as input:

somefile.txt:

Some text is here.
More text here.
**ABORT reading
This text is not read
This text is not read
This text is not read
This text is not read

You can now write a program as follows:

use Text::Parser::SomeFile;

my $par = Text::Parser::SomeFile->new();
$par->read('somefile.txt');
print $par->get_records(), "\n";

The output will be:

Some text is here.
More text here.

Example 4 : Multi-line parsing

Some text formats allow users to split a line into several lines with a line continuation character (usually at the end or the beginning of a line).

Trivial line-joiner

Below is a trivial example where all lines are joined into one:

use strict;
use warnings;
use Text::Parser;

my $join_all = Text::Parser->new(auto_chomp => 1, multiline_type => 'join_last');
$join_all->read('input.txt');
print $join_all->get_records(), "\n";

Another trivial example is here.

Continue with character

(Pun intended! ;-))

In the above example, all lines are joined (indiscriminately). But most often text formats have a continuation character that specifies that the line continues to the next line, or that the line is a continuation of the previous line. Here's an example parser that treats the back-slash (\) character as a line-continuation character:

package MyMultilineParser;
use parent 'Text::Parser';
use strict;
use warnings;

sub new {
    my $pkg = shift;
    $pkg->SUPER::new(multiline_type => 'join_next');
}

sub is_line_continued {
    my $self = shift;
    my $line = shift;
    chomp $line;
    return $line =~ /\\\s*$/;
}

sub join_last_line {
    my $self = shift;
    my ($last, $line) = (shift, shift);
    chomp $last;
    $last =~ s/\\\s*$/ /g;
    return $last . $line;
}

1;

In your main::

use MyMultilineParser;
use strict;
use warnings;

my $parser = MyMultilineParser->new();
$parser->read('multiline.txt');
print "Read:\n"
print $parser->get_records(), "\n";

Try with the following input multiline.txt:

Garbage In.\
Garbage Out!

When you run the above code with this file, you should get:

Read:
Garbage In. Garbage Out!

Simple SPICE line joiner

Some text formats allow a line to indicate that it is continuing from a previous line. For example SPICE has a continuation character (+) on the next line, indicating that the text on that line should be joined with the previous line. Let's show how to build a simple SPICE line-joiner. To build a full-fledged parser you will have to specify the rich and complex grammar for SPICE circuit description.

use TrivialSpiceJoin;
use parent 'Text::Parser';

use constant {
    SPICE_LINE_CONTD => qr/^[+]\s*/,
    SPICE_END_FILE   => qr/^\.end/i,
};

sub new {
    my $pkg = shift;
    $pkg->SUPER::new(auto_chomp => 1, multiline_type => 'join_last');
}

sub is_line_continued {
    my ( $self, $line ) = @_;
    return 0 if not defined $line;
    return $line =~ SPICE_LINE_CONTD;
}

sub join_last_line {
    my ( $self, $last, $line ) = ( shift, shift, shift );
    return $last if not defined $line;
    $line =~ s/^[+]\s*/ /;
    return $line if not defined $last;
    return $last . $line;
}

sub save_record {
    my ( $self, $line ) = @_;
    return $self->abort_reading() if $line =~ SPICE_END_FILE;
    $self->SUPER::save_record($line);
}

Try this parser with a SPICE deck with continuation characters and see what you get. Try having errors in the file. You may now write a more elaborate method for save_record above and that could be used to parse a full SPICE file.

SEE ALSO

BUGS

Please report any bugs or feature requests on the bugtracker website http://github.com/balajirama/Text-Parser/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

Balaji Ramasubramanian <balajiram@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018-2019 by Balaji Ramasubramanian.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

CONTRIBUTOR

H.Merijn Brand - Tux <h.m.brand@xs4all.nl>