Defining your parser

Parser types

Csly uses a parser combinator strategy to generate strongly typed parser instances via the ParserBuilder.BuildParser<T, U> method. The BuildParser method includes two generic arguments; one contains the expression tokens you define and the other is the expected parser output type. More formally, a user-defined parser is of type Parser<IN,OUT> where:

• IN is an enum type with regex [Lexeme] decorators that represent all the tokens (symbols) your language accepts,
• OUT is the expected output type for your parser instance's Parse(...) method once it is invoked.

The output generic type can be a value or reference type. Traditionally, it will be a structure encoding an Abstract Syntax Tree (AST). In the sample parser discussed in the Getting started section, the output type is an integer which happens to contain the result of the arithmetic expression passed to the Parser.Parse(...) method.

More information on expression tokens is available in the Lexer page.

Typing rules

The visiting generic types entered at ParserBuilder instantiation are checked when ParserBuilder.BuildParser(...) is called. If the build fails no Exception will be thrown. Instead, check the Parser<T, U>.IsError flag or optionally, if the Parser<T, U>.Errors list is not null. A list of error messages will be populated with line and column indicators as well as reason for failure where the parse failed. todo: link to documented errors. Additional typing rules are described below.

ParserBuilder and Parser generic input and output type convention

Since the custom parser type is specified in both ParserBuilder and Parser OUT generic parameters, all syntax-tree traversal methods must return a value inheriting from type OUT. The same is true for IN types.

Clause rules for both IN and OUT types are formally described as follows:

• Token: for a terminal clause (rule: MyToken)
• OUT: for a non terminal clause (rule: nonTerminal)
• List<Token>: for multiplied terminal clause ( rule: MyToken+ )
• List<Token>: for multiplied non terminal clause (rule: nonterminal*)
• Group<IN,OUT>: for a group/sub rule clause ( rule: (MyToken nonterminal))
• ValueOption: for an optional non terminal clause (rule: nonTerminal?)
• ValueOption<Group<IN,OUT>>: for an optional group clause (rule: (MyToken nonterminal)?)
• List<Group<IN,OUT>>: for a repeated group clause ( rule: (MyToken noTerminal)*)

TODO: provide plain-language examples of the above rules. The clause rules provided above impact tree-traversal methods as well. More info at Parsing principles and BNF parsers.

Since alternate choices are either terminal or non-terminal, the same typing rules apply as in single (terminal) statements.

Getting started ⬅️ Defining your parser ➡️ Parsing principles and BNF parser