aam-csharp 2.6.0

aam-rs for C#

C# bindings for the aam-rs AAM parser using the stable C FFI.

Features

• AAM Parsing: Parse and query .aam configuration files
• Cross-platform: Supports Windows, macOS, and Linux (x64, ARM64)
• Type-safe: Strongly-typed C# API with proper resource management
• Zero-copy: Efficient bindings using P/Invoke
• Schema Validation: Built-in schema and type system support

Installation

Via NuGet

dotnet add package aam-csharp

Or via Package Manager:

Install-Package aam-csharp

Prerequisites

The managed package requires the native aam_rs library at runtime:

• Windows: aam_rs.dll
• macOS: libaam_rs.dylib
• Linux: libaam_rs.so

The NuGet package includes pre-built native libraries for:

• Windows (x64)
• macOS (x64, ARM64)
• Linux (x64)

For local development

Build the native library from the repository:

cd aam-rs/
cargo build --release --features ffi

Then set the library path:

• Linux/macOS: export LD_LIBRARY_PATH=/path/to/target/release:$LD_LIBRARY_PATH
• Windows: Add the directory to your PATH

Usage

Basic Parsing

using AamCsharp;

// Parse AAM content
using var doc = AamDocument.Parse("host = localhost\nport = 8080");

// Look up values
string? host = doc.Get("host");         // "localhost"
string? port = doc.Get("port");         // "8080"

Find / ReverseSearch

using var doc = AamDocument.Parse("host = localhost\nport = 8080\nalias = localhost");
var byKey = doc.Find("host");
var byValue = doc.Find("localhost");
var keys = doc.ReverseSearch("localhost");

DeepSearch by key pattern

using var doc = AamDocument.Parse(@"
root_path = srv
current_path = root_path
mode = active
");

var matches = doc.DeepSearch("path");
Console.WriteLine(matches["root_path"]); // srv

Loading from Files

using var doc = AamDocument.Load("config.aam");

Building and Testing

Solution Layout

• aam-csharp.csproj - class library (NuGet package)
• tests/AamCsharp.Tests.csproj - test project
• examples/AamCsharp.Examples.csproj - runnable examples
• apps/AamCsharp.Console/AamCsharp.Console.csproj - console app
• AamCsharp.sln - solution that includes all projects

Build

dotnet build AamCsharp.sln

Run Tests

dotnet test AamCsharp.sln

Run Examples

dotnet run --project examples/AamCsharp.Examples.csproj -- basic
dotnet run --project examples/AamCsharp.Examples.csproj -- load

Run Console App

dotnet run --project apps/AamCsharp.Console/AamCsharp.Console.csproj -- parse "host = localhost"
dotnet run --project apps/AamCsharp.Console/AamCsharp.Console.csproj -- load ./examples/config.aam

Note: Some tests require the native library to be available. On CI systems without native artifacts, tests gracefully skip with DllNotFoundException.

Supported Platforms

API Reference

AamDocument

Main class for AAM document handling.

Parse(string content): AamDocument

Parses AAM content from a string.

Load(string path): AamDocument

Loads an AAM file from disk.

Get(string key): string?

Returns a value by key.

Find(string query): Dictionary<string, string>

Finds matching pairs by key, then by value fallback.

DeepSearch(string pattern): Dictionary<string, string>

Finds key-value pairs where keys contain a pattern.

ReverseSearch(string value): string[]

Finds keys for a value.

Dispose(): void

Releases native resources. Implement via using statement.

Error Handling

The C# bindings use standard .NET exceptions:

try
{
    using var doc = AamDocument.Parse("invalid content");
}
catch (InvalidOperationException ex)
{
    // Handle parse errors
    Console.WriteLine($"Parse error: {ex.Message}");
}
catch (DllNotFoundException ex)
{
    // Handle missing native library
    Console.WriteLine($"Native library not found: {ex.Message}");
}

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.