M3LParser 0.1.3

M3LParser

M3L (Meta Model Markup Language) parser for .NET — parse .m3l.md files into a structured AST.

M3L is a Markdown-based data modeling language. You write data models in readable Markdown, and this parser converts them into a machine-processable AST with full validation.

Install

dotnet add package M3LParser

Supported runtimes: .NET 8.0, .NET 9.0, .NET 10.0

Quick Start

using M3L;

var parser = new M3LParser();

// Parse a file or directory
var ast = await parser.ParseAsync("./models");

// Parse a string
var ast2 = parser.ParseString("""
## User
- name: string(100) @not_null
- email: string(320)? @unique

## UserRole ::enum
- admin: "Administrator"
- user: "Regular User"
""");

Console.WriteLine(ast2.Models.Count);  // 1
Console.WriteLine(ast2.Enums.Count);   // 1

// Validate with diagnostics
var (validated, result) = await parser.ValidateAsync("./models");
foreach (var error in result.Errors)
    Console.WriteLine($"[{error.Code}] {error.Message}");

M3L Syntax

# Namespace: myapp

## Author
- name(Author Name): string(100) @not_null @searchable
- bio(Biography): text?
- birth_date: date?

### Rollup
- book_count: integer @rollup(BookAuthor.author_id, count)

> Stores information about book authors.

## BookStatus ::enum
- available: "Available"
- borrowed: "Borrowed"
- reserved: "Reserved"

## Book : BaseModel
- title: string(200) @not_null @searchable
- isbn: string(20) @unique
- status: enum = "available"
  - available: "Available"
  - borrowed: "Borrowed"
- publisher_id: identifier @fk(Publisher.id)

### Lookup
- publisher_name: string @lookup(publisher_id.name)

### Computed
- is_available: boolean @computed("status = 'available' AND quantity > 0")

## OverdueLoans ::view @materialized
> Currently overdue book loans.
### Source
- from: Loan
- where: "due_date < now() AND status = 'ongoing'"
- order_by: due_date asc
- borrower_name: string @lookup(member_id.name)

Key syntax elements:

AST Output

The parser produces an M3LAst object:

public class M3LAst
{
    public string ParserVersion { get; set; }   // Parser package version (semver)
    public string AstVersion { get; set; }      // AST schema version
    public ProjectInfo Project { get; set; }
    public List<string> Sources { get; set; }
    public List<ModelNode> Models { get; set; }
    public List<EnumNode> Enums { get; set; }
    public List<ModelNode> Interfaces { get; set; }
    public List<ModelNode> Views { get; set; }
    public List<Diagnostic> Errors { get; set; }
    public List<Diagnostic> Warnings { get; set; }
}

Key AST types

public class FieldNode
{
    public string Name { get; set; }
    public string? Type { get; set; }
    public List<string>? GenericParams { get; set; }  // map<K,V> → ["K", "V"]
    public bool Nullable { get; set; }
    public bool Array { get; set; }
    public bool ArrayItemNullable { get; set; }       // string?[] → true
    public FieldKind Kind { get; set; }               // Stored, Computed, Lookup, Rollup
    public List<FieldAttribute> Attributes { get; set; }
    public List<CustomAttribute>? FrameworkAttrs { get; set; }
    public LookupDef? Lookup { get; set; }
    public RollupDef? Rollup { get; set; }
    public ComputedDef? Computed { get; set; }
    public List<FieldNode>? Fields { get; set; }      // sub-fields for object type
    // ...
}

public class ModelNode
{
    public string Name { get; set; }
    public string NodeType { get; set; }              // "model", "interface", "view"
    public List<string> Inherits { get; set; }
    public List<FieldAttribute> Attributes { get; set; }  // model-level attrs
    public List<FieldNode> Fields { get; set; }
    public SectionData Sections { get; set; }
    // ...
}

Validation

The validator checks for semantic errors and style warnings:

Errors:

Warnings (strict mode):

Multi-file Projects

Place .m3l.md files in a directory and parse the directory path. The resolver automatically merges all files, resolves inheritance, and detects cross-file references.

var parser = new M3LParser();
var ast = await parser.ParseAsync("./models");

// All models, enums, interfaces, views from all files are merged
Console.WriteLine($"Models: {ast.Models.Count}");
Console.WriteLine($"Errors: {ast.Errors.Count}");

API Reference

High-level API (M3LParser)

var parser = new M3LParser();

// Parse files from path (file or directory)
M3LAst ast = await parser.ParseAsync(inputPath);

// Parse content string
M3LAst ast = parser.ParseString(content, filename);

// Parse and validate
(M3LAst ast, ValidateResult result) = await parser.ValidateAsync(inputPath);
(M3LAst ast, ValidateResult result) = parser.ValidateString(content);

Lower-level API

using M3L;
using M3L.Models;

// Step-by-step parsing
List<Token> tokens = Lexer.Lex(content, "file.m3l.md");
ParsedFile parsed = Parser.ParseTokens(tokens, "file.m3l.md");
M3LAst ast = Resolver.Resolve(new[] { parsed });
ValidateResult result = Validator.Validate(ast, new ValidateOptions { Strict = true });

Version Info

string parserVersion = M3LParser.GetParserVersion(); // from VERSION file
string astVersion = M3LParser.GetAstVersion();       // "1.0"

Compatibility

This C# parser is a direct port of the TypeScript parser and produces an equivalent AST structure. Both parsers share the same conformance test suite.

Version is managed centrally via the root VERSION file.

License

MIT