Text::Parser::Rule - Makes it possible to write AWK-style parsing rules for Text::Parser
version 0.927
Users should not use this class directly to create and run rules. See Text::Parser::Manual::ExtendedAWKSyntax for instructions on creating rules in a class. But the example below shows the way this class works for those that intend to improve the class.
use Text::Parser::Rule; use Text::Parser; # To demonstrate use with Text::Parser use Data::Dumper 'Dumper'; # To print any records my $rule = Text::Parser::Rule->new( if => '$1 eq "NAME:"', do => '${2+}' ); # Must have auto_split attribute set - this is automatically done by # the add_rule method of Text::Parser my $parser = Text::Parser->new(auto_split => 1); # Example of how internally the $parser would run the $rule # This code below won't really run any rules because rules # have to be applied when the $parser->read() method is called # and not outside of that $rule->run($parser) if $rule->test($parser); print "Continuing to next rule..." if $rule->continue_to_next;
Takes optional attributes described in ATTRIBUTES section.
my $rule = Text::Parser::Rule->new( condition => '$1 eq "NAME:"', # Some condition string action => 'return $2;', # Some action to do when condition is met dont_record => 1, # Directive to not record continue_to_next => 1, # Directive to next rule till another rule # passes test condition );
The attributes below may be used as options to new constructor. Note that in some cases, the accessor method for the attribute is differently named. Use the attribute name in the constructor and accessor as a method.
new
Read-write attribute. Set in the constructor with if key. Must be string which after transformation must eval successfully without compilation errors.
if
eval
my $rule = Text::Parser::Rule->new( if => 'm//' ); print $rule->action, "\n"; # m// $rule->action('m/something/'); print $rule->action, "\n"; @ m/something/
During a call to test method, this condition is evaluated and the result is returned as a boolean for further decision-making.
test
condition
Read-only attribute. Gets adjusted automatically.
print "Rule requires a minimum of ", $rule->min_nf, " fields on the line.\n";
Read-write attribute. Set in the constructor with do key. Must be string which after transformation must eval successfully without compilation errors.
do
my $rule = Text::Parser->new( do => '' ); print $rule->action, "\n"; # :nothing: $rule->action('return $1'); print $rule->action, "\n"; # return $1
The action is executed during a call to run when condition (and all preconditions) is true. The return value of the evaluated action is used or discarded based on the dont_record attribute.
action
run
dont_record
Boolean indicating if return value of the action (when transformed and evaluated) should be stored in the parser as a record.
print "Will not save records\n" if $rule->dont_record;
The attribute is used in run method. The results of the evaluated action are recorded in the object passed to run. But when this attribute is set to true, then results are not recorded.
Takes a boolean value. This can be set true only for rules with dont_record attribute set to a true value. This attribute indicates that the rule will proceed to the next rule until some rule passes the test. It is easiest to understand the use of this if you imagine a series of rules to test and execute in sequence:
# This code is actually used in Text::Parser # to run through the rules specified foreach my $rule (@rules) { next if not $rule->test($parser); $rule->run($parser); last if not $rule->continue_to_next; }
Takes a list of rule strings that are similar to the condition string. For example:
$rule->add_precondition( '$2 !~ /^ln/', 'looks_like_number($3)', );
During the call to test, these preconditions and the condition will all be combined in the and operation. That means, all the preconditions must be satisfied, and then the condition must be satisfied. If any of them evaluates to a false boolean, test will return false.
and
Takes one argument that must be a Text::Parser. Returns a boolean value may be used to decide to call the run method.
Text::Parser
If all preconditions and condition evaluate to a boolean true, then test returns true.
my $parser = Text::Parser->new(auto_split => 1); $rule->test($parser);
The method will always return a boolean false if the Text::Parser object passed does not have the auto_split attribute on.
auto_split
Takes one argument that must be a Text::Parser, and one optional argument which can be 0 or 1. The default for this optional argument is 1. The 0 value is used when calling a special kind of rule that doesn't need to check for valid current line (mainly useful for BEGIN and END rules). Has no return value.
0
1
BEGIN
END
my $parser = Text::Parser->new(auto_split => 1); $rule->run($parser); $rule->run($parser, 'no_line');
Runs the evaluated action. If dont_record is false, the return value of the action is recorded in $parser. Otherwise, it is ignored.
$parser
"The AWK Programming Language" by Alfred V. Aho, Brian W. Kernighan, and Peter J. Weinberger, Addison-Wesley, 1988. ISBN 0-201-07981-X
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.