diff --git a/doc/en/scripting.md b/doc/en/scripting.md index a21b959ed..17e7f7a7a 100644 --- a/doc/en/scripting.md +++ b/doc/en/scripting.md @@ -42,6 +42,7 @@ Subsections: - [utf8](scripting/builtins/libutf8.md) - [vec2, vec3, vec4](scripting/builtins/libvecn.md) - [world](scripting/builtins/libworld.md) +- [Extensions for standard libraries](scripting/extensions.md) - [Module core:bit_converter](scripting/modules/core_bit_converter.md) - [Module core:data_buffer](scripting/modules/core_data_buffer.md) - [Module core:vector2, core:vector3](scripting/modules/core_vector2_vector3.md) diff --git a/doc/en/scripting/extensions.md b/doc/en/scripting/extensions.md new file mode 100644 index 000000000..94a55ef00 --- /dev/null +++ b/doc/en/scripting/extensions.md @@ -0,0 +1,204 @@ +# Standard Library Extensions + +The **stdmin.lua** kernel script defines functions that extend and complement some of the standard **Lua** libraries. + +## Contents: +- [table extensions](#table-extensions) +- [string extensions](#string-extensions) +- [math extensions](#math-extensions) +- [bit extensions](#bit-extensions) +- [additional global functions](#additional-global-functions) + +## Table Extensions +```lua +-- Creates and returns a copy of the given table by creating a new one and copying all elements from the given table into it. +table.copy(t: table) -> table + +-- The deep copy function creates a full copy of the source table, including all its subtables. +table.deep_copy(t: table) -> table + +-- Returns the number of pairs in the given table. +table.count_pairs(t: table) -> int + +-- Returns one element from the given table at a random position. +table.random(t: table) -> any + +-- Returns true if x is contained in t. +table.has(t: table, x: any) -> boolean + +-- Returns the index of x in t. If the given object is not contained in the table, the function returns -1. +table.index(t: table, x: any) -> int + +-- Removes element x from t. +table.remove_value(t: table, x: any) + +-- Shuffles values ​​in the table. +table.shuffle(t: table) -> table + +-- Adds values ​​from table t2 to table t1. If table t2 contains a key from t1, the key's value will not be changed. +table.merge(t1: table, t2: table) -> table + +-- Iterates through the table and applies a func to all its elements, returning the new value of the element. +table.map(t: table, func: function(indx, value)) -> table + +-- Iterates through the table using a func that returns true if the element should be kept and false if it should be deleted. +table.filter(t: table, func: function(indx, value)) -> table + +-- Allows you to safely retrieve the value for the specified key. If the key exists in the table, the method will return its value. +-- If the key is missing, the method will set it to the default value and return it. +table.set_default(t: table, key: int | string, default: any) -> any + +-- Returns a "flattened" version of the original table. +table.flat(t: table) -> table + +-- Returns a deep "flat" version of the original table. +table.deep_flat(t: table) -> table + +-- Returns a truncated version of the table from index start to index stop, inclusive. Key-value pairs +-- are not preserved in the new table. For nil values, the value starts at 1 and ends at #arr, respectively. +table.sub(arr: table, start: number | nil, stop: number | nil) -> table + +-- Adds a value to the table only if it was not originally there. +table.insert_unique(t: table, val: any) +table.insert_unique(t: table, pos: int, val: any) + +-- Returns a table containing all keys of the given table, including numeric ones. table.keys(t: table) -> table + +-- Adds all key-value pairs from table extension to table t. If a key from t is present in extension, its value will be overwritten. +table.extend(t: table, extension: table) -> table + +-- Converts the passed table to a string. +table.tostring(t: table) -> string +``` + +## String extensions + +It's important to note that all of the functions listed below that extend **string** can be used as meta-methods on string instances, i.e.: + +```lua +local str = "ABA str BAB" + +if str:starts_with("ABA") and str:ends_with("BAB") then +print(str:replace("BA", "DC")) +end +``` + +```lua +-- Splits the string into parts based on the specified separator/expression and returns the result as a table of strings. If withpattern is true, the separator parameter will be evaluated as a regular expression. string.explode(separator: string, str: string, withpattern: boolean) -> table + +-- Splits the string into parts based on the specified delimiter and returns the result as a table of strings. +string.split(str: string, delimiter: string) -> table + +-- Escapes special characters in the string, such as `()[]+-.$%^?*`, into `%character` format. The `NUL` character (`\0`) will be converted to `%z`. +string.pattern_safe(str: string) -> string + +-- Splits seconds into hours, minutes, and milliseconds and formats them using the following parameter order: `minutes, seconds, milliseconds`, and then returns the result. If format is not specified, it returns a table where: +-- h - hours, +-- m - minutes, +-- s - seconds, +-- ms - milliseconds. +string.formatted_time(seconds: number, format: string) -> string | table + +-- Replaces all substrings in str equal to tofind with toreplace and returns a string with all the modified substrings. +string.replace(str: string, tofind: string, toreplace: string) -> string + +-- Removes all characters equal to char from the string from the left and right ends and returns the result. +-- If the char parameter is undefined, all empty characters will be selected. +string.trim(str: string, char: string) -> string + +-- Removes all characters equal to char from the string from the left end and returns the result. +-- If the char parameter is undefined, all empty characters will be selected. +string.trim_left(str: string, char: string) -> string + +-- Removes all characters equal to char from the right end of the string and returns the result. +-- If the char parameter is undefined, all empty characters will be selected. +string.trim_right(str: string, char: string) -> string + +-- Returns true if the string begins with the substring start. +string.starts_with(str: string, start: string) -> boolean + +-- Returns true if the string ends with the substring endStr. +string.ends_with(str: string, endStr: string) -> boolean + +-- The string.lower and string.upper functions are also overridden by utf8.lower and utf8.upper. + +-- Escapes a string. It is an alias for utf8.escape. +string.escape(str: string) -> string + +-- Escapes special XML characters. An alias for utf8.escape_xml. +string.escape_xml(text: string) -> string + +-- Adds a char to the left and right of the string until its size equals size. +-- By default, char is equal to the space character. +string.pad(str: string, size: int, char: string) -> string + +-- Adds a char to the left of the string until its size equals size. +-- By default, char is equal to the space character. +string.left_pad(str: string, size: int, char: string) -> string + +-- Adds a char to the right of the string until its size equals size. +-- By default, char is equal to the space character. +string.right_pad(str: string, size: int, char: string) -> string +``` + +## Math extensions + +```lua +-- Returns _in if it is in the range low <= _in <= high +-- Otherwise, returns the boundary to which _in is closest. +math.clamp(_in: number, low: number, high: number) -> number + +-- Returns a random fractional number in the range low to high. +math.rand(low: number, high: number) -> number + +-- Returns the normalized value of num relative to conf. +math.normalize(num: number, [optional] conf: number) -> number + +-- Returns the rounded value of num to the specified number of decimal places. +math.round(num: number, [optional] places: number) -> number + +-- Returns the sum of all received arguments. If a table was passed as an argument, the method will return the sum of all its elements. +math.sum(x: number, ... | t: table) -> number + +``` + +## Bit extensions +```lua + +-- Common arguments: +-- * expr: A string containing a bitwise expression, conforming to the Lua 5.3 bitwise operations format +-- * args: A list of names of the expression arguments. If nil, the list is automatically generated based on the detected identifiers. + +- Compiles the function to perform bitwise operations +-- * asFunction: If true, returns the function; otherwise, returns a string of function code +bit.compile(expr: string, args: table | nil, asFunction: boolean=true) -> function | string + +-- Compiles the function to perform bitwise operations and executes it in place +-- * ...: Values ​​to be passed to the compiled function. bit.execute(expr: string, args: table | nil, ...) -> number +``` +## Additional Global Functions + +This script also defines other global functions that are available for use. Their list is below. + +```lua +-- Returns true if the passed table is an array, that is, if each key is an integer greater than or equal to one +-- and if each key follows the previous one. +is_array(x: table) -> boolean + +-- Splits the path into two parts and returns them: the entry point and the file path. +parse_path(path: string) -> string, string + +-- Calls the function func iters times, passing it the arguments ..., and then prints to the console the time in microseconds that has elapsed +-- since the call to timeit. timeit(iters: int, func: function, ...) + +-- Causes the coroutine to pause until the number of seconds specified in timesec has elapsed. +-- The function can only be used inside a coroutine. +sleep(timesec: number) + +-- Waits for the passed coroutine to complete, returning the control flow. The function can only be used inside a coroutine. +-- Returns values ​​similar to those returned by pcall. +await(co: coroutine) -> result, error + +-- A constant storing the PID of the current engine instance. +os.pid -> number +``` diff --git a/doc/ru/scripting/extensions.md b/doc/ru/scripting/extensions.md index 922d02404..54a19f723 100644 --- a/doc/ru/scripting/extensions.md +++ b/doc/ru/scripting/extensions.md @@ -7,7 +7,7 @@ - [расширения для string](#расширения-для-string) - [расширения для math](#расширения-для-math) - [расширения для bit](#расширения-для-bit) -- [Дополнительные глобальные функции](#дополнительные-глобальные-функции) +- [дополнительные глобальные функции](#дополнительные-глобальные-функции) ## Расширения для table ```lua