AviatorScript on the JVM: a lightweight scripting language for rules and formulas

What AviatorScript is for, and who ends up using it

The README describes AviatorScript as a high performance, lightweight scripting language hosted on the JVM, including Android. Its stated use cases are rule judgement and rule engines, formula computation, dynamic script control and collection ELT. That list is narrower than "a general purpose language", and the design follows from it. The people who reach for it are Java engineers who need an expression or a short script to be editable outside the compiled application: a pricing formula, a scoring rule, a filter over a list of records. The README also carries a blunt line aimed at people who mistake the project for something else, stating it is not a game and is a programming language. That line exists because the name collides with an unrelated gambling game, which is also why the search data for the project is polluted.

The feature list is the useful part of the pitch. Functions are first class, with closures and functional programming. bigint and decimal are built in for large integers and high precision arithmetic, and operator overloading lets those types participate in ordinary + - * / expressions. The language has multi-line data, conditionals, loops, lexical scope and exception handling. Sequences are an abstraction for working over collections. There is a module system, several ways to call Java methods, and support for the Java scripting API so Java can invoke scripts. Compilation results can be serialized for caching, and evaluation can be given a timeout so a destructive script cannot exhaust resources.

How the runtime works: ASM bytecode, an interpreter, and a sandbox switch

AviatorScript has two execution paths. In ASM mode the script is compiled directly into JVM bytecode, which is the high performance path the README advertises. In interpreter mode the same script runs without that compilation step, which is what makes Android and other non-standard Java platforms viable. The choice matters because the two paths do not have identical constraints: bytecode generation ties you to what the JVM accepts, while the interpreter is the fallback when that is not available.

Around that core sit several mechanisms that a rule engine actually needs. Compiled results can be serialized, so a script can be compiled once and cached rather than parsed on every request. Evaluation can be given a timeout, which is the difference between a bad rule and a hung worker thread. The module system is lightweight, and the sandbox is a configuration of the language rather than a separate product: the README lists rich customization options and says the language can serve both as a safe sandbox and as a full-featured language. Version 5.4.3 added a one-call method for enabling the secure sandbox, and 5.4.4 went further by removing the io module in sandbox mode, with the release note recommending the upgrade to anyone running sandboxed. That is a security fix, not a feature: if you enabled the sandbox and your scripts used io, the upgrade changes what they can do.

The 5.4.4 release also refactored the lexer and parser and added support for dotted property access without the # prefix, so a.b.c and foo.bars[0].name now work. If you have scripts written against the older syntax, the parser change is worth a read before you upgrade.

Installing AviatorScript and running a first script

There are two entry points. For a Java project, the README gives a Maven dependency, and it points at search.maven.org for the list of available versions. The README recommends version 5.2.6 or later.

<dependency>
  <groupId>com.googlecode.aviator</groupId>
  <artifactId>aviator</artifactId>
  <version>{version}</version>
</dependency>

For trying the language without touching a build file, download the shell script from the repository's bin directory, make it executable, and run it. The README's example puts it in ~/bin/aviator and uses wget and chmod.

wget https://raw.githubusercontent.com/killme2008/aviator/master/bin/aviator
chmod u+x aviator

Running the aviator command downloads the latest released jar into an installation directory under ~/.aviatorscript and then starts it. The usage output the README shows is three forms: a file, the -e flag for an inline script, and -v for the version.

aviator
Usage: java com.googlecode.aviator.Main [file] [args]
     : java com.googlecode.aviator.Main -e [script]
     : java com.googlecode.aviator.Main -v

Save a script as hello.av and run it with aviator hello.av. The README's example prints a greeting, builds a tuple of five numbers, reduces it with the + operator, and calls into java.util.Date to print the year and month.

p("Hello, AviatorScript!");

let a = tuple(1, 2, 3, 4, 5);

p("sum of a is: " + reduce(a, +, 0));

let date = new java.util.Date();
p("The year is: "+ getYear(date));
p("The month is: #{getMonth(date)}");

