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

NAME

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

VERSION

version 1.000

QUICK START

Jump right here for a quickstart!

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 checking if it is a text file, (potentially uncompressing content), calling open, close etc.?

  • parsing line-wrapped files were as simple as setting an attribute, or writing two small routines to unwrap them?

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

  • the code could be re-used for other text formats with same/similar syntax with minor modifications, instead of re-writing the whole thing?

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

Text::Parser accomplishes all of these and more! The programmer needs to specify a set of parsing rules, and the rest is all taken care of.

CHAPTERS

This manual is divided into chapters:

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.