Builtin functions

Check whether the given key exists within the given object value.

Returns true if the given key is present within the object passed as the first argument, otherwise false.

Terminate the interpreter with the given exit code.

This function does not return.

Filter the array passed as the first argument by invoking the function specified in the second argument for each array item.

If the invoked function returns a truthy result, the item is retained, otherwise, it is dropped. The filter function is invoked with three arguments:

1. The array value
2. The current index
3. The array being filtered

(Note that the map function behaves similarly to filter with respect to its fn parameters.)

Returns a new array containing only retained items, in the same order as the input array.

Interacts with the mark and sweep garbage collector of the running ucode virtual machine.

Depending on the given operation string argument, the meaning of argument and the function return value differs.

The following operations are defined:

• collect - Perform a complete garbage collection cycle, returns true.
• start - (Re-)start periodic garbage collection, argument is an optional integer in the range 1..65535 specifying the interval. Defaults to 1000 if omitted. Returns true if the periodic GC was previously stopped and is now started or if the interval changed. Returns false otherwise.
• stop - Stop periodic garbage collection. Returns true if the periodic GC was previously started and is now stopped, false otherwise.
• count - Count the amount of active complex object references in the VM context, returns the counted amount.

If the operation argument is omitted, the default is collect.

Query an environment variable or then entire environment.

Returns the value of the given environment variable, or - if omitted - a dictionary containing all environment variables.

Like localtime() but interpreting the given epoch value as UTC time.

See localtime() for details on the return value.

Converts the given hexadecimal string into a number.

Returns the resulting integer value or NaN if the input value cannot be interpreted as hexadecimal number.

Decodes the given hexadecimal digit string into a byte string, optionally skipping specified characters.

If the characters to skip are not specified, a default of " \t\n" is used.

Returns null if the input string contains invalid characters or an uneven amount of hex digits.

Returns the decoded byte string on success.

Encodes the given byte string into a hexadecimal digit string, converting the input value to a string if needed.

Evaluate and include the file at the given path and optionally override the execution scope with the given scope object.

By default, the file is executed within the same scope as the calling include(), but by passing an object as the second argument, it is possible to extend the scope available to the included file.

This is useful to supply additional properties as global variables to the included code. To sandbox included code, that is giving it only access to explicitly provided properties, the proto() function can be used to create a scope object with an empty prototype.

Finds the given value passed as the second argument within the array or string specified in the first argument.

Returns the first matching array index or first matching string offset or -1 if the value was not found.

Returns null if the first argument was neither an array nor a string.

Converts the given value to an integer, using an optional base.

Returns NaN if the value is not convertible.

Convert the given IP address string to an array of byte values.

IPv4 addresses result in arrays of 4 integers while IPv6 ones in arrays containing 16 integers. The resulting array can be turned back into IP address strings using the inverse arrtoip() function.

Returns an array containing the address byte values. Returns null if the given argument is not a string or an invalid IP.

Joins the array passed as the second argument into a string, using the separator passed in the first argument as glue.

Returns null if the second argument is not an array.

Parse the given string or resource as JSON and return the resulting value.

If the input argument is a plain string, it is directly parsed as JSON.

If an array, object or resource value is given, this function will attempt to invoke a read() method on it to read chunks of input text to incrementally parse as JSON data. Reading will stop if the object's read() method returns either null or an empty string.

Throws an exception on parse errors, trailing garbage, or premature EOF.

Returns the parsed JSON data.

Enumerates all object key names.

Returns an array of all key names present in the passed object. Returns null if the given argument is not an object.

Convert the given string to lowercase and return the resulting string.

Returns null if the given argument could not be converted to a string.

Determine the length of the given object, array or string.

Returns the length of the given value.

• For strings, the length is the amount of bytes within the string
• For arrays, the length is the amount of array elements
• For objects, the length is defined as the amount of keys

Returns null if the given argument is not an object, array or string.

Compiles the given file into a ucode program and returns the resulting program entry function.

See loadstring() for details.

Returns the compiled program entry function.

Throws an exception on compilation or file I/O errors.

Compiles the given code string into a ucode program and returns the resulting program entry function.

The optional options dictionary overrides parse and compile options.

• If a non-string code argument is given, it is implicitly converted to a string value first.
• If options is omitted or a non-object value, the compile options of the running ucode program are reused.

See ParseConfig for known keys within the options object. Unrecognized keys are ignored, unspecified options default to those of the running program.

Returns the compiled program entry function.

Throws an exception on compilation errors.

