java-commons/muscript

μ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 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:

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);