java-commons/muscript/README.md

# μScript

μScript was created to allow respackopts pack authors to specify conditions for loading resources
in a more human-friendly manner than the previous json tree-based system.
It is intended to be vaguely like java in its syntax, though it deviates in some aspects.
The language is parsed into an AST representation which is executed in-place, no compilation is performed.
μScript supports outputting data using various types, not just strings or booleans

## Value types

This DSL supports numbers (double), booleans, strings, objects, lists and functions.
The topmost operator of a condition must always return a boolean for it to be valid in the context of respackopts.
The values of input data are according to the pack config.
String literals may be written with quotation marks as follows: `"some text"` or `'some text'`
Numbers may be written as follows: `103` or `10.15`
Booleans may be written either as `true` or `false`
Objects, lists and functions cannot be created manually but may be provided to the script as parameters or from
functions.
Additionally, function parameters will automatically be packed in a list

Please ensure you use proper whitespace, as this might behave unexpectedly otherwise.

## Operators

Numbers support the following operators (x and y are numbers):

- Addition: `x + y`
- Subtraction: `x - y`
- Multiplication: `x * y`
- Division: `x / y`
- Modulo: `x % y`
- Power: `x ^ y`
- Inversion: `-x`
- Greater than: `x > y`
- Greater than or equal: `x >= y`
- Less than: `x < y`
- Less than or equal: `x <= y`
- Equality: `x == y`
- Inequality: `x != y`

Strings support the following operators (x and y are strings, a is any value):

- Equality: `x == y`
- Inequality: `x != y`
- Concatenation: `x || a` or `a || x`

Booleans support the following operators (x and y are booleans, a and b are values of the same type):

- Conditional: `x ? a : b`
- Inversion: `!x`
- And: `x & y`
- Or: `x | y`
- Equality (=XNOR): `x == y`
- Inequality (=XOR): `x != y`

Objects support the following operators (x is an object with an entry called `entry`):

- Value access via `.`: `x.entry`
- Value access via square brackets: `x["entry"]` (also supports other types)

Parentheses (`()`) may be used to indicate order of operation

Namespacing is done using double colons like in c++ (`namespace::value`), though it should not be used

## Embedding μScript

μScript is available as a [maven package](https://gitlab.com/JFronny/java-commons/-/packages) which you can add to your
project.
To use it, first parse a script via `Parser.parse(String script)` and convert the returned generic expression to a typed
one
by calling `as(Bool|String|Number|Dynamic)Expr`.
This process may throw a ParseException.
You can call `get(Dynamic<?> dataRoot)` on the result to execute the script on the provided data, which should be an
`ExpressionParameter` on which you called `StandardLib.addTo()` to add standard methods.
This is also where you can add custom data to be accessed by your script.
The execution of a script can throw a LocationalException which may be converted to a LocationalError for printing
using the source of the expression if available.
You may also call `StarScriptIngester.starScriptToMu()` to generate μScript code from StarScript code.

A full example could look as follows:

```java
String source = args[0];
Expr<?> parsed;
try {
    parsed = Parser.parse(source); // or Parser.parse(StarScriptIngester.starScriptToMu(source))
} catch (Parser.ParseException e) { // Could not parse
    System.err.println(e.error);
    return;
}
BoolExpr typed;
try {
    typed = parsed.asBoolExpr();
} catch (LocationalException e) {
    System.err.println(e.asPrintable(source));
    return;
}
ExpressionParameter parameter = StandardLib.addTo(new ExpressionParameter())
        .set("someValue", DFinal.of(15))
        .set("someOther", DFinal.of(Map.of(
                "subValue", DFinal.of(true)
        )));
boolean result;
try {
    result = typed.get(parameter);
} catch (LocationalException e) {
    System.err.println(e.asPrintable(source));
    return;
}
System.out.println("Result: " + result);
```