NAME

Parse::RandGen::Rule - Grammatical Rule object

DESCRIPTION

A Rule matches if any one of its Productions match the input text. In BNF notation, the relationship of Rules and Productions is:

rule1:         production1
             | production2
             | production3

For example:

perlFuncCall:  /&?/ identifier '(' argument(s?) ')'
             | scalar '->' identifier '(' argument(s?) ')'

The two productions in this example could respectively match:

"func()",  "func(x, y)",  or "&func(x)"
"$obj->member()"

METHODS

new

Creates a new Rule. The Rule name is the only required argument. Productions are optional.

Parse::RandGen::Rule->new (
    name => "perlFuncCall",     # Rule name (optional if an anonymous rule)

    # "prod" specifies a new Production object on this Rule
    prod => [ name => "staticFuncCall",   # Production name is optional
              cond => qr/&?/,                  # Regexp  Condition - 0 or 1 '&' characters
              cond => "indentifier",           # Subrule Condition - exactly 1 "identifier" rule
              cond => q{'('},                  # Literal Condition - single '(' character
              cond => "argument(s?)",          # Subrule Condition - 0 or more "argument" rules
              cond => q{')'}, ],               # Literal Condition - single ')' character
    prod => [ name => "objectFuncCall",   # Rule's second production
              cond => "scalar",
              cond => q{'->'},
              cond => "indentifier",
              cond => q{'('},
              cond => "argument(s?)",
              cond => q{')'}, ],
);

name

Return the name of the Rule.

grammar

Returns a reference to the Grammar that the Rule belongs to.

pick

Randomly generate data (text) that matches (or does not) the rule.

Takes a "match" boolean argument that specifies whether to match the regular expression or deliberately not match it.

Also takes a "vals" hash argument that has pairs of subrules (name or reference) and their desired value. This allows the generated data to have user-specified constraints while allowing the rest of the rule to choose random data. If "match" is false, the user-specified "vals" are still used (which may cause the data to match even though it was not supposed to). If a user-specified value is given, then productions that do not reference that rule are not chosen (unless no productions reference the rule).

Example:
    $re->pick(match=>0, vals=>{ file=>"Rule", extension=>"pm" });

SEE ALSO

Parse::RandGen, Parse::RandGen::Grammar, Parse::RandGen::Production, and Parse::RandGen::Condition

AUTHORS

Jeff Dutton