Rule References

    <sub_rule_name>
    sub_rule_name

When used outside a regex, a reference can have a number of prefix modifiers. Note the the angle brackets are not required here, but add to readability.

    =rule  # Zero-width positive assertion (look-ahead)
    !rule  # Zero-width negative assertion (look-ahead)
    .rule  # Skip (ie: parse but don't capture a subpattern)
    -rule  # Flat (flatten the array captures)
    +rule  # Always wrap

(Skipping and wrapping are explained in [Return Values].)

A reference can also have a number of suffixed quantifiers. Similar to regular expression syntax, a quantifier indicates how many times a rule (reference) should match.

    rule?      # optional
    rule*      # 0 or more times
    rule+      # 1 or more times
    <rule>8    # exactly 8 times
    <rule>2+   # 2 or more times
    <rule>2-3  # 2 or 3 times
    <rule>0-6  # 0 to 6 times

Note that you must use angle brackets if you are using a numbered modifier:

    rule8    # WRONG!  This would match rule "rule8".
    rule2+   # WRONG!  This would match rule "rule2", 1 or more times.
    rule2-3  # WRONG!  Pegex syntax error

There is a special set of predefined "Atoms" that refer to regular expression fragments. Atoms exist for every punctuation character and for characters commonly found in regular expressions. Atoms enhance readability in grammar texts, and allow special characters (like slash or hash) to be used as Pegex syntax.

For example, a regex to match a comment might be '#' followed by anything, followed by a newline. In Pegex, you would write:

    comment: / HASH ANY* EOL /

instead of:

    comment: /#.*\r?\n/

Pegex would compile the former into the latter.

Here are some atoms:

    DASH    # -
    PLUS    # +
    TILDE   # ~
    SLASH   # /
    HASH    # # (literal)
    QMARK   # ? (literal)
    STAR    # * (literal)
    LPAREN  # ( (literal)
    RPAREN  # ) (literal)
    WORD    # \w
    WS      # \s

The full list can be found in the [Atoms source code|<https://metacpan.org/source/Pegex::Grammar::Atoms].>

Regexes

A regex is a string inside forward slashes.

    /regex/

The regex syntax mostly follows Perl, with the following exceptions:

    # Any rules in angle brackets are referenced in the regex
    / ( <rule1> | 'non_rule' ) /  # "non_rule" is interpreted literally

    # The syntax implies a /x modifier, so whitespace and comments are
    # ignored.
    / (
        rule1+   # Match rule1 one or more times
        |
        rule2
    ) /

    # Whitespace is declared with dash and plus.
    / - rule3 + /  # - = \s*, + = \s+, etc.

    # Any (?XX ) syntax can have the question mark removed
    / (: a | b ) /  # same as / (?: a | b ) /

Error Message

    `error message`

Operators

AND and OR are the most common operators. AND is represented by the absence of an operator. Like in these rules:

    r1: <a><b>
    r2: a b

Those are both the same. They mean rule "a" AND (followed immediately by) rule "b".

OR means match one or the other.

    r: a | b | c

means match rule "a" OR rule "b" OR rule "c". The rules are checked in order and if one matches, the others are skipped.

ALT means alternation. It's a way to specify a separator in a list.

    r: a+ % b

would match these:

    a
    aba
    ababa

"%%" means that a trailing separator is optional.

    r: a+ %% b

would match these:

    a
    ab
    aba
    abab

ANY operators take precedence over everything else, similar to other parsers. These rules have the same binding precedence:

    r1: a b | c % d
    r2: (a b) | (c % d)

Parens are not only used for indicating binding precedence; they also can create quantifiable groups:

    r1: (a b)+ c

would match:

    abababac

Skipping

    r: (a .b)+ % +
    a: /( ALPHA+ )/
    b: /( DIGIT+ )( PLUS )/

    # input = foobar123+ boofar789+
    # output (using Pegex::Tree) = [
    #     'foobar',
    #     'boofar',
    # ]

The skip modifier can also be used with groups. (This is the only group modifier allowed so far.)

    r: .(a b)+ % +
    a: /( ALPHA+ )/
    b: /( DIGIT+ )( PLUS )/

    # output (using Pegex::Tree) = []

Wrapping

    { rule_A => $match }
    { rule_B => [ @matches ] }

Note that this behavior can be "hard set" with the "+/-" rule modifiers:

    -rule  # Flatten array captures
    +rule  # Always wrap (even if using Pegex::Tree)

This is simply a check in the "gotrule" for the receiver. So, any specific "got_*" receiver methods will override even these settings, and choose to pass the match as-is. In this case, the "got_*" sub return value dictates what ultimately gets put into the tree object:

    +rule_A   # in this case, the + is useless here

    sub got_rule_A {
        my ($self, $matches_arrayref) = @_;
        return $matches_arrayref;
        # will be received as [ @matches ]
    }

You can "correct" this behavior by passing it back to "gotrule":

    +rule_A   # now + is honored

    sub got_rule_A {
        my ($self, $matches_arrayref) = @_;
        return $self->gotrule($matches_arrayref);
        # will be received as { rule_A => [ @matches ] }
    }