/ 
Data-Annotation-0.002
/ Data::Annotation::Rule

NAME

Data::Annotation::Rule

SYNOPSIS

use Data::Annotation::Rule;

DESCRIPTION

Representation of a rule, meant to be used by Data::Annotation.

INTERFACE

Constructor

my $rule = Data::Annotation::Rule->(%opts);

Make a new instance for a rule.

Input parameter condition is supposed to be compatible with Data::Annotation::Expression, either by being an instance itself or by being suitable to create a new instance.

Accessors

condition

my $condition = $rule->condition;

The condition that is checked to see if the rule applies or not. It must be compatible with Data::Annotation::Expression and will be used as a boolean expression.

description

my $text = $rule->description;

An optional description for the rule definition. It will be useful for you in a couple of months, after you forgot everything about it.

name

my $text = $rule->name;

An explicit name for the rule, useful for debugging (it is printed when a rule matches and debug or trace is enabled).

parse_context

my $ctx = $rule->parse_context;

Whatever was passed as argument condition-parse-context, which can help set the stage for condition parsing. This should not be generally needed, but still. See Data::Annotation::Expression for more details.

record

my $defs = $rule->record;

A data structure to drive changes in the $overlay passed to "evaluate" in case the condition applies. This allows recording some data that can be later used by other chains/rules during following evaluations.

Accepts a hash reference with the following keys:

All paths are supposed to be relative to an initial key run, which is mapped onto the $overlay in "execute".

As an example, let's consider the following chains definitions:

# ...
EHLO:
  default: reject
  rules:
    - condition:
        and:
          - eq: [ '.peer_ip', '=127.0.0.1' ]
          - eq: [ '.peer_identity', '=localhost.localdomain' ]
      record:
        set:
          '.caller': localhost
      return: accept

DATA:
  default: reject
  rules:
    - name: localhost/size
      condition:
        and:
          - eq: [ '.caller', '=localhost' ]
          - '<': [ '.mail_min_size', '=250' ]
      return: accept
# ...

When the EHLO chain is called and the first (and only) rule is matched, then a new parameter at position run.caller is set to the literal value localhost. This can then be used at a later call to rule DATA, allowing to avoid repeating all the tests and adding readability to the whole condition.

retval

my $retval = $rule->retval;

The result (annotation) value returned by "evaluate" when the condition of the rule applies.

Initialized by key return in the constructor.

Methods

evaluate

my $result = $rule->evaluate($overlay);

Evaluate the annotation for data wrapped in some $overlay.

ANYTHING ELSE (INCLUDING AUTHOR, COPYRIGHT AND LICENSE)

See documentation for Data::Annotation.