/ 
Text-Parser-1.000
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 1.000

SYNOPSIS

use Text::Parser;

my $parser = Text::Parser->new();
$parser->add_rule(
    if               => '$1 eq "NAME:"',      # Some condition string
    do               => '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
);
$parser->read(shift);

DESCRIPTION

This class is never used directly. Instead rules are created and managed in one of two ways:

In both cases, the arguments are the same.

METHODS

condition

Read-write attribute accessor method. Returns a string with the condition string as supplied to the if clause in the constructor.

my $cond_str = $rule->condition();

Or modify the condition of a given rule:

$rule->condition($new_condition);

action

Read-write accessor method for the do clause of the rule. This is similar to the condition accessor method.

my $act_str = $rule->action;
$rule->action($modified_action);

dont_record

Read-write boolean accessor method for the dont_record attribute of the constructor.

print "This rule will not record\n" if $rule->dont_record;

continue_to_next

Read-write boolean accessor method for the continue_to_next attribute in the constructor.

print "Continuing to the next rule\n" if $rule->continue_to_next;

add_precondition

Method that can be used to add more pre-conditions to a rule

$rule->add_precondition('looks_like_number($1)');
# Check if the first field on line is a number

When you call test on the rule, it tests all the pre-conditions and the regular condition. If any of them fail, the test returns a boolean false.

This method is very useful when you clone a rule.

test

Method called internally in Text::Parser. Runs code in if block.

print "I will run the task of the rule\n" if $rule->test;

run

Method called internally in Text::Parser. Runs code in do block, and saves the result as a record depending on dont_record.

my $result = $rule->run();

CONSTRUCTOR

new

Instances of this class can be created using the new constructor, but normally a user would never create a rule themselves:

my $rule = Text::Parser::Rule->new(
    if               => '# some condition string', 
    do               => '# some task rule', 
        # At least one of the above two clauses must be specified
        # When not specified, if clause defaults to 1
        # When not specified, do clause defaults to 'return $_;'
    dont_record      => 1, # default: 0
    continue_to_next => 1, # default: 0
);

clone

You can clone a rule and construct another rule from it.

$new_rule = $rule->clone();
 # Just creates a clone of $rule.

The above is not particularly useful as it just creates a copy of the same rule. In the below example, we demonstrate that any of the four main attributes of a rule could be changed while creating a clone. For example:

$rule = Text::Parser::Rule->new(
    if               => '# some condition',
);
$new_rule = $rule->clone(
    # all of these are optional
    do               => '# modify original action', 
    dont_record      => 1, 
    continue_to_next => 1,
);

You could also change the if clause above, but you could also add a pre-condition at the time of creating $new_rule without affecting $rule itself:

$new_rule = $rule->clone(
    add_precondition => '# another condition',
    # ...
);

The clone method is just another way to create a rule. It just uses an existing rule as a seed.

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.