/ 
Text-Parser-0.925
River stage zero No dependents
/ Text::Parser::Manual

NAME

Text::Parser::Manual - A manual for the Text::Parser class

VERSION

version 0.925

MOTIVATION

Text parsing is perhaps the single most common thing that almost every Perl program does. Yet we don't have a lean, flexible, text parsing utility. Ideally, the developer should only have to specify the "grammar" of the text file she intends to parse. 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, trimming white space, splitting each line into fields, etc., should be automatic.

Unfortunately however, most file parsing code looks like this:

open FH, "<$fname";
my $line_count = 0;
while (<FH>) {
    $line_count++;
    chomp;
    $_ = trim $_;  ## From String::Util
    my (@fields) = split /\s+/;
    # do something for each line ...
}
close FH;

Note that a developer may have to repeat all of the above if she has to read another file with different content or format. And if the target text format allows line-wrapping with a continuation character, it isn't easy to implement it well with the above while loop. Furthermore, the part that is not shown in the above code # do something for each line ... can actually be quite complex with several cascading if-else blocks.

if ($fields[0] eq 'NAME:') {
    # something
} elsif ($fields[0] eq 'ADDRESS:') {
    # something else
} elsif ($fields[0] eq 'EMAIL:') {
.
.
.
} else {
    # finally!
}

There are several problems with this sort of code. For starters, it is:

  • Hard to refactor and simplify into small functions (See "Clean Code" by Robert C. Martin).

  • Cannot be easily modified and re-used for another very similar text format.

  • Complex conditions are harder to write and often result in nested conditions.

  • Documenting code in the while loop can get rather hairy.

VISION

What if:

  • a utility took care of all the "mundane" boilerplate like open, close etc.?

  • parsing line-wrapped files were as simple as writing a small function that joins lines to unwrap?

  • data extraction could be done with a set of self-explanatory rules that don't need to be documented?

  • the resulting code "reads like well-written prose"?

  • developers could easily extend a text parser written by another developer?

Text::Parser can help you accomplish all of these and more!

The programmer needs to specify a set of parsing rules which look quite like AWK. And the rest is all taken care of. So now, a programmer need only focus on the grammar of the file they intend to parse.

CHAPTERS

This manual is divided into chapters:

You can start here.

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.