docs: Document StandardLib and GsonLib functions for μScript users
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful
This commit is contained in:
parent
e927d1f82c
commit
e84f8adc88
10
muscript-gson/README.md
Normal file
10
muscript-gson/README.md
Normal file
|
@ -0,0 +1,10 @@
|
||||||
|
# μScript-gson
|
||||||
|
μScript-gson bridges the gap between μScript and commons-gson by supporting the serialization and deserialization of `Dynamic` to json and exposing this functionality to μScript scripts.
|
||||||
|
The gson type adapters are automatically registered to any `GsonHolder`, but the μScript methods need to be added to your `Scope` manually via `GsonLib.addTo(scope)`.
|
||||||
|
Other than that, no setup is needed.
|
||||||
|
|
||||||
|
## Exposed functions
|
||||||
|
| signature | description |
|
||||||
|
|------------------------------|-------------------------------------------------------|
|
||||||
|
| `toJson(src: any): string` | Serializes `scr` to json |
|
||||||
|
| `fromJson(src: string): any` | Deserialized `src` into the appropriate μScript types |
|
|
@ -9,8 +9,11 @@ The language is parsed into an AST representation which is executed in-place, no
|
||||||
μScript supports outputting data using various types, not just strings or booleans.
|
μScript supports outputting data using various types, not just strings or booleans.
|
||||||
|
|
||||||
The purpose of this document is to be a guide on embedding μScript in your application or library.
|
The purpose of this document is to be a guide on embedding μScript in your application or library.
|
||||||
|
|
||||||
For details on how to use the language, look [here](src/test/resources/example.md).
|
For details on how to use the language, look [here](src/test/resources/example.md).
|
||||||
|
|
||||||
|
For details on the standard library provided by μScript, look [here](StandardLib.md).
|
||||||
|
|
||||||
## Embedding μScript
|
## Embedding μScript
|
||||||
|
|
||||||
μScript is available as a [maven package](https://maven.frohnmeyer-wds.de/#/artifacts/io/gitlab/jfronny/muscript) which you can add to your
|
μScript is available as a [maven package](https://maven.frohnmeyer-wds.de/#/artifacts/io/gitlab/jfronny/muscript) which you can add to your
|
||||||
|
|
77
muscript/StandardLib.md
Normal file
77
muscript/StandardLib.md
Normal file
|
@ -0,0 +1,77 @@
|
||||||
|
# μScript Standard Library
|
||||||
|
|
||||||
|
The purpose of this document is to be a guide to the standard library provided by μScript.
|
||||||
|
It is not intended to explain the syntax of the language or provide information on its history, implementation, or how to embed it in programs.
|
||||||
|
|
||||||
|
For information on that, look at the [language guide](src/test/resources/example.md) and the [developer info](README.md).
|
||||||
|
|
||||||
|
## Types
|
||||||
|
| name | description |
|
||||||
|
|----------|-----------------------------------------------------------------------------------------------------|
|
||||||
|
| number | Equivalent to a java double, the only number type in muScript |
|
||||||
|
| bool | A boolean. Either true or false |
|
||||||
|
| null | Equivalent to null in java or Unit in kotlin |
|
||||||
|
| string | A sequence of characters |
|
||||||
|
| list | An ordered sequence of items of any type |
|
||||||
|
| object | A mapping between keys (string) and values (any) |
|
||||||
|
| callable | A value that can be invoked via `()` |
|
||||||
|
| date | Represents a calendar date. Can be represented as string, number (days since 01-01-1970) and object |
|
||||||
|
| time | Represents a time of day. Can be represented as a string, number (second of day) and object |
|
||||||
|
| enum | Details below |
|
||||||
|
| try | Details below |
|
||||||
|
|
||||||
|
### Enum
|
||||||
|
A map between names and values of any type. Can also be represented as a list of names.
|
||||||
|
One entry may be selected, its index will be accessible as the number representation and its name as the string representation of the enum.
|
||||||
|
|
||||||
|
### Try
|
||||||
|
An `object` returned by the `try` function. Contains the following entries:
|
||||||
|
- `result`: The result of executing the closure, the result of `catch` if it failed and `catch` was called, or `null`
|
||||||
|
- `catch(handler: {string -> any})`: If the execution of the closure failed,
|
||||||
|
`handler` will be executed with the error message and its result will be provided as `result`.
|
||||||
|
No more than one `catch` may exist per `try`.
|
||||||
|
|
||||||
|
## Functions
|
||||||
|
The standard library also provides a number of default utility functions.
|
||||||
|
Below, these are listed alongside their arguments.
|
||||||
|
The syntax used for signatures in this list is not used elsewhere and not part of the language.
|
||||||
|
|
||||||
|
### Signature syntax
|
||||||
|
- If a parameter is suffixed with `?`, it can be omitted. If omission is equivalent to a default value, it will be listed with the default behind an equals sign
|
||||||
|
- If a parameter is suffixed with `...`, it will be variadic (support 0 or more arguments)
|
||||||
|
- If multiple types are possible, they are listed as `T1 / T2`, where T1 is preferred over T2
|
||||||
|
- If an object supports multiple representations, it will be denoted as `T1 & T2`
|
||||||
|
- Callables are represented like closures but with types instead of names
|
||||||
|
|
||||||
|
### Supported functions
|
||||||
|
| signature | description |
|
||||||
|
|---------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||||
|
| `round(value: number, decimalPlaces?: number = 0): number` | Rounds `value` while retaining `decimalPlaces` places after the comma |
|
||||||
|
| `floor(value: number): number` | Returns the largest integer lower than or equal to `value` |
|
||||||
|
| `ceil(value: number): number` | Returns the smallest integer larger than or equal to `value` |
|
||||||
|
| `abs(value: number): number` | Returns the absolute value of `value` (always positive or zero) |
|
||||||
|
| `random(min?: number = 0, max?: number = 1): number` | Returns a random number between `min` and `max`. If `min` is provided, `max` cannot be omitted. |
|
||||||
|
| `toUpper(value: string): string` | Converts all characters in `value` to upper case |
|
||||||
|
| `toLower(value: string): string` | Converts all characters in `value` to lower case |
|
||||||
|
| `contains(in: list / object / string, find: any): bool` | Checks whether `find` is an element of the list, a key of the object or a substring of the string provided as `in` |
|
||||||
|
| `replace(source: string, target: string, replacement: string): string` | Replaces all instances of `target` in `source` with `replacement` and returns the result |
|
||||||
|
| `listOf(elements: any...): list` | Creates a list with the provided elements |
|
||||||
|
| `len(toCheck: string / object / list): number` | Gets the amount of characters in the string or entries in the object or list provided as `toCheck` |
|
||||||
|
| `isEmpty(toCheck: object / list): bool` | Checks whether the object or list provided as `toCheck` contain any entries |
|
||||||
|
| `concat(lists: list...): list` | Returns a list containing all elements of all provided lists in their original order |
|
||||||
|
| `filter(in: list, with: {any -> bool}): list` | Returns a list of all elements `el` of `in` for which `with(el)` returned true |
|
||||||
|
| `allMatch(in: list, with: {any -> bool}): bool` | Whether `with(el)` is true for all elements `el` of `in` |
|
||||||
|
| `anyMatch(in: list, with: {any -> bool}): bool` | Whether `with(el)` is true for any element `el` of `in` |
|
||||||
|
| `map(in: list, with: {any -> any}): list` | Returns a list of the results of applying `with` to all elements of `in` |
|
||||||
|
| `flatMap(in: list, with: {any -> list}): list` | Returns the concatenated list of the results of applying `with` to all elements of `in` |
|
||||||
|
| `fold(in: list, identity: any, operator: {any, any -> any}): any` | Runs `operator(previous, current)` for every element in `in` where `previous` is the previous result of `operator`, starting with `identity` and `current` is the current element |
|
||||||
|
| `forEach(in: list, with: {any -> any}): any` | Runs `with` for each element in `in`, returning the last result or `null` for empty lists |
|
||||||
|
| `toObject(from: list, keyMapper: {any -> string}, valueMapper: {any -> any}): object` | Creates an object mapping the results of `keyMapper` to the results of `valueMapper` for every element in `from` |
|
||||||
|
| `callableObject(source: object, action: callable): object & callable` | Returns an object equivalent to `source` that can be called, resulting in the invocation of `action` |
|
||||||
|
| `enum(values: object, selected?: string): enum` | Creates an enum with the values provided as `values`, optionally marking the one with the key `selected` as such |
|
||||||
|
| `keys(ob: object): list` | Returns the list of names of entries of the object `ob` |
|
||||||
|
| `values(ob: object): list` | Returns the list of values of entries of the object `ob` |
|
||||||
|
| `try(closure: {any... -> any}, args: any...): try` | Attempts to execute the closure with the provided args and returns a `try`. For details on what to do with that, look above. |
|
||||||
|
|
||||||
|
Other project-specific functions (like [μScript-gson](../muscript-gson/README.md)) will likely also be available to your scripts.
|
||||||
|
Please consult the documentation for the project using μScript for more information on what is available or use `this::keys()` to view everything.
|
|
@ -194,7 +194,7 @@ public class StandardLib {
|
||||||
|
|
||||||
public static DList map(DList args) {
|
public static DList map(DList args) {
|
||||||
if (args.size() != 2) throw new IllegalArgumentException("Invalid number of arguments for map: expected 2 but got " + args.size());
|
if (args.size() != 2) throw new IllegalArgumentException("Invalid number of arguments for map: expected 2 but got " + args.size());
|
||||||
return of(args.get(0).asList().getValue().stream().<Dynamic>map(args.get(1).asCallable()::call).toList());
|
return of(args.get(0).asList().getValue().stream().map(args.get(1).asCallable()::call).toList());
|
||||||
}
|
}
|
||||||
|
|
||||||
public static DList flatMap(DList args) {
|
public static DList flatMap(DList args) {
|
||||||
|
|
|
@ -7,6 +7,7 @@ import io.gitlab.jfronny.muscript.ast.Expr;
|
||||||
import io.gitlab.jfronny.muscript.compiler.ExprWriter;
|
import io.gitlab.jfronny.muscript.compiler.ExprWriter;
|
||||||
import io.gitlab.jfronny.muscript.compiler.Parser;
|
import io.gitlab.jfronny.muscript.compiler.Parser;
|
||||||
import io.gitlab.jfronny.muscript.data.dynamic.additional.*;
|
import io.gitlab.jfronny.muscript.data.dynamic.additional.*;
|
||||||
|
import io.gitlab.jfronny.muscript.data.dynamic.lens.DStringLens;
|
||||||
import org.jetbrains.annotations.NotNull;
|
import org.jetbrains.annotations.NotNull;
|
||||||
import org.jetbrains.annotations.Nullable;
|
import org.jetbrains.annotations.Nullable;
|
||||||
|
|
||||||
|
@ -76,7 +77,7 @@ public sealed interface Dynamic permits DBool, DCallable, DList, DNull, DNumber,
|
||||||
|
|
||||||
default DString asString() {
|
default DString asString() {
|
||||||
if (this instanceof DString string) return string;
|
if (this instanceof DString string) return string;
|
||||||
else return DFinal.of(StringFormatter.toString(getValue()));
|
else return new DStringLens(this, () -> StringFormatter.toString(getValue()));
|
||||||
}
|
}
|
||||||
|
|
||||||
default boolean isObject() {
|
default boolean isObject() {
|
||||||
|
|
|
@ -2,8 +2,11 @@
|
||||||
|
|
||||||
The purpose of this document is to be a guide to using the μScript language.
|
The purpose of this document is to be a guide to using the μScript language.
|
||||||
It is not intended to explain any history of the language, implementation details or details on how to embed μScript in programs.
|
It is not intended to explain any history of the language, implementation details or details on how to embed μScript in programs.
|
||||||
|
|
||||||
For information on that, look [here](../../../README.md).
|
For information on that, look [here](../../../README.md).
|
||||||
|
|
||||||
|
For information on the standard library provided by μScript, look [here](../../../StandardLib.md)
|
||||||
|
|
||||||
## Types
|
## Types
|
||||||
μScript supports a couple of basic types, namely:
|
μScript supports a couple of basic types, namely:
|
||||||
- [Numbers](#numbers) (double-precision floating-point)
|
- [Numbers](#numbers) (double-precision floating-point)
|
||||||
|
@ -43,12 +46,12 @@ listOf(
|
||||||
4 >= 4,
|
4 >= 4,
|
||||||
5 != 2,
|
5 != 2,
|
||||||
8 == 8,
|
8 == 8,
|
||||||
round(PI, 2) + floor(E) // round also accepts a second argument: precision, but it can be ommitted to round to a whole number
|
round(PI, floor(E)) // round also accepts a second argument: decimalPlaces, but it can be ommitted to round to a whole number
|
||||||
)
|
)
|
||||||
```
|
```
|
||||||
Result:
|
Result:
|
||||||
```
|
```
|
||||||
[7, -3, 2, 8, 12, 2, 2, 1024, true, false, true, true, true, 5.1400]
|
[7, -3, 2, 8, 12, 2, 2, 1024, true, false, true, true, true, 3.14]
|
||||||
```
|
```
|
||||||
</details>
|
</details>
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue
Block a user