Grammar live view

The grammar live view helps you to develop and debug grammars more efficiently. Its primary function is to run a grammar against a given example input whenever there is a change to the grammar or to the input text. However, the results it presents offer insights into how the grammar is matching (or failing to match) the input, and even hint at potential ways to change a grammar for better performance.

Basic usage

In a project containing a grammar, open the Tools menu, and select Preview Raku Grammar. A dropdown list can be used to select from the grammars in the project. Underneath that is an editor where input to test the grammar with can be entered. The results of running the grammar against that input are displayed below: first a summary, then a tree showing how the grammar matched against the text.

Exploring how the grammar matched

Double-clicking on the matched input text will open the deepest grammar rule that matched in in the tree view below. Similarly, clicking on a rule in the match tree will show highlight the text that it matched in the input editor. The locate icon on the left can be used to navigate to the source code of the rule currently selected in the parse tree.

Rules whose output is captured by the parent rule are shown in bold. When the parent captures it under a different name, the name of the rule is not bolded, and the alias it was captured under is displayed in bold in parentheses next to it. Effectively, one can read the capture tree by looking at the bold text.

If the uncaptured things are too distracting, there is a toolbar button to hide non-capturing rules. (However, there are still some non-bolded entries: these are the names of the protoregex candidates that were chosen.)

When the grammar fails to parse

When the grammar fails to parse, up to three regions are indicated in the input text.

The text with no background highlight was successfully consumed either by the TOP rule or a rule called from the TOP rule. The yellow background color indicates text that was matched by some rule, but was ultimately backtracked over when a parent rule failed to match, ultimately leading to the overall failure of the grammar to match. Finally, the red indicates text that was never successfully matched by a rule. In some cases, there may be no yellow section.

Generally, the start of the red is where things went wrong. The yellow section can provide a clue as to what the grammar was trying to parse before it reached something it could not match.

The parse tree offers further information: it shows which rules were attempted but failed to match. Such rules show up in red. In the case in the image above, the problem is that the parameter rule failed (actually due to wrong syntax in the input rather than a grammar bug in this specific situation).

Spotting potential inefficiencies

Even in the case that the grammar was successful, there can still be failed rules displayed (in red) in the tree view.

Sometimes these are relatively benign; for example, when parsing a sequence of things, often there will be a failure to match at the end of the sequence. However, when there are deep trees beneath a red node, this can potentially indicate a large amount of wasted work, and may present an opportunity to optimize the grammar.