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:

• via the add_rule method of Text::Parser

• using applies_rule function from Text::Parser::RuleSpec

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

• Text::Parser

• "The AWK Programming Language" by Alfred V. Aho, Brian W. Kernighan, and Peter J. Weinberger, Addison-Wesley, 1988. ISBN 0-201-07981-X

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.

cpanm Text::Parser

perl -MCPAN -e shell
install Text::Parser