<!-- markdownlint-disable first-line-h1 -->

<!-- markdownlint-enable first-line-h1 -->

About parol

<!-- markdownlint-disable Inline HTML --> <br> <img src="https://github.com/jsinger67/parol/raw/main/crates/parol/logo/Parol.svg" alt="Logo" height=300 with=300> <br><br><br> <!-- markdownlint-enable Inline HTML -->

ATTENTION - The main branch is subject to constant changes, so the experience can be bumpy

Therefore, please use an officially released version from crates.io or refer to one of the latest tags applied to main branch.

---

This workspace contains four essential crates that are all separately released on crates.io.

• parol
• parol_runtime
• parol-macros
• parol-ls

New changes can be viewed in the change logs of the respective projects.

• CHANGELOG parol
• CHANGELOG parol_runtime
• CHANGELOG parol-macros
• CHANGELOG parol-ls

It also contains the vs-code extension parol-vscode which is released on VS Code marketplace parol-vscode

• CHANGELOG parol-vscode
• Development checks parol-vscode

---

<!-- Start of content from CommonReadMe copied here. Unfortunately there is no include directive available in Markdown -->

parol is a LL(k) and a LALR(1) parser generator for Rust and C#.

It's an installable command line tool that can generate complete parsers from a single grammar description file including all AST data types you would otherwise had to design by yourself. parol does this solely by analyzing your language's grammar. parol is also a library that you can use in your own crates.

You can control the process of AST type generation. First you can mark elements for omission in your AST. Also you can specify your own types for language elements.

Language description and language implementation is strictly separated in parol. Thus you can design your language's grammar without any need to process anything because generated parsers function by default as acceptors. This empowers you to do a real rapid prototyping of your grammar.

parol generates a trait as interface between your language processing and the generated parser. The trait contains functions for each non-terminal of your grammar which you can implement for non-terminals you need to process. In the simplest case you only implement the trait function for the start symbol of your grammar which is called after the whole input string is parsed. This function then is called with a parameter that comprises the complete structure of the parsed document.

For generated C# parsers this interface is emitted as I<GrammarName>Actions and extends IUserActions and IProvidesValueConverter. Generated actions include a default GeneratedValueConverter and delegate %nt_type conversions via RuntimeValueConverter.Convert<T>. You can override the ValueConverter property in a derived actions class to provide custom grammar-specific conversions. The .NET SDK is only required for C# generation/build workflows. Rust-only workflows do not require .NET, and C# integration tests are skipped automatically when dotnet is not available. C# code generation supports both LL(k) and %grammar_type 'LALR(1)' grammars.

The parser calls the interface trait's functions via a separately generated adapter automatically during the process of parsing.

With such a generated interface trait you theoretically never have to let parol generate new code for you anymore and you can concentrate on the development of your language processing. Although, often a more iterative approach is taken.

Generated parsers

• are true LL(k) parsers implemented by push down automata (PDAs).
• are predictive, i.e. they implement a non-backtracking parsing technique. This often results in much faster parsers.
• are clean and easy to read.
• use only as much lookahead as needed for a certain non-terminal (from 0 to k)
• are generated from a single grammar description file.
• can generate types that resemble the AST of your grammar automatically. Semantic actions are then called with these types. This greatly improves the development process and makes it less error-prone.
• As of version 0.24.0 generated parsers can recover from syntax errors automatically
• As of version 0.28.0 parol starts to support LR style grammars as well, in detail LALR(1) grammars. Please have a look at the CHANGELOG

Other properties of parol

• Selection of production is done by a deterministic finite lookahead automaton for each non-terminal.
• Semantic actions with empty default implementations are generated as a trait. You can implement this trait for your grammar processing item and implement only needed actions. This provides a loose coupling between your language definition and the language processing.
• As a result semantic actions are strictly separated from the grammar definition in contrast to Bison. No parser generation step is needed when you merely change the implementation of a semantic action.
• The grammar description is provided in a Yacc/Bison-like style with additional features known from EBNF such as grouping, optional elements and repetitions.
• You can define multiple scanner states (aka start conditions) and define switches between them directly in the productions of your grammar.
• You can opt out the default handling of whitespace and newlines for each scanner state separately.
• The grammar description supports definition of language comments via %line_comment and %block_comment declarations for each scanner state.
• The crate provides several tools for grammar analysis, transformation and parse tree visualization to support your grammar implementation.
• The parser generator detects direct and indirect left recursions in your grammar description.
• parol's parser is generated by parol itself.
• Use parol new to create your own crate that uses parol.
• parol new -L c-sharp creates a .NET console project and references Parol.Runtime from NuGet by default.

Why should you use LL(k) parsers in your language implementation?

LL parsing technique is a top-down parsing strategy that always starts from the start symbol of your grammar. This symbol becomes the root node of the parse tree. Then it tries to derive the left-most symbol first. All such symbols are then processed in a pre-order traversal. During this process the parse tree is created from the root downwards.

Both, processing the input and producing the parse tree in 'natural' direction ensures that at every point during parsing you can see where you came from and what you want to derive next. parol's parse stack contains 'End of Production' markers which reflect the 'call hierarchy' of productions.

This tremendously helps to put your language processing into operation. In contrast, anyone who has ever debugged a LR parser will remember the effect of 'coming out of nowhere'.

Although LL grammars are known to be less powerful than LR grammars many use cases exist where LL grammars are sufficient. By supporting more than one lookahead token the abilities of traditional LR(1) grammars and LL(k) grammars become more and more indistinct.

Why should you use parol?

parol is simple. You can actually understand all parts of it without broader knowledge in parsing theory.

parol is fast. The use of deterministic automata ensures a minimal overhead during parsing, no backtracking needed.

parol is a true LL(k) parser. You won't find much working LL(k) parsers out there.

parol generates beautiful code that is easy to read which fosters debugging.

parol is young. Although this might be a problem some times, especially regarding the stability of the API, the best is yet to come.

parol is actively developed. Thus new features are likely to be added as the need arises.

Documentation

Examples

This project contains some introductory grammar examples from entry level up to a more complex C-like expression language and an acceptor for Oberon-0 grammar.

A complete Oberon-2 acceptor generated by parol can be found in the examples of this repository.

A rudimentary Basic interpreter strives to mimic a small part of C64 Basic.

I also provide a JSON Parser.

C# examples are available as calc_csharp and json_parser_csharp.

parol's input language processing is an additional and very practical example.

The book

A book ex