aviator-parser

A Pratt-style parser for Aviator Script.

Since Aviator Script does not expose a public parser API, this project implements a standalone parser that builds an AST for Aviator expressions. With it, you can analyze, validate, transform, or interpret Aviator expressions without relying on the full Aviator runtime.

This library also includes a short-circuit evaluator, implemented as a demonstration and provided as part of the core module.

Maven

<dependency>
  <groupId>io.github.drincann</groupId>
  <artifactId>aviator-parser</artifactId>
  <version>0.7.0</version>
</dependency>

Build & Test

mvn clean verify

Features

• Pratt Parsing for operator precedence and associativity

• Immutable AST with distinct nodes for operators, calls, lambdas, variadic parameters, argument unpacking, and first-class operator references

• Reverse Polish Notation (RPN) and serialization utilities

• Short-circuit analysis engine with staged execution

Usage

Expression Parser

This parser is designed for expression-style Aviator syntax (i.e., non-Turing-complete scripts). It parses expressions and returns an AST that can be further inspected or transformed.

Expr ast = Pratt.parse("A == 1 ? (lambda (x) -> x + 1 end)(1) : func_call(a, b)");

System.out.println("Serialized: " + ast.serialize()); 
// Output: ((A == 1) ? lambda (x) -> (x + 1) end(1) : func_call(a, b))

System.out.println("Reverse Polish Notation: " + ast.rp()); 
// Output: (? (== A 1) (lambda (x) -> (+ x 1) end 1) (func_call a b))

// AST inspection
assert ast instanceof Node;
assert ast.getChildren().size() == 3;

Node condition = (Node) ast.getChildren().get(0);
FunctionCall thenExpr = (FunctionCall) ast.getChildren().get(1);
assert thenExpr.getFunction() instanceof LambdaFunction;

FunctionCall elseExpr = (FunctionCall) ast.getChildren().get(2);
List<Expr> arguments = elseExpr.getArguments();

Short-circuit Evaluator

You can use the short-circuit evaluator to determine whether an expression can be executed given a partially known variable set. This is useful in staged or lazy evaluation contexts, such as rule engines or event-driven flows.

PendingExecution pending = AviatorPendingExecutionFactory.compile(
    new SimpleAviatorRuntime(), // A user-defined runtime interface
    "A && !(B && C)"
);

The first argument to compile(...) is an implementation of AviatorRuntime. This interface decouples the evaluator from Aviator's internal runtime, giving you full control over variable resolution. A minimal implementation SimpleAviatorRuntime is provided as a demonstration:

public class SimpleAviatorRuntime implements ExpressionRuntime {
    @Override
    public Object run(String expression, Map<String, Object> context) {
        return AviatorEvaluator.compile(expression, true).execute(context);
    }
}

Sample usage:

assert pending.canExecute() == false;

pending.provide("B", true);
assert pending.canExecute() == false;

pending.provide("C", true);
assert pending.canExecute() == true;

assert pending.execute() == false;

Architecture

AST Hierarchy

• Expr: Base interface

• Leaf: Atomic expressions (identifiers, literals)

• Node: Composite expressions (binary, ternary, grouped)

• FunctionCall: Function invocation node with arguments

• LambdaFunction: First-class anonymous function

Pratt Parser

The parser is based on Pratt's top-down operator precedence parsing. It supports:

• Custom token precedence and binding power

• Arithmetic, logical, and comparison operations

• Function calls, argument unpacking, variadic lambdas, and operator references

• Conditional (ternary) expressions

• Numeric forms, regexes, quoted identifiers, comments, bit operations, shifts, exponentiation, indexing, and assignment expressions

This design enables modular parsing without deep recursion or grammar ambiguity.

Statement scripts (if, let, return, named fn, loops, and exception handling) are intentionally outside this parser's expression boundary.

Contributing

Pull requests and issues are welcome. Feel free to contribute features, tests, or improvements.

License

This project is licensed under the WTFPL, see LICENSE for details.

You can do anything you want with this code, including using it in commercial applications, without any restrictions.