Text::Parser::Manual - A manual for the Text::Parser class
version 1.000
Jump right here for a quickstart!
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.
open
close
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.
while
# do something for each line ...
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.
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.
This manual is divided into chapters:
Comparing with native Perl - compares native Perl solutions against Text::Parser lists some of the pros and cons of both.
The Extended AWK Syntax - this chapter outlines the syntax for the rules
Collected Examples - a collection of examples using Text::Parser. This will need to be expanded.
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.
Balaji Ramasubramanian <balajiram@cpan.org>
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.
To install Text::Parser, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Text::Parser
CPAN shell
perl -MCPAN -e shell install Text::Parser
For more information on module installation, please visit the detailed CPAN module installation guide.