Aexol Language Tools

Complete lexer, tokenizer, and parser for the Aexol language, a declarative DSL for defining multi-agent systems, workflows, and capability hierarchies.

Overview

Aexol is a domain-specific language designed for:

• Capability Modeling: Define hierarchical capability trees for visitors/actors
• Workflow Design: Express state machines and workflow transitions
• Role-Based Access: Define roles and permissions
• Agent Definition: Create autonomous agents with capabilities
• Type System: Define custom types, enums, and interfaces

This package provides complete language processing tools:

• Lexer (lexer.ts): Tokenizes Aexol source code
• Tokenizer (tokenizer.ts): Stream-based token access with lookahead
• Parser (parser.ts): Builds Abstract Syntax Trees (AST)
• Validator (validator.ts): Semantic analysis and validation
• Code Generator (codegen.ts): Generate implementation code
• Utilities (utils.ts): Analysis, visualization, and reporting

Quick Start

Installation

The Aexol tools are built into the Ouro CLI:

npm install @aexol/ouro
# or
deno add jsr:@aexol/ouro

Basic Usage

import { Parser, Validator, CodeGenerator } from "@aexol/ouro/aexol";

// Parse Aexol source code
const source = await Deno.readTextFile("system.aexol");
const parser = new Parser(source);
const ast = parser.parse();

// Validate the AST
const validator = new Validator(ast);
const result = validator.validate();

if (!result.isValid) {
  console.error("Validation failed:", result.errors);
}

// Generate TypeScript code
const generator = new CodeGenerator(ast, { language: "typescript" });
const code = generator.generate();

Module Structure

src/aexol/
├── lexer.ts           # Tokenization (TokenType, Lexer class)
├── tokenizer.ts       # Token stream (Tokenizer class)
├── parser.ts          # AST generation (Parser, ASTNode types)
├── validator.ts       # Semantic analysis (Validator class)
├── codegen.ts         # Code generation (CodeGenerator class)
├── utils.ts           # Analysis utilities
├── index.ts           # Barrel exports
└── examples/
    ├── todo.aexol       # Simple todo system
    └── ecommerce.aexol  # Complete e-commerce example

API Reference

Lexer

class Lexer {
  constructor(source: string)
  tokenize(): Token[]
  getTokens(): Token[]
}

Tokenizer

class Tokenizer {
  constructor(source: string)
  current(): Token              // Current token
  peek(offset?: number): Token  // Look ahead
  advance(): Token              // Move to next
  check(type: TokenType): boolean
  checkAny(...types: TokenType[]): boolean
  consume(type: TokenType, message?: string): Token
  match(...types: TokenType[]): Token | null
  isAtEnd(): boolean
  getAllTokens(): Token[]
}

Parser

class Parser {
  constructor(source: string)
  parse(): Program
}

Validator

class Validator {
  constructor(program: Program)
  validate(): ValidationResult
}

interface ValidationResult {
  isValid: boolean
  errors: ValidationError[]
  warnings: ValidationError[]
  infos: ValidationError[]
}

CodeGenerator

class CodeGenerator {
  constructor(program: Program, options?: CodeGenOptions)
  generate(): string
}

interface CodeGenOptions {
  language: "typescript" | "python" | "rust" | "go" | "javascript"
  framework?: string
  outputFormat?: "classes" | "functions" | "interfaces" | "agents"
  indent?: number
}

Language Features

Capabilities

Capabilities are defined using quoted strings:

visitor {
    "login"
    "view dashboard"
    "create document"
}

Language Constructs

Visitors - Hierarchical capabilities for actors:

visitor {
    "login" {
        "create document"
        "edit document"
        "delete document"
    }
}

Roles - Permission sets:

role Editor {
    permission documents {
        create,
        read,
        update,
        delete
    }
}

Workflows - State machines:

workflow DocumentPublishing {
    state draft -> review
    state review -> published, rejected
    state published -> archived
}

Agents - Autonomous entities:

agent ContentProcessor: Editor {
    "fetch document"
    "process content"
    "publish document"
}

Types - Custom data types:

type Document {
    id: string
    title: string
    status: DocumentStatus
}

enum DocumentStatus {
    draft
    review
    published
    archived
}

Examples

Simple Todo System

visitor {
    "login" {
        "list todos"
        "add todo"
        "mark done"
        "delete todo"
    }
    "register"
}

E-Commerce System

See examples/ecommerce.aexol for a complete example including:

• Product types and enums
• Order workflows
• Customer, seller, and admin visitors
• Multiple agents with different roles

CLI Usage

Parse a File

aexol parse system.aexol

Validate

aexol validate system.aexol

Analyze

aexol analyze system.aexol

Generate Code

aexol inference system.aexol

Generate Documentation

aexol docs system.aexol

Utilities

Analysis

import { analyzeAexol, generateReport } from "@aexol/ouro/aexol";

const report = analyzeAexol(source);
console.log(generateReport(source));

Visualization

import { visualizeCapabilityTree } from "@aexol/ouro/aexol";

console.log(visualizeCapabilityTree(visitor.capabilities));

Search

import { findCapabilities } from "@aexol/ouro/aexol";

const readActions = findCapabilities(ast, /read/);

Documentation Generation

import { generateMarkdownDocs } from "@aexol/ouro/aexol";

const docs = generateMarkdownDocs(ast);
await Deno.writeTextFile("api.md", docs);

Architecture

Lexical Analysis (Lexer)

The lexer converts source code into tokens:

• Recognizes keywords, identifiers, operators, strings
• Handles indentation-based scoping
• Supports comments

Syntax Analysis (Parser)

The parser builds an AST:

• Recursive descent parsing
• Operator precedence handling
• Error recovery and synchronization

Semantic Analysis (Validator)

The validator checks:

• Name uniqueness and references
• Type constraints
• Structure and hierarchy
• Best practices

Code Generation

The code generator produces implementation:

• Supports multiple target languages
• Generates classes, functions, or agent definitions
• Preserves semantic structure

Error Handling

Compile-Time Errors

Validation Warnings

Performance

• Parse files up to 100KB: < 1 second
• Validate: < 500ms
• Code generation: < 200ms
• Memory: ~1-2MB per file

Testing

The lexer, tokenizer, and parser handle:

• All language constructs
• Nested hierarchies (up to 10+ levels)
• Comments and whitespace
• Error recovery and synchronization
• Large files (100KB+)

See examples/ for test files and use the analysis tools to validate.

Extending

Custom Code Generators

class MyGenerator extends CodeGenerator {
  generateType(type: TypeDefinition): void {
    // Custom implementation
  }
}

Custom Validators

class MyValidator extends Validator {
  validateAgent(agent: AgentDefinition): void {
    super.validateAgent(agent);
    // Custom checks
  }
}

Documentation

• Aexol Language Guide
• Aexol Specification
• API Reference

Contributing

When adding features:

1. Update the lexer for new tokens
2. Update the parser for new grammar rules
3. Add validator checks
4. Update code generators
5. Add examples and tests
6. Update documentation

License

MIT - See LICENSE file