aam-rs 2.0.2

A Rust implementation of the Abstract Alias Mapping (AAM) framework for aliasing and maping aam files.
Documentation

AAM (Abstract Alias Mapping)

A robust and lightweight configuration library for Rust built around the new pipeline-backed AAM API. It parses .aam files (key = value), supports directives (@import, @derive, @schema, @type), and provides fast query and formatting utilities.

What changed in 2.x

  • AAM is now the primary API.
  • Parsing/loading returns Result<_, Vec<AamlError>> to preserve full diagnostics.
  • Query methods are now centered around get, find, find_by, deep_search, and reverse_search.
  • Pipeline formatter and LSP helper methods are available directly on AAM.
  • AAML remains available for backward compatibility, but is deprecated.

Features

  • Simple key = value syntax.
  • Directive support: @import, @derive, @schema, @type.
  • Schema/type validation via pipeline.
  • Search helpers for key lookup, reverse lookup, and predicate filtering.
  • Formatter utilities (format, format_range) and LSP assist (lsp_assist).
  • Optional AOT loading (.aam.bin) for fast startup (aot feature; enabled by default).
  • Fluent config generation with AAMBuilder.

Format

You can find syntax documentation and examples at: https://aam.ininids.in.rs/

Installation

Add the crate to your Cargo.toml:

[dependencies]
aam-rs = "2.0.2"

Configuration syntax (.aam)

# Comments are supported
host = "localhost"
port = 8080

@import database.aam
@import theme.aam

@type port_t = i32
@schema Service {
    host: string
    port: port_t
}

Usage (new AAM API)

1) Parse and load

use aam_rs::aam::AAM;
use aam_rs::error::AamlError;

fn print_errors(errors: &[AamlError]) {
    for err in errors {
        eprintln!("{err}");
    }
}

fn main() {
    let inline = "host = localhost\nport = 8080";

    match AAM::parse(inline) {
        Ok(cfg) => {
            if let Some(host) = cfg.get("host") {
                println!("host = {host}");
            }
        }
        Err(errors) => {
            print_errors(&errors);
        }
    }
}

2) Lookups and queries

use aam_rs::aam::AAM;

let cfg = AAM::parse(
    "
app_mode = production
backup_mode = production
api_port = 8080
"
).unwrap();

// O(1) key lookup
assert_eq!(cfg.get("api_port"), Some("8080"));

// key-first lookup, then reverse lookup by value
let found = cfg.find("production");
assert_eq!(found.len(), 2);

// reverse lookup only
let keys = cfg.reverse_search("production");
assert_eq!(keys.len(), 2);

// key pattern search
let deep = cfg.deep_search("mode");
assert_eq!(deep.len(), 2);

// custom predicate
let filtered = cfg.find_by(|k, v| k.ends_with("_port") && v == "8080");
assert_eq!(filtered, vec![("api_port", "8080")]);

3) Iteration and extraction

use aam_rs::aam::AAM;

let cfg = AAM::parse("a = 1\nb = 2").unwrap();

for (k, v) in cfg.iter() {
    println!("{k} = {v}");
}

let keys = cfg.keys();
let map = cfg.to_map();
assert!(keys.contains(&"a"));
assert_eq!(map.get("b"), Some(&"2".to_string()));

4) Formatting and LSP helper

use aam_rs::aam::AAM;
use aam_rs::pipeline::{FormatRange, FormattingOptions};

let cfg = AAM::new();
let src = "host=localhost\nport=8080";

let formatted = cfg.format(src, &FormattingOptions::default()).unwrap();
let _range = cfg
    .format_range(
        src,
        FormatRange { start_line: 1, end_line: 1 },
        &FormattingOptions::default(),
    )
    .unwrap();

let assist = AAM::lsp_assist(&formatted, &FormattingOptions::default());
assert!(assist.diagnostics.is_empty());

5) Builder (AAMBuilder)

use aam_rs::builder::{AAMBuilder, SchemaField};

let mut builder = AAMBuilder::new();
builder
    .comment("Server configuration")
    .type_alias("port_t", "i32")
    .schema("Server", [
        SchemaField::required("host", "string"),
        SchemaField::required("port", "port_t"),
        SchemaField::optional("debug", "bool"),
    ])
    .add_line("host", "2.0.2.1")
    .add_line("port", "8080");

println!("{}", builder.as_string());
builder.to_file("generated_config.aam").unwrap();

Legacy API (AAML, deprecated)

AAML is still available for compatibility and supports methods such as:

  • parse, load
  • merge_content, merge_file
  • find_obj, find_key, find_deep
  • validate_value, apply_schema, validate_schemas_completeness

For migration guidance, see docs/AAML_TO_AAM_MIGRATION.md.

Bindings

Node.js / N-API

npm install aam-nodejs

C# / .NET

dotnet add package aam-csharp

Quick verification commands

cargo test
cargo run --example standard
cargo run --example advanced

API reference (high-level)

AAM

  • Constructors/loaders: new, parse, load, from_pipeline
  • Query: get, find, find_by, deep_search, reverse_search
  • Iteration/export: iter, keys, to_map
  • Introspection: schemas, get_schema, types, get_type
  • Formatting/LSP: format, format_range, lsp_assist
  • AOT (feature-gated): cook, load_fast

AAMBuilder

  • new, with_capacity
  • add_line, comment
  • schema, schema_multiline, derive, import, type_alias
  • to_file, build, as_string

AamlError

Typed errors used across parser, validator, and runtime paths.

License

See LICENSE-MIT and LICENSE-APACHE.

Full documentation