A lightweight, fast and efficient Molang lexer, parser, interpreter and compiler for Java 8+

<h2>Bindings</h2>
There are two ways to bind a external function/property to the Mocha environment so that
it can be used from the used expressions.
<h3>1. Function interface</h3>
The way is faster for interpreted expressions, but slower for compiled expressions.
<pre><code class="hljs language-java">MochaEngine&#x3C;?> mocha = MochaEngine.createStandard();

// query.get_age()
mocha.scope().query().set("get_age", (ctx, args) -> {
 return NumberValue.of(18);
});

mocha.eval("query.get_age()"); // evaluates to 18
</code></pre>
<h3>2. Java methods</h3>
This way is faster for compiled expressions, since they can directly call the methods, but
it is a lot slower for interpreted expressions, since they have to use reflection to call
them.
<pre><code class="hljs language-java">@Binding("random")
public class RandomBinding {
 // random.select(a, b)
 @Binding("select")
 public static double select(double a, double b) {
 return Math.random() &#x3C; 0.5 ? a : b;
 }
}

// ...
MochaEngine&#x3C;?> mocha = MochaEngine.createStandard();

mocha.scope().forceSet("random", JavaObjectBinding.of(RandomBinding.class, new RandomBinding()));

mocha.compile("random.select(1, 2)").evaluate(); // evaluates to either 1 or 2
// generates the following code:
// return RandomBinding.select(1, 2);
</code></pre>
<h3>3. Use both</h3>
Mocha allows you to use both approaches so that you can use the best of both worlds.
With this approach, compiled expressions will prefer the Java methods, while interpreted
expressions will prefer the function interfaces.
<pre><code class="hljs language-java">@Binding("random")
public class RandomBinding implements ObjectValue {
 // random.select(a, b)
 @Binding("select")
 public static double select(double a, double b) {
 return Math.random() &#x3C; 0.5 ? a : b;
 }
 
 @Override
 public @NotNull Value get(String name) {
 if (name.equals("select")) {
 return (Function&#x3C;?>) (ctx, args) ->
 NumberValue.of(select(args[0].asDouble(), args[1].asDouble()));
 }
 return Value.nil();
 }
}

mocha.scope().forceSet("random", JavaObjectBinding.of(RandomBinding.class, new RandomBinding()));

mocha.compile("random.select(1, 2)").evaluate(); // uses Java method

mocha.evaluate("random.select(1, 2)"); // uses Function
</code></pre>

Bindings

<h2>Getting Started</h2>
Welcome to the <code>mocha</code> documentation
<code>mocha</code> is a lightweight, fast and efficient Molang lexer, parser, interpreter
and compiler for Java 8+. Molang is a simple expression-based language designed
for fast and data-driven calculation of values at run-time.
For more information about the Molang language, check their official documentation
at <a href="https://learn.microsoft.com/en-us/minecraft/creator/reference/content/molangreference/examples/molangconcepts/molangintroduction?view=minecraft-bedrock-stable">learn.microsoft.com</a>.
<h3>Features</h3>
<ul>
<li>Fast computing. mocha can compile Molang expressions directly to JVM bytecode,
no need to parse and interpret the expression every time, zero overhead.</li>
<li>Extensive API, you can bind objects and functions to the Molang expression
environment, so that they can be called from the evaluated expressions.</li>
<li>Lightweight, mocha is a small library with a single dependency: javassist, it's easy to
integrate in your project.</li>
</ul>
<h3>mocha vs other Molang libraries</h3>
Here are some (reduced) results from a benchmark comparing mocha with other Molang
libraries, ordered from fastest to slowest. (To run the benchmark yourself, run
<code>./gradlew jmh</code>)
<pre><code class="hljs language-python"> Benchmark Mode Cnt Score Error Units
1. unnamed's mocha sample 8874677 0.035 ± 0.006 us/op
2. MoonflowerTeam's molang-compiler sample 7507288 0.041 ± 0.007 us/op
3. bedrockk's MoLang sample 5404802 6.449 ± 0.158 us/op
</code></pre>
To run the benchmark yourself, run <code>./gradlew jmh</code>. You can also check the benchmark
source code <a href="https://github.com/unnamed/mocha/blob/main/src/jmh/java/team/unnamed/mocha/CompareBenchmark.java">here</a>.

Getting Started

<h2>Installation</h2>
You can add <code>mocha</code> to your project using <a href="https://gradle.org/">Gradle</a>
(recommended), <a href="https://maven.apache.org/">Maven</a> or manually downloading the
JAR files from <a href="https://github.com/unnamed/mocha/releases">GitHub Releases</a>.
Note that <code>mocha</code> is available in the Maven Central Repository.
<h3>Gradle</h3>
<pre><code class="hljs language-kotlin">dependencies {
 implementation("team.unnamed:mocha:3.0.0")
}
</code></pre>
<h3>Maven</h3>
<pre><code class="hljs language-xml">&#x3C;dependency>
 &#x3C;groupId>team.unnamed&#x3C;/groupId>
 &#x3C;artifactId>mocha&#x3C;/artifactId>
 &#x3C;version>3.0.0&#x3C;/version>
&#x3C;/dependency>
</code></pre>

Installation

<h2>Usage</h2>
Create a new MochaEngine instance with the static factory method <code>MochaEngine.createStandard()</code>,
which will create the instance with the standard configuration, where everything tries to be
as spec-compliant as possible.
<pre><code class="hljs language-java">MochaEngine&#x3C;?> mocha = MochaEngine.createStandard();
</code></pre>
Then we can either evaluate (interpret) or compile Molang code.
<h3>Evaluate</h3>
To evaluate expressions we can just use the <code>eval</code> method.
<pre><code class="hljs language-java">double result = mocha.eval("math.sqrt(3 * 3 + 4 * 4)");
// evaluates to 5.0

double result2 = mocha.eval("math.abs(-5) + 5");
// evaluates to 10.0
</code></pre>
Or if we might want to evaluate the same expression multiple times,
we can cache the parsed expressions.
<pre><code class="hljs language-java">MochaFunction function = mocha.prepareEval("math.sqrt(3 * 3 + 4 * 4)");

function.evaluate();
// evaluates to 5.0

function.evaluate();
// evaluates to 5.0
</code></pre>
<h3>Compile</h3>
Compiling expressions is pretty similar to preparing them and evaluating them
later, but faster.
<pre><code class="hljs language-java">MochaFunction function = mocha.compile("math.sqrt(3 * 3 + 4 * 4)");
// will compile a class that implements MochaFunction, with the following
// code:
// return Math.sqrt(25);
// note that the compiler can optimize constant expressions like 3*3+4*4 to just 25

function.evaluate();
// evaluates to 5.0, no interpretation overhead

function.evaluate();
// evaluates to 5.0, no interpretation overhead
</code></pre>
We could also specify the function type we would like to get.
<pre><code class="hljs language-java">interface CompareFunction extends MochaCompiledFunction {
 boolean compare(@Named("a") double a, @Named("b") double b);
}

// ...
CompareFunction gt = mocha.compile("a > b", CompareFunction.class);

gt.compare(5, 4);
// true

gt.compare(4, 5);
// false

gt.compare(5, 5);
// false
</code></pre>