Ramstack.Parsing 1.1.0

dotnet add package Ramstack.Parsing --version 1.1.0
                    
NuGet\Install-Package Ramstack.Parsing -Version 1.1.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Ramstack.Parsing" Version="1.1.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Ramstack.Parsing" Version="1.1.0" />
                    
Directory.Packages.props
<PackageReference Include="Ramstack.Parsing" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Ramstack.Parsing --version 1.1.0
                    
#r "nuget: Ramstack.Parsing, 1.1.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Ramstack.Parsing@1.1.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Ramstack.Parsing&version=1.1.0
                    
Install as a Cake Addin
#tool nuget:?package=Ramstack.Parsing&version=1.1.0
                    
Install as a Cake Tool

Ramstack.Parsing

NuGet MIT

A fast, lightweight parser combinator library for .NET. Build text parsers in C# with typed results and optional error diagnostics.

Installation

Requires .NET 6 or later.

dotnet add package Ramstack.Parsing

Documentation

See the documentation for method guides, parsing details, and complete examples in plain English.

Example

This parser evaluates arithmetic expressions with parentheses, unary minus, and operator precedence:

using System;
using Ramstack.Parsing;
using static Ramstack.Parsing.Parser;

var calc = CreateParser();

Console.WriteLine(calc.Parse("2 + 3 * (4 - 1)")); // 11
Console.WriteLine(calc.Parse("1 + ("));           // (1:6) Expected '-', '(', or number

static Parser<double> CreateParser()
{
    var sum = Deferred<double>();

    var value = Literal
        .Number<double>("number")
        .ThenIgnore(S);

    var parenthesis = sum.Between(
        Seq(L('('), S),
        Seq(L(')'), S)
        );

    var primary = parenthesis.Or(value);

    var unary = Seq(
        L('-').Optional(),
        S,
        primary
        ).Do((u, _, d) => u.HasValue ? -d : d);

    var product = unary.FoldL(
        OneOf("*/").ThenIgnore(S),
        (l, r, op) => op == '*' ? l * r : l / r);

    sum.Parser = product.FoldL(
        OneOf("+-").ThenIgnore(S),
        (l, r, op) => op == '+' ? l + r : l - r);

    return sum.Between(S, Eof);
}

Full grammar: calculator.

Parsing results

Parse returns a result with Success, Value, and ErrorMessage properties. Parse errors include the line, column, and expected input:

var result = calc.Parse("2 + 3 * (4 - 1)");
if (result.Success)
{
    Console.WriteLine(result.Value);
}
else
{
    Console.WriteLine(result.ErrorMessage);
}

Use TryParse when you only need the value and success status. It skips diagnostics, so it allocates less and runs faster:

if (calc.TryParse("2 + 3 * (4 - 1)", out var value))
{
    Console.WriteLine(value);
}

Parsing notes

  • Parse and TryParse accept strings and ReadOnlySpan<char>.
  • L matches a literal; S matches zero or more whitespace characters. Whitespace is handled explicitly.
  • Add Eof to require the entire input. Here, Between(S, Eof) allows leading whitespace and rejects trailing input.
  • Build each parser once and reuse it.

Performance

In this email-matching benchmark, Ramstack.Parsing performs about as fast as compiled and source-generated regex, with no measured managed allocations.

The benchmark matches development.team-2021@example.com against \A[\w.+-]+@[\w-]+\.\w{2,}\z. All implementations use the same Unicode character classes and require the end of input. This is a simplified pattern, not a full email validator.

Measured with BenchmarkDotNet on .NET 11 RC1 (Linux, AMD Ryzen 9 5900X).

Method Mean Ratio Allocated
Ramstack 34.81 ns 1.00 -
Regex 106.58 ns 3.06 -
Regex:Compiled 38.02 ns 1.09 -
Regex:Generated 38.42 ns 1.10 -
Parlot 160.11 ns 4.60 184 B
Parlot:Compiled 150.57 ns 4.32 184 B
Pidgin 202.13 ns 5.81 0–40 B

Pidgin measured 0–40 B across runs.

Among parser combinator libraries, Ramstack.Parsing is the fastest in this comparison - about 1.7–1.9x faster than the next-fastest implementation on the expression and JSON benchmarks.

See the full benchmark results for expression evaluation, JSON parsing, library versions, and reproduction commands. Results depend on the grammar, input, runtime, and hardware.

Examples

  • Calculator — recursive expressions and operator precedence.
  • JSON — nested objects and arrays.
  • TinyC — statements, expressions, and comments.

Contributing

Bug reports and pull requests are welcome. See Contributing.

License

MIT.

Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net6.0

    • No dependencies.
  • net7.0

    • No dependencies.
  • net8.0

    • No dependencies.
  • net9.0

    • No dependencies.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Ramstack.Parsing:

Package Downloads
Ramstack.ExpressionParser

A flexible expression parser library for .NET, allowing dynamic evaluation and binding of expressions with context-aware support.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.1.0 79 11/16/2026
1.0.1 1,026 7/20/2025
1.0.0 305 5/24/2025
1.0.0-beta.7 233 5/8/2025
1.0.0-beta.6 220 4/28/2025
1.0.0-beta.5 220 2/15/2025
1.0.0-beta.4 177 2/11/2025
1.0.0-beta.3 196 2/8/2025
1.0.0-beta.2 175 2/8/2025
1.0.0-beta.1 161 2/6/2025