built-in functions you can rely on
MiniScript comes with a standard set of built-in (or intrinsic) functions. Many of these are globals (i.e., referred to by variables in the global space). Others (particularly functions intended for use with strings, lists, and maps) are normally invoked via dot syntax after an identifier.
In fact, though, all intrinsic functions that use dot syntax are written in such a way that they can also be invoked as global functions. So, for example, you can get the length of a string s by typing s.len, but you can also do the same thing as len(s).
The following tables list the standard intrinsic functions, divided by data type on which they operate. Keep in mind that MiniScript is intended to be embedded in some host environment, such as a game or application. The host will normally add additional intrinsic functions particular to that environment. Please consult the documentation or help materials for your host environment for information on these extra functions.
Numeric Functions
MiniScript includes a selection of trigonometric functions, which all work in radians (rather than degrees), and other math functions, as well as random numbers and conversion of numbers into strings.
In the following table, x is any number, i is an integer, and r is a number of radians.
| abs(x) | absolute value of x |
| acos(x) | arccosine of x, in radians |
| asin(x) | arcsine of x, in radians |
| atan(y, x=1) | arctangent of y/x, in radians (returns correct quadrant if optional x parameter is used) |
| ceil(x) | next whole number equal to our greater than x |
| char(i) | returns Unicode character with code point i (see string .code for the inverse function) |
| cos(r) | cosine of r radians |
| floor(x) | next whole number less than or equal to x |
| log(x, base=10) | logarithm (with the given base) of x, i.e., the value y such that base^y == x |
| pi | 3.14159265358979 |
| range(x, y=0, step=null) | returns a list containing values from x through y, in ncrements of step; step == null is treated as a step of 1 if y > x, or -1 otherwise |
| round(x, d=0) | x rounded to d decimal places |
| rnd(seed=null) | if seed=null, returns random number in the range [0,1); if seed != null, seeds the random number generator with the given integer value |
| sign(x) | sign of x: -1 if x < 0; 0 if x == 0; 1 if x > 0 |
| sin(r) | sine of r radians |
| sqrt(x) | square root of x |
| str(x) | converts x to a string |
| tan(r) | tangent of r radians |
String Functions
All string functions except slice are designed to be invoked on strings using dot syntax, but can also be invoked as globals with the string passed in as the first parameter. Note that strings are immutable; all string functions return a new string, leaving the original string unchanged. In the following table, self refers to the string, s is another string argument, and i is an integer number.
| .code | Unicode code point of first character of self (see numeric char function for inverse) |
| .hasIndex(i) | 1 if i is in the range 0 to self.len-1; otherwise 0 |
| .indexes | range(0, self.len-1) |
| .indexOf(s, after=null) | 0-based position of first substring s within self, or null if not found; optionally begins the search after the given position |
| .insert(index, s) | returns new string with s inserted at position 0 |
| .len | length (number of characters) of self |
| .lower | lowercase version of self |
| .remove(s) | self, but with first occurrence of substring s removed (if any) |
| .replace(oldval, newval, maxCount=null) | returns a new string with up to maxCount occurrences of substring oldval replaced with newval (if maxCount unspecified, then replaces all occurrences) |
| .upper | uppercase version of self |
| .val | converts self to a number (if self is not a valid number, returns 0) |
| .values | list of individual characters in self (e.g. „spam“.values = [„s“, „p“, „a“, „m“] |
| slice(s, from, to) | equivalent to s[from:to] |
| .split(delimiter=“ „, maxCount=null) | splits the string into a list by the given delimiter, with at most maxCount entries (if maxCount is unspecified, then splits into a list of any size) |
List Functions
All list functions except slice are designed to be invoked on lists using dot syntax, but can also be invoked as globals with the list passed in as the first parameter. Lists are mutable; the pop, pull, push, shuffle, and remove functions modify the list in place. To use a list like a stack, add items with push and remove them with pop. To use a list like a queue, add items with push and remove them with pull.
In the following table, self is a list, i is an integer, and x is any value.
| .hasIndex(i) | 1 if i is in the range 0 to self.len-1; otherwise 0 |
| .indexes | range(0, self.len-1) |
| .indexOf(x, after=null) | 0-based position of first element matching x in self, or null if not found; optionally begins the search after the given position |
| .insert(index, value) | inserts value into self at the given index (in place) |
| .join(delimiter=“ „) | builds a string by joining elements by the given delimiter |
| .len | length (number of elements) of self |
| .pop | removes and returns the last element of self (like a stack) |
| .pull | removes and returns the first element of self (like a queue) |
| .push(x) | appends the given value to the end of self; often used with pop or pull |
| .shuffle | randomly rearranges the elements of self (in place) |
| .sort(key=null) | sorts list in place, optionally by value of the given key (e.g. in a list of maps) |
| .sum | total of all numeric elements of self |
| .remove(i) | removes element at index i from self (in place) |
| .replace(oldval, newval, maxCount=null) | replaces (in place) up to maxCount occurrences of oldval in the list with newval (if maxCount not specified, then all occurrences are replaced) |
| slice(list, from, to) | equivalent to list[from:to] |
Map Functions
Functions on maps are very similar to functions on lists. Maps (like lists) are mutable; the push, pop, remove, and shuffle methods modify the map in place. You can treat a map like a set using push, which inserts 1 (true) for the value of the given key, and pop, which returns a key and removes it (and its value) from the map. Keep in mind that the order of keys in a map is undefined.
In the following table, self is a map, i is an integer, and x is any value.
| .hasIndex(x) | 1 if x is a key contained in self; 0 otherwise |
| .indexes | list containing all keys of self, in arbitrary order |
| .indexOf(x, after=null) | first key in self that maps to x, or null if none; optionally begins the search after the given key |
| .len | length (number of key-value pairs) of self |
| .pop | remove and return an arbitrary key from self |
| .push(x) | equivalent to self[x] = 1 |
| .remove(x) | removes the key-value pair where key=x from self (in place) |
| .replace(oldval, newval, maxCount=null) | replaces (in place) up to maxCount occurrences of value oldval in the map with newval (if maxCount not specified, then all occurrences are replaced) |
| .shuffle | randomly remaps values for keys |
| .sum | total of all numeric values in self |
| .values | list containing all values of self, in arbitrary order |
System Functions
The following functions relate to the operation of MiniScript itself, or interact with the host environment. The latter (print, time, and wait) are only quasi-standard, in that support for them depends on the host application, and so they may not function in some environments.
| globals | reference to the global variable map |
| locals | reference to the local variable map for the current call frame |
| print(x) | convert x to a string and print to some text output stream |
| time | number of seconds since program execution began |
| wait(x=1) | wait x seconds before proceeding with the next MiniScript instruction |
| yield | wait for next invocation of main engine loop (e.g., next frame in a game) |