The expected output, as the README shows it, is the greeting, sum of a is: 15, and the year and month lines. Note the two interpolation styles in that snippet: string concatenation with +, and the #{...} form inside a string literal. The README also links a longer calculator example at examples/calculator.av for evaluating arithmetic expression strings, and the examples directory holds files for closures, bigint, bigdecimal, collections, file IO and the various loop forms.

Where AviatorScript is the wrong tool

The documentation problem is real and it is the first thing a new user hits. The repository README is written in Chinese and the English documentation is a separate file, README-EN.md. The substantive material, the user guide, the changelog and the type reference, lives on Yuque, an external hosted documentation site, not in the repository. The repository itself contains a pom.xml, a src directory, an examples directory and a bin directory. There is no doc directory. If your team needs documentation that travels with the source, or that can be reviewed in a pull request, this layout is a mismatch.

The licence is the second gap. The repository carries a licenses.txt file at the top level, but the project metadata does not state a licence identifier. Before adopting a dependency in a commercial codebase, read licenses.txt and any bundled third-party notices yourself. Nothing in the README settles the question.

Version history is the third thing to weigh. The gap between 5.4.3 in June 2024 and 5.4.4 in July 2026 is roughly two years, and 5.4.3 and 5.4.2 are one day apart. That is not a release cadence you can plan a quarterly upgrade around. The last push to the repository was on 2026-07-27, which is recent, but a single release after a long quiet period is a different signal from steady monthly releases.

Finally, treat the sandbox as a boundary you configure rather than one you inherit. The 5.4.4 note about removing the io module in sandbox mode is the clearest evidence that the sandbox is an active surface, and that what it permits can change between versions. If you evaluate scripts from users, pin your version and read the release notes before moving.

AviatorScript compared with QLExpress

QLExpress is the comparison people search for, and the two projects occupy the same niche: a Java-hosted expression language for rules and dynamic evaluation. The difference in approach is in how much language you get. QLExpress is positioned around rule and expression evaluation with a Java-flavoured syntax and a macro system; AviatorScript presents itself as a full scripting language first, with the rule engine as one of several use cases. The README's feature list backs that up with closures, first-class functions, a Sequence abstraction, a module system, bigint and decimal types with operator overloading, and serializable compiled output.

The practical consequence is that AviatorScript asks more of the reader. A richer language means more surface to learn and more ways for a script to surprise the person who wrote it, and the documentation for that surface is on Yuque. QLExpress is the more conservative choice if all you need is an expression evaluator and you want the smallest possible language. AviatorScript is the better fit when the expressions are really small programs: loops over collections, closures passed to a reduce, high precision decimal arithmetic that has to use ordinary operators. The timeout and serialization features are the part that matters most in production, because they are what let you run untrusted or user-edited logic without giving it unbounded time or paying parse cost on every call.

Upgrade cost and what the licence question means for you

Upgrading across the 5.4.3 to 5.4.4 boundary has two concrete costs. The first is the sandbox change: the io module is no longer available in sandbox mode. The release note frames this as a security fix and recommends the upgrade for anyone using the sandbox, so the trade is deliberate. If your sandboxed scripts read or write files through io, they will need a different approach or an unsandboxed execution path.

The second is the lexer and parser refactor. Dotted property access without the # prefix is now supported, which is an addition, but a refactored parser is the kind of change that can shift error messages and edge-case behaviour. The release note mentions several bug fixes without enumerating them. The repository does not document a rollback procedure for a compiled script cache, so if you serialize compiled results, assume you will recompile after the upgrade rather than reuse the old cache.

On licensing, the honest answer is that the README does not state a licence and the metadata does not either. The repository has a licenses.txt at the top level, and the README links to Maven Central. Check both before you ship, because a dependency whose terms you have not read is a dependency you cannot defend in a review.

Editorial conclusion

Adopt AviatorScript when you need user-editable expressions or rules evaluated inside a JVM process and you accept a language whose full documentation lives on Yuque rather than in the repository. Do not adopt it for general application logic, and do not run it on untrusted input without enabling the sandbox. Before upgrading, read the 5.4.4 release note about the io module and confirm whether your scripts import it.

Frequently asked questions

Official sources

1. Issues
2. killme2008/aviatorscript on GitHub
3. Project website
4. README
5. Releases