Parlot .NET Parser Combinator Library

Parlot supports covariance through the IParser<out T> interface. This allows you to use a parser of a derived type (e.g., IParser<Dog>) in a context that expects a parser of a base type (e.g., IParser<Animal>).

Instead of using .Then<TBase>(x => x) to manually cast parsers—which creates unnecessary wrapper objects and impacts performance—you can use the OneOf<T> method. OneOf<T> accepts params IParser<T>[], allowing it to directly consume covariant parsers.

class Animal { public string Name { get; set; } }
class Dog : Animal { public string Breed { get; set; } }
class Cat : Animal { public string Color { get; set; } }

var dogParser = Terms.Text("dog").Then(_ => new Dog { Name = "Buddy", Breed = "Golden Retriever" });
var catParser = Terms.Text("cat").Then(_ => new Cat { Name = "Whiskers", Color = "Orange" });

// Use OneOf<T> directly with covariant parsers to avoid wrapper overhead
var animalParser = OneOf<Animal>(dogParser, catParser);

You can use helper attributes to control the environment of the generated code. These can be applied to individual methods or at the class level to affect all parsers within that class.

IncludeFiles

Include additional source files that your parser depends on. Paths are relative to the source file containing the [GenerateParser] method. Supports glob patterns:

• *: matches any characters except path separator
• **: matches recursively
• ?: matches single character

IncludeUsings

Add specific using directives to the generated code.

IncludeGenerators

Specify other source generators (e.g., PolySharp) that should run before the Parlot parser generation.

Class-level Application

Applying these attributes to a partial class applies them to all [GenerateParser] methods within that class. Method-level attributes are additive to class-level attributes.

// Method-level usage
[GenerateParser]
[IncludeFiles("Ast.cs", "Tokens.cs")]
[IncludeUsings("System.Collections.Generic", "MyProject.Models")]
[IncludeGenerators("PolySharp")]
public static Parser<Expression> CreateParser() => ...;

// Class-level usage
[IncludeFiles("Ast.cs")]
[IncludeUsings("MyProject.Models")]
public static partial class MyParsers
{
    [GenerateParser]
    public static Parser<Expression> ExprParser() => ...;

    [GenerateParser]
    [IncludeFiles("Extra.cs")]  // Combined with class-level
    public static Parser<Statement> StmtParser() => ...;
}

The OneOf parser (created via .Or(a, b)) can optimize parsing by using lookup tables to make quick decisions based on the next character in the input. This avoids unnecessary parser invocations.

To enable this optimization, a parser type can implement the ISeekable interface. Even if the parser cannot provide a full list of expected characters, implementing ISeekable and setting the CanSeek property allows the engine to utilize the optimization.

Example of creating an optimized Or parser:

var integer = Terms.Integer();
var hello = Terms.Text("Hello", caseInsensitive: true);
var intOrHello = integer.Or(hello);

Note on Terms.Text:

• When caseInsensitive: true is used, Text("Hello") returns the canonical requested text ("Hello") by default to avoid allocations.
• If you require the actual matched input text (e.g., "HELLO"), set returnMatchedText: true.

When implementing a custom parser, you must ensure that if a parser fails after having advanced the cursor, the cursor is reset to its initial position. This prevents subsequent parsers from starting at the wrong offset.

Best Practices:

• Always return from a non-successful parser with the cursor position it had when the parser was first invoked.
• If a parser succeeds and then a subsequent parser in a sequence fails, you must call context.Scanner.Cursor.ResetPosition(start) where start is the position captured before the first parser was called.
• If a parser is designed to be atomic and handles its own cleanup, it is assumed to reset the cursor on failure.
• Unit Testing: Always create a unit test to verify that your parser correctly resets the cursor position upon failure.

// Example of resetting position in a Sequence parser
public override bool Parse(ParseContext context, ref ParseResult<ValueTuple<T1, T2>> result)
{
    context.EnterParser(this);

    var parseResult1 = new ParseResult<T1>();
    var start = context.Scanner.Cursor.Position; // Capture start position

    if (_parser1.Parse(context, ref parseResult1))
    {
        var parseResult2 = new ParseResult<T2>();

        if (_parser2.Parse(context, ref parseResult2))
        {
            result.Set(parseResult1.Start, parseResult2.End, new ValueTuple<T1, T2>(parseResult1.Value, parseResult2.Value));
            context.ExitParser(this);
            return true;
        }

        // Reset position because parser1 succeeded but parser2 failed
        context.Scanner.Cursor.ResetPosition(start);
    }

    context.ExitParser(this);
    return false;
}