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

NAME

Text::Parser::Rule - Makes it possible to write AWK-style parsing rules for Text::Parser

VERSION

version 0.925

SYNOPSIS

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;

CONSTRUCTOR

new

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
);

ATTRIBUTES

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.

condition

Read-write attribute. Set in the constructor with if key. Must be string which after transformation must eval successfully without compilation errors.

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.

min_nf

Read-only attribute. Gets adjusted automatically.

print "Rule requires a minimum of ", $rule->min_nf, " fields on the line.\n";

action

Read-write attribute. Set in the constructor with do key. Must be string which after transformation must eval successfully without compilation errors.

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.

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.

continue_to_next

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;
}

METHODS

add_precondition

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.

test

Takes one argument that must be a Text::Parser. Returns a boolean value may be used to decide to call the run method.

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.

run

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.

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.

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.