Return the given epoch timestamp (or now, if omitted) as a dictionary containing broken-down date and time information according to the local system timezone.

See TimeSpec for a description of the fields.

Note that in contrast to the underlying localtime(3) C library function, the values for mon, wday, and yday are 1-based, and the year is 1900-based.

Trim any of the specified characters from the start of the string. If the second argument is omitted, trims the characters (space), '\t', '\r', and '\n'.

Returns the left trimmed string.

Transform the array passed as the first argument by invoking the function specified in the second argument for each array item.

The mapping function is invoked with three arguments (see examples, below, for some possibly counterintuitive usage):

1. The array value
2. The current index
3. The array being filtered

(Note that the filter function behaves similarly to map with respect to its fn parameters.)

Returns a new array of the same length as the input array containing the transformed values.

Match the given string against the regular expression pattern specified as the second argument.

If the passed regular expression uses the g flag, the return value will be an array of arrays describing all found occurrences within the string.

Without the g modifier, an array describing the first match is returned.

Returns null if the pattern was not found within the given string.

Return the largest value among all parameters passed to the function.

Return the smallest value among all parameters passed to the function.

Without further arguments, this function returns the byte value of the first character in the given string.

If an offset argument is supplied, the byte value of the character at this position is returned. If an invalid index is supplied, the function will return null. Negative index entries are counted towards the end of the string, e.g. -2 will return the value of the second last character.

Returns the byte value of the character. Returns null if the offset is invalid or if the input is not a string.

Pops the last item from the given array and returns it.

Returns null if the array was empty or if a non-array argument was passed.

Print any of the given values to stdout.

The print() function writes a string representation of each given argument to stdout and returns the amount of bytes written.

String values are printed as-is, integer and double values are printed in decimal notation, boolean values are printed as true or false while arrays and objects are converted to their JSON representation before being written to the standard output. The null value is represented by an empty string so print(null) would print nothing. Resource values are printed in the form <type address>, e.g. <fs.file 0x7f60f0981760>.

If resource, array or object values contain a tostring() function in their prototypes, then this function is invoked to obtain an alternative string representation of the value.

Examples:

print(1 != 2);                       // Will print 'true'
print(0xff);                         // Will print '255'
print(2e3);                          // Will print '2000'
print(null);                         // Will print nothing
print({ hello: true, world: 123 });  // Will print '{ "hello": true, "world": 123 }'
print([1,2,3]);                      // Will print '[ 1, 2, 3 ]'

print(proto({ foo: "bar" },          // Will print 'MyObj'
  { tostring: () => "MyObj" }));     // instead of '{ "foo": "bar" }'

Returns the amount of bytes printed.

Formats the given arguments according to the given format string and outputs the result to stdout.

Ucode supports a restricted subset of the formats allowed by the underlying libc's printf() implementation, namely it allows the d, i, o, u, x, X, e, E, f, F, g, G, c and s conversions.

Additionally, an ucode specific J format is implemented, which causes the corresponding value to be formatted as JSON string. By prefixing the J format letter with a precision specifier, the resulting JSON output will be pretty printed. A precision of 0 will use tabs for indentation, any other positive precision will use that many spaces for indentation while a negative or omitted precision specifier will turn off pretty printing.

Other format specifiers such as n or z are not accepted and returned verbatim. Format specifiers including * directives are rejected as well.

Returns the number of bytes written to the standard output.

Get or set the prototype of the array or object value val.

When invoked without a second argument, the function returns the current prototype of the value in val or null if there is no prototype or if the given value is neither an object nor an array.

When invoked with a second prototype argument, the given proto value is set as the prototype on the array or object in val.

Throws an exception if the given prototype value is not an object.

Pushes the given argument(s) to the given array.

Returns the last pushed value.

Construct a regular expression instance from the given source pattern string and any flags optionally specified by the flags argument.

• Throws a type error exception if flags is not a string or if the string in flags contains unrecognized regular expression flag characters.
• Throws a syntax error when the pattern in source cannot be compiled into a valid regular expression.

Returns the compiled regular expression value.

When invoked with a string value as the first argument, the function acts like include() but captures the output of the included file as a string and returns the captured contents.

The second argument is treated as the scope.

When invoked with a function value as the first argument, render() calls the given function and passes all subsequent arguments to it.

Any output produced by the called function is captured and returned as a string. The return value of the called function is discarded.

Replace occurrences of the specified pattern in the string passed as the first argument.

