77 lines
11 KiB
Markdown
77 lines
11 KiB
Markdown
|
# μ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.
|