java-commons/muscript-runtime/StandardLib.md
JFronny 24aab51a4b
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful
feat(muscript-gson): rename to muscript-json and port to commons-serialize-json
2024-04-12 21:19:36 +02:00

11 KiB

μ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 and the developer info.

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