• The pattern value may be either a regular expression or a plain string.
• The replace value may be a function which is invoked for each found pattern or any other value which is converted into a plain string and used as replacement.
• When an optional limit is specified, substitutions are performed only that many times.
• If the pattern is a regular expression and not using the g flag, then only the first occurrence in the string is replaced.
• If the g flag is used or if the pattern is not a regular expression, all occurrences are replaced.
• If the replace value is a callback function, it is invoked with the found substring as the first and any capture group values as subsequent parameters.
• If the replace value is a string, specific substrings are substituted before it is inserted into the result.

Returns a new string with the pattern replaced.

Load and evaluate ucode scripts or shared library extensions.

The require() function expands each member of the global REQUIRE_SEARCH_PATH array to a filesystem path by replacing the * placeholder with a slash-separated version of the given dotted module name and subsequently tries to load a file at the resulting location.

If a file is found at one of the search path locations, it is compiled and evaluated or loaded via the C runtime's dlopen() function, depending on whether the found file is a ucode script or a compiled dynamic library.

The resulting program function of the compiled/loaded module is then subsequently executed with the current global environment, without a this context and without arguments.

Finally, the return value of the invoked program function is returned back by require() to the caller.

By default, modules are cached in the global modules dictionary and subsequent attempts to require the same module will return the cached module dictionary entry without re-evaluating the module.

To force reloading a module, the corresponding entry from the global modules dictionary can be deleted.

To preload a module or to provide a "virtual" module without a corresponding filesystem resource, an entry can be manually added to the global modules dictionary.

Summarized, the require() function can be roughly described by the following code:

function require(name) {
    if (exists(modules, name))
        return modules[name];

    for (const item in REQUIRE_SEARCH_PATH) {
        const modpath = replace(item, '*', replace(name, '.', '/'));
        const entryfunc = loadfile(modpath, { raw_mode: true });

        if (entryfunc) {
            const modval = entryfunc();
            modules[name] = modval;

            return modval;
        }
    }

    die(`Module ${name} not found`);
}

Due to the fact that require() is a runtime operation, module source code is only lazily evaluated/loaded upon invoking the first require invocation, which might lead to situations where errors in module sources are only reported much later throughout the program execution. Unless runtime loading of modules is absolutely required, e.g. to conditionally load extensions, the compile time import syntax should be preferred.

Returns the module value (typically an object) on success.

Throws an exception if the module function threw an exception.

Throws an exception if no matching module could be found, if the module contains syntax errors or upon other I/O related problems.

Reverse the order of the given input array or string.

If an array is passed, returns the array in reverse order. If a string is passed, returns the string with the sequence of the characters reversed.

Returns the reversed array or string. Returns null if neither an array nor a string were passed.

Finds the given value passed as the second argument within the array or string specified in the first argument.

Returns the last matching array index or last matching string offset or -1 if the value was not found.

Returns null if the first argument was neither an array nor a string.

Trim any of the specified characters from the end of the string. If the second argument is omitted, trims the characters (space), '\t', '\r', and '\n'.

Returns the right trimmed string.

Pops the first item from the given array and returns it.

Returns null if the array was empty or if a non-array argument was passed.

Set or query process signal handler function.

When invoked with two arguments, a signal specification and a signal handler value, this function configures a new process signal handler.

When invoked with one argument, a signal specification, this function returns the currently configured handler for the given signal.

The signal specification might either be an integer signal number or a string value containing a signal name (with or without "SIG" prefix). Signal names are treated case-insensitively.

The signal handler might be either a callable function value or one of the two special string values "ignore" and "default". Passing "ignore" will mask the given process signal while "default" will restore the operating systems default behaviour for the given signal.

In case a callable handler function is provided, it is invoked at the earliest opportunity after receiving the corresponding signal from the operating system. The invoked function will receive a single argument, the number of the signal it is invoked for.

Note that within the ucode VM, process signals are not immediately delivered, instead the VM keeps track of received signals and delivers them to the ucode script environment at the next opportunity, usually before executing the next byte code instruction. This means that if a signal is received while performing a computationally expensive operation in C mode, such as a complex regexp match, the corresponding ucode signal handler will only be invoked after that operation concluded and control flow returns to the VM.

Returns the signal handler function or one of the special values "ignore" or "default" corresponding to the given signal specification.

Returns null if an invalid signal spec or signal handler was provided.

Returns null if changing the signal action failed, e.g. due to insufficient permission, or when attempting to ignore a non-ignorable signal.

Pause execution for the given amount of milliseconds.

