Parser Extension in Detail

When you call Parboiled.createParser to construct an instance of your parser class for the first time parboiled for Java internally runs its parser extension logic to augment you parser class with all kinds of special functionality. In order to do that parboiled creates a new, artificial subclass of your parser class that lives in the same package and has the name of your parser class suffixed with “$$parboiled”. Because of this basic approach your parser class must not be private or final, since otherwise parboiled would not be able to subclass it.

The automatically created parser subclass contains method overrides for all methods returning Rule instances. These overrides might at some point delegate to their super methods (the original rule method you defined in your parser class) or they might completely rewrite their supers method body without actually calling it.

These rule methods extensions require a complete rewrite of the method body and therefore do not call their super method:

• Parser Action Expressions
• Action Variables

These rule method extensions can be applied without a method rewrite and call the super method if the method does not also require a transformation listed above:

• @Label
• @Cached
• @SuppressNode
• @SuppressSubnodes
• @SkipNode
• @MemoMismatches

Normally you don’t have to care about the question whether an extension requires a method rewrite or not. However, in debugging scenarios, where you want to set a breakpoint in a rule method in order to trace its execution, your breakpoint will not be hit if the rule method has been rewritten by parboileds parser extension logic. So, for example, if you want to debug a rule method containing explicit or implicit action expressions you will have to temporarily convert these action expressions to explicit anonymous inner Action classes in order to prevent parboiled from completely rewriting the rule method.

All parser methods not returning Rule objects are left untouched by parboileds parser extension logic. In smaller parsers these often implement simple parser actions and can be directly used in rule methods, as long as they are not private.