FastParser 0.1.2

FastParser for .NET

FastParser is a thin C# binding over the FastParse native C ABI.

It parses source bytes in memory and returns AST data as JSON, CSV, binary MessagePack, or stats. It can also execute Tree-sitter queries and return structural matches/captures. The current native package includes the Java Tree-sitter grammar.

Install

dotnet add package FastParser --version 0.1.0-preview.17

The package includes RID-specific native libraries:

runtimes/linux-x64/native/libfastparse.so
runtimes/osx-arm64/native/libfastparse.dylib
runtimes/osx-x64/native/libfastparse.dylib
runtimes/win-x64/native/fastparse.dll

Basic Use

using FastParse;

using var parser = new FastParseClient();

var result = parser.ParseText(
    "class Demo { void run() {} }",
    new ParseOptions
    {
        Format = FastParseFormat.Json,
        IncludeRules = "method_declaration",
        Fields = FastParseField.Rule |
                 FastParseField.Text |
                 FastParseField.ByteRange
    });

Console.WriteLine(result.NodeCount);
Console.WriteLine(result.Text);

Tree-sitter Queries

Use QueryText when the grammar pattern is already known and the caller only needs specific captures:

var queryResult = parser.QueryText(
    "class Demo { void run() {} }",
    "(method_declaration name: (identifier) @method.name) @method",
    new QueryOptions
    {
        Language = "java",
        Format = FastParseFormat.Json,
        Fields = FastParseField.CaptureName |
                 FastParseField.Rule |
                 FastParseField.Text |
                 FastParseField.Range |
                 FastParseField.ByteRange
    });

Console.WriteLine(queryResult.Text);

For query stats, ParseSummary.NodeCount is the capture count and ParseSummary.OutputLength is the match count.

Binary Output

For FastParseFormat.Binary, ParseResult.Data contains MessagePack bytes. The package includes a small schema-specific decoder:

var binary = parser.ParseText(source, new ParseOptions
{
    Format = FastParseFormat.Binary,
    IncludeRules = "method_declaration",
    Fields = FastParseField.Rule | FastParseField.Text | FastParseField.ByteRange
});

var document = FastParseMessagePack.Decode(binary.Data);
Console.WriteLine(document.SchemaVersion);
Console.WriteLine(document.Nodes[0].Rule);

Diagnostics

Request FastParseField.Diagnostics to see Tree-sitter recovery signals:

var binary = parser.ParseText(source, new ParseOptions
{
    Format = FastParseFormat.Binary,
    Fields = FastParseField.Rule | FastParseField.Diagnostics
});

var document = FastParseMessagePack.Decode(binary.Data);
Console.WriteLine(document.HasErrors);
Console.WriteLine(document.ErrorNodeCount);
Console.WriteLine(document.Nodes[0].HasError);

Diagnostics are normal output data. A parse can succeed while HasErrors is true.

Stats Without Output Copy

var summary = parser.ParseTextSummary(source, new ParseOptions
{
    Format = FastParseFormat.Stats
});

Console.WriteLine(summary.NodeCount);
Console.WriteLine(summary.OutputLength); // 0 for stats

Native Library Loading

Normal NuGet use does not require FASTPARSE_LIBRARY_PATH; .NET resolves the bundled native asset for the current RID.

For advanced/manual loading, pass a path explicitly:

using var parser = new FastParseClient("/path/to/libfastparse.dylib");

Or set:

FASTPARSE_LIBRARY_PATH=/path/to/libfastparse.dylib

Threading

Use one FastParseClient per worker thread for simple high-throughput code. Parent applications still own thread pools, queues, and database coordination.

Package Name vs Namespace

The public NuGet package ID is FastParser.

The C# namespace is FastParse:

using FastParse;

Included Agent Resources

The NuGet package includes integration docs and examples for humans and AI agents:

AI_AGENT_GUIDE.md
docs/contracts.md
docs/language_extensions.md
docs/output_formats.md
docs/tree_sitter_queries.md
docs/binary_schema.md
docs/csharp_binding.md
docs/encoding.md
docs/platforms.md
docs/versioning.md
examples/csharp/01_parse_string/
examples/csharp/02_binary_decode/
examples/csharp/nuget/01_parse_string/
examples/csharp/nuget/02_binary_decode/

Start with AI_AGENT_GUIDE.md when generating an integration with an AI coding agent.

Debugging

The NuGet release includes portable PDBs, SourceLink metadata, XML documentation, and a .snupkg symbols package. Debuggers that support NuGet symbols can step from the package into the matching GitHub source revision.