A Quick Introduction to Aviator: A Lightweight JVM Expression Engine and Script Language

Aviator Overview

Aviator started as a lightweight, high‑performance expression engine for the JVM and, since version 5.0.0, has become AviatorScript, a full‑featured script language that also runs on Android.

Key Features

Supports basic types such as numbers, strings, regex, booleans, and fully implements Java operators with correct precedence.

Functions are first‑class citizens, supporting closures and functional programming.

Built‑in bigint / decimal types for large integer and high‑precision arithmetic, with operator overloading (e.g., +-*/ ).

Complete script syntax including multiline data, conditionals, loops, lexical scopes, and exception handling.

Functional programming combined with the Sequence abstraction for convenient collection processing.

Lightweight module system.

Easy Java method invocation and full Java script API support.

Rich customization options, usable as a secure sandbox or a full‑featured language.

High performance: ASM mode compiles scripts to JVM bytecode; an interpreter mode works on non‑standard Java platforms like Android.

Typical Use Cases

Rule evaluation and rule engines.

Formula calculations.

Dynamic script control.

ELT and collection data processing.

Basic Usage

Adding the Dependency

Include the following Maven dependency in your project:

<dependency>
    <groupId>com.googlecode.aviator</groupId>
    <artifactId>aviator</artifactId>
    <version>5.3.3</version>
</dependency>

Evaluate a simple expression:

// Returns 16
Long r = (Long) AviatorEvaluator.execute("2 * (3 + 5)");

For better performance, compile the expression first and reuse it:

Expression expression = AviatorEvaluator.compile("2 * (3 + 5)");
Long r = (Long) expression.execute();

Expression Variables

Pass parameters to expressions using simple values, lists, or objects:

Long a = 12L;
Boolean r = (Boolean) AviatorEvaluator.exec("a > 10", a);

List
a = new ArrayList<>();
a.add(12L);
a.add(20L);
Boolean r = (Boolean) AviatorEvaluator.exec("a[0] > 10", a);

public static class Person {
    private String name;
    private Integer age;
}
Person p = new Person("movee", 25);
Boolean r = (Boolean) AviatorEvaluator.exec("p.age > 10", p);

Map
env = new HashMap<>();
env.put("person", new Person("movee", 25));
env.put("a", 20L);
Object result = AviatorEvaluator.execute("person.name", env);

Extract values from JSON structures directly:

String jsonStr = "{\"a\":{\"b\":[{\"x\":3},{\"x\":4}]}}";
JSONObject jsonObj = new JSONObject(jsonStr);
Object value = AviatorEvaluator.execute("a.b[0]['x']", jsonObj.toMap()); // returns 3

Using Functions

Aviator provides many built‑in functions:

// math.round
Long r = (Long) AviatorEvaluator.execute("math.round(4.3)");
// string.length
Long r = (Long) AviatorEvaluator.execute("string.length('hello')");
// seq.list
Object r = AviatorEvaluator.execute("seq.list(1,2,3)");

You can also define custom Java functions by extending AbstractFunction and registering them:

public class AddFunction extends AbstractFunction {
    @Override
    public AviatorObject call(Map
env, AviatorObject arg1, AviatorObject arg2) {
        long num1 = FunctionUtils.getNumberValue(arg1, env).longValue();
        long num2 = FunctionUtils.getNumberValue(arg2, env).longValue();
        return AviatorLong.valueOf(num1 + num2);
    }
    @Override
    public String getName() { return "add"; }
}

AviatorEvaluator.addFunction(new AddFunction());
Long sum = (Long) AviatorEvaluator.getInstance().execute("add(3,4)"); // returns 7

AviatorScript

Beyond single expressions, AviatorScript allows full script execution. Scripts are typically stored in files with the .av extension.

// hello.av
if (a > 10) {
    return 10;
} else {
    return a;
}

Execute the script with parameters:

Map
env = new HashMap<>();
env.put("a", 30);
Expression exp = AviatorEvaluator.getInstance().compileScript("./hello.av", true);
Object result = exp.execute(env); // returns 10

For more details, refer to the official repository: https://github.com/killme2008/aviatorscript