SimC AST Builder

A TypeScript library for parsing and building abstract syntax trees (ASTs) from SimulationCraft (SimC) action lists.

Features

• Parse SimulationCraft expressions and action lists
• Generate fully-typed abstract syntax trees
• Optimize conditions with various transformation rules
• Built with ANTLR4 for robust parsing
• Full TypeScript support with type definitions

Installation

npm install simc-ast-builder

Usage

Basic Parsing

import { parse } from 'simc-ast-builder';

// Parse a SimC action line
const code = 'actions=frost_strike,if=runic_power>=80';
const ast = parse(code);
console.log(JSON.stringify(ast, null, 2));

Condition Optimization

import { parse, optimize } from 'simc-ast-builder';

// Parse a SimC action with complex conditions
const code = 'actions=frost_strike,if=!(!runic_power>=80&!buff.killing_machine.up)';
const ast = parse(code);

// Optimize the AST to simplify conditions
const optimizedAst = optimize(ast);
console.log(JSON.stringify(optimizedAst, null, 2));

Custom Optimization Options

import { parse, optimize } from 'simc-ast-builder';

const code = 'actions=frost_strike,if=!(!runic_power>=80&buff.killing_machine.up)';
const ast = parse(code);

// Apply only specific optimizations
const customOptimizedAst = optimize(ast, { 
  enabled: true,               // Overall enable/disable flag for all optimizations
  doubleNegation: true,        // Simplify double negation (!!A → A)
  deMorgansLaw: true,          // Apply De Morgan's laws (!(A && B) → !A || !B)
  complementaryTerms: false,   // Simplify complementary terms (A && !A → false, A || !A → true)
  constantsAndIdentities: false, // Simplify constants and identity operations (true && A → A, false || A → A, etc.)
  absorptionLaws: false,       // Apply absorption laws (A && (A || B) → A, A || (A && B) → A)
  flattenNestedOperations: false, // Flatten nested operations (A && (B && C) → (A && B) && C)
  commonSubexpressions: false  // Eliminate common subexpressions ((A && B) || (A && C) → A && (B || C))
});

All-in-one Parsing and Optimization

import { generateAST } from 'simc-ast-builder';

const code = 'actions=frost_strike,if=runic_power>=80';
const result = generateAST(code);
// Result contains the optimized AST and any errors

Project Structure

• /src - Source code
  • /parser - ANTLR4 parser integration
    • /antlr4 - ANTLR4 grammar and generated files
    • /visitors - AST visitor implementation
  • /types - TypeScript type definitions
  • /utils - Utility functions including condition optimizer

Development

Prerequisites

• Node.js (v14+)
• npm or yarn

Setup

# Clone the repository
git clone https://github.com/legacy3/simc-ast-builder.git
cd simc-ast-builder

# Install dependencies
npm install

# Generate ANTLR4 parser from grammar
npm run generate

# Build the project
npm run build

# Run tests
npm test

Available Scripts

• npm run build - Build the project
• npm run generate - Generate ANTLR4 parser files from grammar
• npm test - Run tests
• npm run format - Format code with Prettier
• npm run lint - Lint code with ESLint

License

This project is licensed under the GPL-3.0 License.