v2.5.0: introducing pest_debugger

[tomtau]

What's Changed

• chore: clippy fixes and ignores by @tomtau in chore: clippy fixes and ignores #733
• ci: add CIFuzz GitHub action by @DavidKorczynski in ci: add CIFuzz GitHub action #738
• feature: added a pest_debugger crate (fixes Grammar backtrace #98) by @dragostis and @tomtau in feature: added a pest_debugger crate (fixes #98) #736

New Contributors

• @DavidKorczynski made their first contribution in ci: add CIFuzz GitHub action #738

Full Changelog: v2.4.1...v2.5.0

Accidental breakage of semantic versioning since v2.2.0 in pest_meta

We found out that, in addition to a breaking change in pest that was reverted, there were a few breaking changes in pest_meta in v2.2.0:

• pest_meta::validator::validate_undefined now takes 2 parameters instead of 3,
• pest_meta::validator::validate_pest_keywords now takes 1 parameter instead of 2,
• and pest_meta::validator::validate_rust_keywords now takes 1 parameter instead of 2.

Given pest_meta is primarily used within pest's own crates¹ and no one opened an issue regarding these breaking changes, we decided not to revert the post-2.2.0 releases and keep those functions as they are now in 2.5.0².

Having said that, we now have a CI action to check for semantic versioning, so we should be able to avoid accidental breaking changes in the future.

Introducing a new grammar debugger CLI and crate (pest_debugger)

While pest's focus is on accessibility, developers can sometimes struggle to understand what is going under the hood and why a particular input is parsed in a particular way (or fails to parse). A long time ago, @dragostis implemented a simple CLI debugger that could help in this aspect, but this effort was not finished. This implementation was revived and you are now welcome to use it. You should be able to install it using:

cargo install pest_debugger

You can then run the interactive debugger by calling pest_debugger and view its help by typing h in its prompt:

> h

Use the following commands:
g <grammar filename>          - load .pest grammar
i <input filename>            - load input from a file
id <input text>               - load input directly from a single-line input
ba                            - add breakpoints at all rules
b <rule>                      - add a breakpoint at a rule
d <rule>                      - delete a breakpoint at a rule
da                            - delete all breakpoints
r <rule>                      - run a rule
c                             - continue
l                             - list breakpoints
h                             - help

The commands are self-explanatory; for a quick reference, the basic usage is:

> g ...file path to your grammar...
> i ...file path to your input...
> b ...name of the rule you want to stop at...
> r ...the rule to start running at...

💡 There is a tab completion for file paths and command history.

And then, once the debugger hits a breakpoint, you can continue the execution by typing:

> c

💡 You can also start up the debugger with command-line arguments that will do those steps during initialisation:

Usage: pest_debugger [options]

Options:
-g, --grammar <grammar file>    - load .pest grammar
-i, --input <input file>        - load input file
-r, --rule <rule>               - run rule
-b, --breakpoint <rule>         - breakpoint at rule
-s, --session <session file>    - load session history file
-h, --help                      - print this help menu

Looking for a side project?

If you are using pest in your projects and would like to contribute to its development by organising its issues, reviewing its pull requests etc., please feel free to comment on this post to join the triage team!

In addition to that, here are also a few potential ideas for work that can help anyone who would like to get familiar with pest's implementation:

• The fiddle editor on pest.rs currently lives in the site repository and has not been updated to the latest pest version. It's also been built with the stdweb crate that is no longer maintained. It will be great to upgrade to the latest version as well as migrate from stdweb to wasm-bindgen and websys.
• The pest_debugger core functionality has been extracted to a standalone crate that could be used in frontends other than a command line. It will be cool to have something like regex101 for pest. The web-based debugger could perhaps live side-by-side with the fiddle editor on pest.rs or it could be standalone like the current online pest formatter tool.
• It can also be cool to explore if the pest_debugger functionality can be integrated within the existing Vim and IntelliJ plugins. Or create a new one for Visual Studio Code?

Does any of these ideas sound interesting to you and would like to work on them? Or do you have other pest-related ideas you are working on or would like to explore? Please don't hesitate to share them in the comments below the announcement!

---

This discussion was created from the release v2.5.0: introducing `pest_debugger`.

Footnotes

1. Those three pest_meta functions are rather internal and perhaps did not need to be made public early on. ↩

2. If these accidental pest_meta breaking changes cause any trouble in your code, please feel free to open an issue though! ↩

[tomtau]

BTW for those first two ideas, I opened these issues, feel free to comment directly on them:

pest-parser/site#13

pest-parser/site#14

[tomtau]

The website has been migrated to wasm-bindgen and the latest pest: https://pest.rs/#editor (you may need to refresh the window or clear the browser cache to reload the page content).
Huge kudos to @birkenfeld ! 🙏