Performs a shallow copy of a portion of the source array, as specified by the start and end offsets. The original array is not modified.

Returns a new array containing the copied elements, if any. Returns null if the given source argument is not an array value.

Sort the given array according to the given sort function. If no sort function is provided, a default ascending sort order is applied.

The input array is sorted in-place, no copy is made.

The custom sort function is repeatedly called until the entire array is sorted. It will receive two values as arguments and should return a value lower than, larger than or equal to zero depending on whether the first argument is smaller, larger or equal to the second argument respectively.

Returns the sorted input array.

Determine the path of the source file currently being executed by ucode.

Removes the elements designated by off and len from the given array, and replaces them with the additional arguments passed, if any.

The array grows or shrinks as necessary.

Returns the modified input array.

Split the given string using the separator passed as the second argument and return an array containing the resulting pieces.

If a limit argument is supplied, the resulting array contains no more than the given amount of entries, that means the string is split at most limit - 1 times total.

The separator may either be a plain string or a regular expression.

Returns a new array containing the resulting pieces.

Formats the given arguments according to the given format string.

See printf() for details.

Returns the formatted string.

Extracts a substring out of str and returns it. First character is at offset zero.

• If off is negative, starts that far back from the end of the string.
• If len is omitted, returns everything through the end of the string.
• If len is negative, leaves that many characters off the string end.

Returns the extracted substring.

Executes the given command, waits for completion, and returns the resulting exit code.

The command argument may be either a string, in which case it is passed to /bin/sh -c, or an array, which is directly converted into an execv() argument vector.

• If the program terminated normally, a positive integer holding the program's exit() code is returned.
• If the program was terminated by an uncaught signal, a negative signal number is returned.
• If the optional timeout argument is specified, the program is terminated by SIGKILL after that many milliseconds if it doesn't complete within the timeout.

Omitting the timeout argument or passing 0 disables the command timeout.

Returns the program exit code.

Returns the current UNIX epoch.

Like timelocal() but interpreting the given date time specification as UTC time.

See timelocal() for details.

Performs the inverse operation of localtime() by taking a broken-down date and time dictionary and transforming it into an epoch value according to the local system timezone.

The wday and yday fields of the given date time specification are ignored. Field values outside of their valid range are internally normalized, e.g. October 40th is interpreted as November 9th.

Returns the resulting epoch value or null if the input date time dictionary was invalid or if the date time specification cannot be represented as epoch value.

Enables or disables VM opcode tracing.

When invoked with a positive non-zero level, opcode tracing is enabled and debug information is printed to stderr as the program is executed.

Invoking trace() with zero as an argument turns off opcode tracing.

Trim any of the specified characters in c from the start and end of str. If the second argument is omitted, trims the characters, (space), \t, \r, and \n.

Returns the trimmed string.

Query the type of the given value.

Returns the type of the given value as a string which might be one of "function", "object", "array", "double", "int", or "bool".

Returns null when no value or null is passed.

Converts the given string to uppercase and returns the resulting string.

Returns null if the given argument could not be converted to a string.

Converts each given numeric value to an UTF-8 multibyte sequence and returns the resulting string.

Invalid numeric values or values outside the range 0..0x10FFFF are represented by the unicode replacement character 0xFFFD.

Returns a new UTF-8 encoded string consisting of unicode characters corresponding to the given numeric codepoints.

Returns a new array containing all unique values of the given input array.

• The order is preserved, and subsequent duplicate values are skipped.
• If a non-array argument is given, the function returns null.

Add the given values to the beginning of the array passed via first argument.

Returns the last value added to the array.

Returns an array containing all values of the given object.

Returns null if no object was passed.

Print any of the given values to stderr. Arrays and objects are converted to their JSON representation.

Returns the amount of bytes printed.

Match the given subject against the supplied wildcard (file glob) pattern.

• If a truthy value is supplied as the third argument, case-insensitive matching is performed.
• If a non-string value is supplied as the subject, it is converted into a string before being matched.

Returns true when the value matched the given pattern, otherwise false.

A parse configuration is a plain object describing options to use when compiling ucode at runtime. It is expected as parameter by the loadfile() and loadstring() functions.

All members of the parse configuration object are optional and will default to the state of the running ucode file if omitted.

A time spec is a plain object describing a point in time, it is returned by the gmtime() and localtime() functions and expected as parameter by the complementary timegm() and timelocal() functions.

When returned by gmtime() or localtime(), all members of the object will be initialized, when passed as argument to timegm() or timelocal(), most member values are optional.