Module

Function Signatures

This document describes the available built-in functions, organized by category (core logic, type conversion, collections, strings, parsing, encoding, validation, generation, and more). Each function includes its signature, behavior, and parameters to help you use it correctly in modules and expressions.

Core Functions

Provide basic logic building blocks.

alltrue

alltrue(bool_list list of bool) bool

Returns true if all values in the input list are true. Returns true for an empty list. Returns false if any value is false or null. Returns unknown if any value is unknown.

Parameters

bool_list (list of bool): List of boolean values. The function checks if all are true.

anytrue

anytrue(bool_list list of bool) bool

Returns true if at least one value in the input list is true. Returns false if the list is empty or contains only false or null. Returns unknown if some values are unknown and none are true.

Parameters

bool_list (list of bool): List of boolean values. The function checks if any are true.

can

can(expression dynamic) bool

Evaluates the given expression and returns a boolean value indicating whether the expression produced a result without any errors.

Parameters

expression (dynamic):

coalesce

coalesce(...values dynamic) dynamic

Returns the first non-empty, non-null value from the input list. Handles dynamic, unknown, and null values. Returns an error if all values are empty or null.

Variadic Parameter

values (dynamic): Variadic input values. Returns the first that is not null or empty.

len

len(value dynamic) number

Returns the length of a string, list, map, set, tuple, or object. For strings, returns the number of characters. For collections and structures, returns the number of elements. Returns unknown if type is dynamic or value is unknown.

Parameters

value (dynamic): Input value to measure. Can be a string, list, map, set, tuple, or object.

try

try(...expressions dynamic) dynamic

Evaluates all of its argument expressions in turn and returns the result of the first one that does not produce any errors.

Variadic Parameter

expressions (dynamic):

Type Conversion

Convert values between types.

tobool

tobool(value dynamic) bool

Converts a value to type bool. Supports dynamic and marked types. Gives clear error messages if conversion fails.

Parameters

value (dynamic): The value to convert. Can be dynamic, marked, or null.

tolist

tolist(value dynamic) list of dynamic

Converts a value to type list of dynamic. Supports dynamic and marked types. Gives clear error messages if conversion fails.

Parameters

value (dynamic): The value to convert. Can be dynamic, marked, or null.

tomap

tomap(value dynamic) map of dynamic

Converts a value to type map of dynamic. Supports dynamic and marked types. Gives clear error messages if conversion fails.

Parameters

value (dynamic): The value to convert. Can be dynamic, marked, or null.

tonumber

tonumber(value dynamic) number

Converts a value to type number. Supports dynamic and marked types. Gives clear error messages if conversion fails.

Parameters

value (dynamic): The value to convert. Can be dynamic, marked, or null.

toset

toset(value dynamic) set of dynamic

Converts a value to type set of dynamic. Supports dynamic and marked types. Gives clear error messages if conversion fails.

Parameters

value (dynamic): The value to convert. Can be dynamic, marked, or null.

tostring

tostring(value dynamic) string

Converts a value to type string. Supports dynamic and marked types. Gives clear error messages if conversion fails.

Parameters

value (dynamic): The value to convert. Can be dynamic, marked, or null.

Collection Operations

Create and change lists, sets, maps, and objects.

at

at(list dynamic, index number) dynamic

Returns the element with the given index from the given list or tuple, applying the modulo operation to the given index if it's greater than the number of elements.

Parameters

list (dynamic):
index (number):

cartesian

cartesian(...sets dynamic) dynamic

Calculates the cartesian product of two or more sets.

Variadic Parameter

sets (dynamic): The sets to consider. Also accepts lists and tuples, and if all arguments are of list or tuple type then the result will preserve the input ordering

chunk

chunk(list list of dynamic, size number) list of list of dynamic

Splits a single list into multiple lists where each has at most the given number of elements.

Parameters

list (list of dynamic): The list to split into chunks.
size (number): The maximum length of each chunk. All but the last element of the result is guaranteed to be of exactly this size.

compact

compact(list list of string) list of string

Removes all empty string elements from the given list of strings.

Parameters

list (list of string):

concat

concat(...seqs dynamic) dynamic

Concatenates together all of the given lists or tuples into a single sequence, preserving the input order.

Variadic Parameter

seqs (dynamic):

contains

contains(list dynamic, value dynamic) dynamic

Returns true if the given value is a value in the given list, tuple, or set, or false otherwise.

Parameters

list (dynamic):
value (dynamic):

difference

difference(a set of dynamic, b set of dynamic) set of dynamic

Returns the relative complement of the two given sets.

Parameters

a (set of dynamic):
b (set of dynamic):

distinct

distinct(list list of dynamic) list of dynamic

Removes any duplicate values from the given list, preserving the order of remaining elements.

Parameters

list (list of dynamic):

flatten

flatten(list dynamic) dynamic

Transforms a list, set, or tuple value into a tuple by replacing any given elements that are themselves sequences with a flattened tuple of all of the nested elements concatenated together.

Parameters

list (dynamic):

indexof

indexof(collection dynamic, target dynamic) dynamic

Returns the index of the first time a value appears in a list or tuple. If the value is not found, an error is returned. The function works safely with dynamic or unknown types.

Parameters

collection (dynamic): The list or tuple to search. This must be a collection (like ["a", "b", "c"]).
target (dynamic): The value to look for in the collection. The type must match the type of items in the list or tuple.

intersect

intersect(first_set set of dynamic, ...other_sets set of dynamic) set of dynamic

Returns the intersection of all given sets.

Parameters

first_set (set of dynamic):

Variadic Parameter

other_sets (set of dynamic):

issubset

issubset(set_a set of dynamic, set_b set of dynamic) bool

Returns true if all elements in set_a are also present in set_b. Returns false if any element in set_a is missing.

Parameters

set_a (set of dynamic): The set of values to check. Each item must exist in set_b to return true.
set_b (set of dynamic): The set to check against. Must contain all values from set_a to return true.

keys

keys(inputMap dynamic) dynamic

Returns a list of the keys of the given map in lexicographical order.

Parameters

inputMap (dynamic): The map to extract keys from. May instead be an object-typed value, in which case the result is a tuple of the object attributes.

lookup

lookup(collection dynamic, key string, ...default_value dynamic) dynamic

Gets the value for a given key in a map or object. If the key is not found, an optional default value can be returned instead. Works safely with dynamic, unknown, or null values.

Parameters

collection (dynamic): The map or object to search in. Must be a valid map or object value (for example, { "name": "alice" }).
key (string): The key to look up in the collection. This must be a string matching one of the keys in the map or object.

Variadic Parameter

default_value (dynamic): An optional value to return if the key is not found. If this is not provided and the key is missing, the function returns an error. The type of this value should match the values in the map.

matchkeys

matchkeys(values list of dynamic, keys list of dynamic, searchset list of dynamic) list of dynamic

Returns a filtered list from values, based on matches between keys and the searchset. For each item in keys that appears in searchset, the corresponding value (at the same index) is included in the result.

This function is useful for filtering lists based on a list of lookup keys. It handles dynamic types and unknown values safely.

Parameters

values (list of dynamic): The list of values to filter. A value is included in the result only if its index matches a key that appears in searchset.
keys (list of dynamic): A list of keys to check. Each key is compared to the searchset. If a key matches, the value at the same index from values is included.
searchset (list of dynamic): The list of keys to match against. Each item in keys is checked to see if it exists in this list.

merge

merge(...maps dynamic) object

Merges all of the elements from the given maps into a single map, or the attributes from given objects into a single object.

Variadic Parameter

maps (dynamic):

one

one(collection dynamic) dynamic

Returns the first item in a list, set, or tuple. Returns null if the collection is empty. If there are multiple items, it returns the first.

Parameters

collection (dynamic): A list, set, or tuple. The function returns the first item, or null if the collection is empty.

reverse

reverse(list dynamic) dynamic

Returns the given list with its elements in reverse order.

Parameters

list (dynamic):

slice

slice(list dynamic, start_index number, end_index number) dynamic

Extracts a subslice of the given list or tuple value.

Parameters

list (dynamic):
start_index (number):
end_index (number):

sort

sort(list list of string) list of string

Applies a lexicographic sort to the elements of the given list.

Parameters

list (list of string):

transpose

transpose(input_map map of list of string) map of list of string

Swaps keys and values in a map of lists of strings. Each string in the lists becomes a key, with a list of original keys as its value. The result is a new map with sorted lists.

Parameters

input_map (map of list of string): A map where each key maps to a list of strings. The function reverses this structure to group keys by shared values.

union

union(first_set set of dynamic, ...other_sets set of dynamic) set of dynamic

Returns the union of all given sets.

Parameters

first_set (set of dynamic):

Variadic Parameter

other_sets (set of dynamic):

values

values(mapping dynamic) dynamic

Returns the values of elements of a given map, or the values of attributes of a given object, in lexicographic order by key or attribute name.

Parameters

mapping (dynamic):

zipmap

zipmap(keys list of string, values dynamic) dynamic

Constructs a map from a list of keys and a corresponding list of values, which must both be of the same length.

Parameters

keys (list of string):
values (dynamic):

String Manipulation

Change and inspect text strings.

chomp

chomp(str string) string

Removes one or more newline characters from the end of the given string.

Parameters

str (string):

containsstr

containsstr(inputString string, substring string) bool

Check if a string contains a specific substring. The check is case-sensitive and returns true if found.

Parameters

inputString (string): The string to search in.
substring (string): The string to search for. The match must be exact and case-sensitive.

endswith

endswith(inputString string, suffix string) bool

Check if a string ends with a given suffix. Returns true for an exact case-sensitive match, false otherwise.

Parameters

inputString (string): The string to check. This is the main string being evaluated.
suffix (string): The expected ending of the input string. Must be an exact match (case-sensitive).

fmtcase

fmtcase(input string, format string, ...options object) string

Formats the input string to the requested case format.

The input may be in any style (snake_case, kebab-case, camelCase, PascalCase, dot.case, spaced words, SCREAMING_SNAKE, or a mixed form). It will be tokenized and normalized before being converted to the target format.

Supported formats (case-insensitive; examples in parentheses):

snake (snake_case)
kebab (kebab-case)
camel (camelCase)
pascal (PascalCase)
dot (dot.case)

Options object (all optional):

digits_mode: "split" | "separate" | "attach" (default: "split") Controls token boundaries at letter↔digit transitions.
acronyms: list(string) (default: none) Known initialisms for tokenization (e.g., ["ID","URL","HTTP"]).
preserve_acronyms: bool (default: false) If true, keeps acronyms uppercase in output.
ascii_only: bool (default: false) If true, drops non-ASCII runes (lossy).
trim: bool (default: true) Trim leading/trailing Unicode whitespace.

Parameters

input (string): The string to convert.
format (string): The target format (snake, kebab, camel, pascal, or dot).

Variadic Parameter

options (object): Optional options object controlling tokenization and output (see above).

format

format(format string, ...args dynamic) string

Constructs a string by applying formatting verbs to a series of arguments, using a similar syntax to the C function "printf".

Parameters

format (string):

Variadic Parameter

args (dynamic):

formatlist

formatlist(format string, ...args dynamic) list of string

Constructs a list of strings by applying formatting verbs to a series of arguments, using a similar syntax to the C function "printf".

Parameters

format (string):

Variadic Parameter

args (dynamic):

indent

indent(spaces number, str string) string

Adds a given number of spaces after each newline character in the given string.

Parameters

spaces (number): Number of spaces to add after each newline character.
str (string): The string to transform.

join

join(separator string, ...lists list of string) string

Concatenates together the elements of all given lists with a delimiter, producing a single string.

Parameters

separator (string): Delimiter to insert between the given strings.

Variadic Parameter

lists (list of string): One or more lists of strings to join.

lower

lower(str string) string

Returns the given string with all Unicode letters translated to their lowercase equivalents.

Parameters

str (string):

replace

replace(inputString string, searchString string, replacement string) string

Replace all matches of a substring or pattern in a string. If the search string is wrapped in slashes (/pattern/), it is treated as a regular expression.

Parameters

inputString (string): The original string where replacements will be made.
searchString (string): The text to replace. If wrapped in /, it's treated as a regex pattern.
replacement (string): The string that will replace each match of the search string or pattern.

reversestr

reversestr(str string) string

Returns the given string with all of its Unicode characters in reverse order.

Parameters

str (string):

split

split(separator string, str string) list of string

Produces a list of one or more strings by splitting the given string at all instances of a given separator substring.

Parameters

separator (string): The substring that delimits the result strings.
str (string): The string to split.

startswith

startswith(inputString string, prefix string) bool

Check if a string starts with a given prefix. Returns true if it does, false if not. Tries to infer result if the string is unknown but the prefix is known.

Parameters

inputString (string): The string to check. Can be a known or unknown value.
prefix (string): The prefix to check for. Must be a known string.

stripansi

stripansi(inputString string) string

Remove ANSI escape codes (e.g., color/style codes) from a string. Returns clean text.

Parameters

inputString (string): The string that may contain ANSI codes for formatting (like colors).

substr

substr(str string, offset number, length number) string

Extracts a substring from the given string.

Parameters

str (string): The input string.
offset (number): The starting offset in Unicode characters.
length (number): The maximum length of the result in Unicode characters.

title

title(str string) string

Replaces one letter after each non-letter and non-digit character with its uppercase equivalent.

Parameters

str (string):

trim

trim(str string, cutset string) string

Removes consecutive sequences of characters in "cutset" from the start and end of the given string.

Parameters

str (string): The string to trim.
cutset (string): A string containing all of the characters to trim. Each character is taken separately, so the order of characters is insignificant.

trimprefix

trimprefix(str string, prefix string) string

Removes the given prefix from the start of the given string, if present.

Parameters

str (string): The string to trim.
prefix (string): The prefix to remove, if present.

trimspace

trimspace(str string) string

Removes any consecutive space characters (as defined by Unicode) from the start and end of the given string.

Parameters

str (string):

trimsuffix

trimsuffix(str string, suffix string) string

Removes the given suffix from the start of the given string, if present.

Parameters

str (string): The string to trim.
suffix (string): The suffix to remove, if present.

upper

upper(str string) string

Returns the given string with all Unicode letters translated to their uppercase equivalents.

Parameters

str (string):

Data Parsing

Read structured text and return fields or objects.

parsebytes

parsebytes(byteSizeString string) number

Convert a string with a size unit (e.g., '1.5KB') into a number in bytes.

Parameters

byteSizeString (string): A string with a byte size and unit (e.g., '2MB', '3.5GB'). Supports decimal values and valid units.

parsefields

parsefields(inputString string) list of string

Split a string by whitespace. Return a list of non-whitespace substrings.

Parameters

inputString (string): The string to split. It will be split at any space, tab, or newline.

parseint

parseint(integerString dynamic, base number) dynamic

Convert a string to an integer using a specific base. Supports bases 2 to 62.

Parameters

integerString (dynamic): The string to convert. Must be a valid integer in the given base.
base (number): The base to use (e.g., 10 for decimal, 16 for hex). Must be between 2 and 62.

parselines

parselines(multilineString string) list of string

Split a multiline string into a list. Remove blank lines. Trim spaces from each line.

Parameters

multilineString (string): A string with multiple lines. Lines are separated by newline characters.

parseregex

parseregex(pattern string, string string) dynamic

Applies the given regular expression pattern to the given string and returns information about a single match, or raises an error if there is no match.

Parameters

pattern (string):
string (string):

parseregexall

parseregexall(pattern string, string string) list of dynamic

Applies the given regular expression pattern to the given string and returns a list of information about all non-overlapping matches, or an empty list if there are no matches.

Parameters

pattern (string):
string (string):

parsesiprefix

parsesiprefix(siString string) number

Convert a string with an SI prefix into a number. For example, '2.5M' becomes 2500000.

Parameters

siString (string): A string with a number and an SI prefix (e.g., '1.5k', '2M'). Must follow standard SI format.

parseurl

parseurl(urlString string) object

Parse a URL string and return its parts: scheme, hostname, port, path, fragment, query, username, and password.

Parameters

urlString (string): The URL to parse. Must follow standard URL format (e.g., 'https://user:pass@host:1234/path?x=1#frag').

parseuseragent

parseuseragent(userAgentString string) object

Analyzes a user-agent string and extracts structured information about the client, including the browser name and version, operating system name and version, platform, device type, and whether the client is a bot.

Parameters

userAgentString (string): A string representing the user-agent to be parsed. This string typically comes from the User-Agent HTTP header in client requests.

Encoding & Decoding

Convert data to and from encodings such as JSON, YAML, XML, CSV, and Base64.

decode

decode(input string, source string) string

Decodes the input string from the specified encoding.

The input must be a valid encoded string for the given source encoding.

Supported encodings (case-insensitive):

base64 : Standard Base64 decoding.
base64_gzip : Decodes from Base64, then decompresses using gzip.

Parameters

input (string): The encoded string to decode.
source (string): The source encoding (base64 or base64_gzip).

encode

encode(input string, target string) string

Encodes the input string using the specified encoding.

The input is taken as a raw string (UTF-8) and converted according to the target encoding.

Supported encodings (case-insensitive):

base64 : Standard Base64 encoding.
base64_gzip : Compresses the string with gzip, then encodes the result in Base64.

Parameters

input (string): The input string to encode.
target (string): The encoding to apply (base64 or base64_gzip).

fromcsv

fromcsv(str string) dynamic

Parses the given string as Comma Separated Values (as defined by RFC 4180) and returns a map of objects representing the table of data, using the first row as a header row to define the object attributes.

Parameters

str (string):

fromhcl

fromhcl(hcl_string string) dynamic

Convert an HCL string into a dynamic structured value. Returns error if syntax is invalid or cannot evaluate.

Parameters

hcl_string (string): Input HCL string to decode.

fromjson

fromjson(str string) dynamic

Parses the given string as JSON and returns a value corresponding to what the JSON document describes.

Parameters

str (string):

fromxml

fromxml(xml_string string) dynamic

Convert an XML string into a dynamic structured value. Returns error if input is invalid or cannot be converted.

Parameters

xml_string (string): Input XML string to decode.

fromyaml

fromyaml(src string) dynamic

Parameters

src (string):

tocsv

tocsv(records list of list of string) string

Encodes a list of lists of strings into a single CSV-formatted string. Each inner list represents a row in the CSV, and each string represents a cell value.

Parameters

records (list of list of string): A list of lists of strings where each inner list represents a row and each string represents a cell value.

tohcl

tohcl(value dynamic) dynamic

Encodes a given value into its HCL (HashiCorp Configuration Language) representation as a string. Supports dynamic types and ensures the output is valid HCL syntax.

Parameters

value (dynamic): The value to be encoded into HCL format. The input can be of any type that is supported by HCL syntax.

tojson

tojson(val dynamic) string

Returns a string containing a JSON representation of the given value.

Parameters

val (dynamic):

tourl

tourl(input_string string) string

Encodes a string by applying URL encoding, ensuring all special characters are escaped appropriately for inclusion in URLs.

Parameters

input_string (string): The string to be URL-encoded. All special characters will be replaced with their corresponding percent-encoded values.

toxml

toxml(value dynamic) dynamic

Encodes a given value into its XML representation as a string. Supports dynamic types and ensures proper conversion to XML format. Returns an error if the value cannot be serialized to XML.

Parameters

value (dynamic): The value to be encoded into XML format. The input can be of any type that can be serialized to XML.

toyaml

toyaml(value dynamic) string

Parameters

value (dynamic):

Extraction & Scanning

Find and return matching data inside text.

scan

scan(input dynamic, datatype string) dynamic

Scans the input for the specified datatype and returns a set of unique matches.

Supported datatypes (case-insensitive):

aws_access_keys, aws_account_ids, aws_s3_urls
base64, basic_auth_tokens, bearer_tokens, braintree_access_tokens, credit_cards
domains, dsa_private_keys, emails, facebook_access_tokens
filepaths, files, github_access_tokens
google_api_keys, google_captcha_keys, google_oauth_keys
html_comments, ipv4_addresses, ipv6_addresses, javascript_comments
jwt_tokens, mac_addresses, mailgun_api_keys, md5_hashes
rsa_private_keys, sha1_hashes, sha256_hashes, sha512_hashes
square_access_tokens, square_oauth_secrets, stripe_api_tokens
timestamps, twilio_api_keys, twilio_sids, uuid_v4

Parameters

input (dynamic): Any value; strings will be collected recursively from within (lists, sets, tuples, maps, and objects).
datatype (string): The pattern category to scan for (see list above). Case-insensitive, snake_case.

Data Validation

Check that data matches a known format.

is

is(input string, datatype string) bool

Validates whether the input string matches a specific datatype/format.

Supported datatypes (case-insensitive):

alpha_numeric, alpha, ascii, base64
cidr, crc32, crc32b, credit_card, data_uri, dial_string, dns_name
email, existing_email, file_path, hash, hexadecimal, hex_color, host
imei, imsi, ipv4, ipv6, ip, isbn10, isbn13
iso693_alpha2, iso693_alpha3, iso3166_alpha2, iso3166_alpha3
json, latitude, longitude, mac, magnet_uri
md4, md5, mongo_id, multibyte, port, printable_ascii, regex
request_uri, request_url, rfc3339, rfc3339_without_zone
rgb_color, ripemd128, ripemd160, semver
sha1, sha256, sha384, sha512
sha3_224, sha3_256, sha3_384, sha3_512
ssn, tiger128, tiger160, tiger192, ulid
unix_file_path, url, uuid, uuidv3, uuidv4, uuidv5
windows_file_path, yaml

Parameters

input (string): The string to validate.
datatype (string): The validation to apply (snake_case). Examples: "alpha_numeric", "email", "ipv4", "uuid", "sha256", "url", "yaml".

Data Generation

Produce random or test data.

random

random(datatype string) bool

Generates a string for the given datatype/format.

Supported datatypes (case-insensitive):

ach_account, ach_routing
app_author, app_name, app_version
bitcoin_address, bitcoin_private_key
blurb, bs, buzz_word
chrome_user_agent, city, company, company_suffix
country, country_abbr, credit_card_cvv, credit_card_exp, credit_card_number, credit_card_type
currency_long, currency_short
domain_name, domain_suffix
email, firefox_user_agent, first_name, gender
hacker_verb, hacker_abbreviation, hacker_adjective, hacker_noun, hacker_phrase
hobby
http_method, http_version
ipv4_address, ipv6_address
job_descriptor, job_level, job_title
language, language_abbr, last_name
latitude, latitude_in_range, longitude, longitude_in_range
mac_address, middle_name, name, name_prefix, name_suffix
opera_user_agent, phone, phone_formatted, price
programming_lang, range, slogan, ssn
state, state_abbr, street, street_name, street_number, street_prefix, street_suffix
url, username, user_agent
uuid
zip

Parameters

datatype (string): The validation to apply (snake_case). Examples:

Hashing & Checksums

Compute digests for data and files.

hash

hash(input string, hash string) string

Computes a cryptographic hash of a string and returns the lowercase hexadecimal digest. Supported algorithms: md5, sha1, sha256, sha512.

Parameters

input (string): The input string to hash. The string is hashed as its UTF-8 bytes.
hash (string): The hash algorithm to use: one of "md5", "sha1", "sha256", or "sha512" (lowercase).

hashfile

hashfile(path string, hash string, ...dependsOn dynamic) string

Hash the contents of a file and encode the result. Supports tracking dependencies like shell commands or other files.

Parameters

path (string): Path to the file to hash.
hash (string): The hash algorithm to use: one of "md5", "sha1", "sha256", or "sha512" (lowercase).

Variadic Parameter

dependsOn (dynamic): Optional dependencies (e.g., command runs or other inputs) that affect the file.

Numerical Operations

Do math and statistics on numbers.

abs

abs(num number) number

If the given number is negative then returns its positive equivalent, or otherwise returns the given number unchanged.

Parameters

num (number):

ceil

ceil(num number) number

Returns the smallest whole number that is greater than or equal to the given value.

Parameters

num (number):

floor

floor(num number) number

Returns the greatest whole number that is less than or equal to the given value.

Parameters

num (number):

log

log(num number, base number) number

Returns the logarithm of the given number in the given base.

Parameters

num (number):
base (number):

max

max(...numbers number) number

Returns the numerically greatest of all of the given numbers.

Variadic Parameter

numbers (number):

mean

mean(numbers list of number) number

Return the average of a list of numbers. If the list is empty, the result is 0.

Parameters

numbers (list of number): List of numbers to average. Can be empty.

median

median(numbers list of number) number

Return the median value from a list of numbers. If the list is empty, an error is returned.

Parameters

numbers (list of number): List of numbers. Must not be empty.

min

min(...numbers number) number

Returns the numerically smallest of all of the given numbers.

Variadic Parameter

numbers (number):

pow

pow(num number, power number) number

Returns the given number raised to the given power (exponentiation).

Parameters

num (number):
power (number):

signum

signum(num number) number

Returns 0 if the given number is zero, 1 if the given number is positive, or -1 if the given number is negative.

Parameters

num (number):

sum

sum(collection dynamic) dynamic

Add all numbers in a list, set, or tuple. Returns an error if the input is empty or contains non-number values.

Parameters

collection (dynamic): A list, set, or tuple with only numbers. Must not be empty or contain null or non-number values.

Time & Dates

Format, compare, and add times and dates.

fmtreltime

fmtreltime(timestampA string, timestampB string, labelA string, labelB string) string

Create a human-readable string showing the time between two timestamps. Adds custom labels like 'ago' or 'from now'. Example: '5 minutes ago', 'in 3 hours'.

Parameters

timestampA (string): The first timestamp (ISO 8601 format, e.g., '2023-12-31T15:30:00Z').
timestampB (string): The second timestamp (ISO 8601 format).
labelA (string): Label for timestampA (e.g., 'ago'). Used when A is earlier.
labelB (string): Label for timestampB (e.g., 'from now'). Used when B is earlier.

fmttime

fmttime(timestamp string) string

Convert a timestamp to a human-readable time relative to now. Example: '5 minutes ago' or 'in 3 hours'.

Parameters

timestamp (string): The timestamp to convert (ISO 8601 format, e.g., '2023-12-31T15:30:00Z'). Compared against current time.

timeadd

timeadd(timestamp string, duration string) string

Adds the duration represented by the given duration string to the given RFC 3339 timestamp string, returning another RFC 3339 timestamp.

Parameters

timestamp (string):
duration (string):

timecompare

timecompare(timestampA string, timestampB string) number

Compare two timestamps in RFC 3339 format. Returns -1 if the first is earlier, 0 if equal, 1 if later.

Parameters

timestampA (string): The first timestamp in RFC 3339 format.
timestampB (string): The second timestamp in RFC 3339 format.

timeformat

timeformat(format string, time string) string

Formats a timestamp given in RFC 3339 syntax into another timestamp in some other machine-oriented time syntax, as described in the format string.

Parameters

format (string):
time (string):

timestamp

timestamp() string

Get the current date and time as a string in RFC 3339 format.

Formatting Helpers

Present values in a clear, human-readable form.

fmtbytes

fmtbytes(bytes number) string

Convert a number of bytes into a readable string. For example, 1024 becomes '1.0 kB'.

Parameters

bytes (number): The size in bytes. Must be a non-negative number.

fmtcomma

fmtcomma(number number, decimal number) string

Format a number with commas as thousand separators and round it to a specific number of decimal places.

Parameters

number (number): The number to format. Can be a whole number or a decimal.
decimal (number): How many digits to show after the decimal point. Must be a non-negative whole number.

fmtordinal

fmtordinal(number number) string

Convert a number to its ordinal form. Example: 1 → '1st', 2 → '2nd', 103 → '103rd'.

Parameters

number (number): The number to convert. Should be a whole number, like 1, 2, 103.

fmtplural

fmtplural(quantity number, singular string, plural string) string

Combine a number and a word, and return the correct singular or plural form. If no plural form is given, basic English rules are used. Example: (2, 'apple', '') → '2 apples'.

Parameters

quantity (number): The number of items. Must be a whole number.
singular (string): The singular word (e.g., 'apple'). Used when quantity is 1.
plural (string): The plural word (e.g., 'apples'). If empty, a default rule adds 's' to the singular.

fmtpluralword

fmtpluralword(quantity number, singular string, plural string) string

Return the correct word form (singular or plural) based on quantity. If no plural is given, simple English rules are used. Example: 2 + 'apple' → 'apples'.

Parameters

quantity (number): The number used to choose singular or plural. Use 1 for singular, any other number for plural.
singular (string): The word in singular form (e.g., 'apple'). Used when quantity is 1.
plural (string): The word in plural form (e.g., 'apples'). If empty, the function adds 's' to the singular by default.

fmtsi

fmtsi(value number, unit string) string

Format a number using the best-fitting SI prefix (like k, M, G) and add the given unit. For example, 1500 with unit 'm' becomes '1.5 km'.

Parameters

value (number): The numeric value to format. It will be scaled to match an SI prefix like k (kilo), M (mega), etc.
unit (string): The base unit to use in the output, such as 'm' for meters or 'g' for grams.

fmtwordseries

fmtwordseries(words list of string, conjunction string, useOxfordComma bool) string

Format a list of words into a sentence-style series with a conjunction. Optionally include the Oxford comma. Example: ['apple', 'banana', 'cherry'] + 'and' + true → 'apple, banana, and cherry'.

Parameters

words (list of string): List of words to join. Each word will be separated by commas and the conjunction.
conjunction (string): The word to use before the last item (e.g., 'and', 'or').
useOxfordComma (bool): True to include a comma before the last conjunction (Oxford comma), false to skip it.

Networking & CIDR

Work with IP addresses and CIDR blocks.

cidrhost

cidrhost(cidrPrefix string, hostNumber number) string

Get the IP address of a host at a given index in a CIDR block. For example, ('192.168.1.0/24', 5) → '192.168.1.5'.

Parameters

cidrPrefix (string): The CIDR block as a string (e.g., '192.168.1.0/24').
hostNumber (number): The index of the host in the CIDR block. Must be a whole number within the valid range.

cidrnetmask

cidrnetmask(cidrPrefix string) string

Get the subnet mask for an IPv4 CIDR block. Example: '192.168.1.0/24' → '255.255.255.0'. IPv6 is not supported.

Parameters

cidrPrefix (string): CIDR block as a string (e.g., '192.168.1.0/24'). Must be an IPv4 address.

cidrsubnet

cidrsubnet(cidrPrefix string, newBits number, subnetIndex number) string

Create a subnet address by extending a CIDR prefix with more bits. For example, adding 8 bits to '192.168.0.0/16' gives a /24 subnet like '192.168.10.0/24'.

Parameters

cidrPrefix (string): The base network in CIDR format (e.g., '192.168.0.0/16').
newBits (number): How many bits to add to the network prefix. This sets the subnet size.
subnetIndex (number): The index of the subnet to return. Must be a valid number in the new range.

cidrsubnets

cidrsubnets(prefix string, ...newbits number) list of string

Create multiple subnets from a base CIDR block. Each subnet adds more bits to the prefix.

Parameters

prefix (string): Base network in CIDR format (e.g., '10.0.0.0/16').

Variadic Parameter

newbits (number): Number of bits to add to the base prefix for each new subnet.

Filesystem & Templates

Read files, expand paths, and render templates.

fsabspath

fsabspath(path string) string

Converts a given filesystem path string to an absolute path. If the input path is already absolute, it is returned as-is. Otherwise, the path is resolved relative to the current working directory, ensuring a complete absolute path.

Parameters

path (string): The input string representing a filesystem path. This can be either a relative path (resolved using the current working directory) or an absolute path.

fsbasename

fsbasename(path string) string

Extracts the base name (last portion) from a given filesystem path string. For example, for a path '/foo/bar/file.txt', it returns 'file.txt'.

Parameters

path (string): The input string representing a filesystem path. It can be either an absolute or relative path.

fsdirname

fsdirname(path string) string

Extracts the directory portion of a given filesystem path string by removing the last segment (usually the file or last directory name). For example, given '/foo/bar/file.txt', it returns '/foo/bar'. This is helpful for obtaining the parent directory path.

Parameters

path (string): The input string representing a filesystem path. It can be either an absolute or relative path.

fsfileexists

fsfileexists(path string, ...depends_on dynamic) bool

Checks if a file exists at a given path. Returns true if the file exists and is a regular file, otherwise returns false or an error for invalid paths or unsupported file types.

Parameters

path (string): The relative or absolute path of the file to check. Paths using ~ for home directory expansion are supported.

Variadic Parameter

depends_on (dynamic): Optional references to dependencies such as commands, runs, or sleep times that might affect file availability.

fsglob

fsglob(pattern string, ...depends_on dynamic) set of string

Enumerates a set of files matching a given glob pattern..

Parameters

pattern (string): The glob pattern to match files against. This pattern is relative to the specified base path.

Variadic Parameter

depends_on (dynamic): Optional references to dependencies such as exec, runs, or sleep times that might affect file availbilty.

fspathexpand

fspathexpand(path string) string

Expands a given filesystem path string by replacing a leading '~' character with the current user's home directory. This ensures that paths referencing the user's home directory are correctly resolved to their absolute equivalents.

Parameters

path (string): The input string representing a filesystem path. If the path begins with '~', it will be expanded to the current user's home directory. Paths without a leading '~' are returned unchanged.

fsread

fsread(path string, ...depends_on dynamic) string

Reads the contents of a file specified by a path and returns the content either as a UTF-8 string or as a base64-encoded string if specified. Handles dependencies for advanced use cases.

Parameters

path (string): The relative file path within the base directory from which content will be read.

Variadic Parameter

depends_on (dynamic): Optional references to dependencies, such as commands, runs, modules, or sleep times, which can influence the file readiness.

templatefile

templatefile(path string, vars dynamic) dynamic

Renders a specified file as a template using redteamer template syntax. The function accepts a file path and a set of named variables to use within the template. The function ensures that dependencies are well-defined and prevents recursive calls to avoid infinite loops.

Parameters

path (string): The relative file path to the template within the base directory.
vars (dynamic): A map of variables to be used in rendering the template. Variables must be valid identifiers.

CLI Helpers

Build command-line arguments, options, and flags.

cliargs

cliargs(...value dynamic) list of string

Generates a list of CLI arguments from the given values.

Accepts primitive types (string, number, boolean), as well as lists, sets, or tuples of them
All values are converted to strings
Ignores nulls and empty strings

Useful for flattening structured data into a flat CLI argument list.

Variadic Parameter

value (dynamic): A value or collection of values:
Can be a string, number, boolean, list, set, or tuple
Each value is converted to a string
Ignores nulls and empty strings

clicsv

clicsv(name string, values list of dynamic, ...format string) list of string

Create a CLI option and one CSV value from a collection.

Accept list, set, or tuple
Convert each element to string with a format (default "%v")
Ignore null and empty-string elements
If no output value, return an empty list

Parameters

name (string): Option name. One character uses '-' prefix. Otherwise uses '--'.
values (list of dynamic): Collection of values (list, set, or tuple). Can be null.

Variadic Parameter

format (string): Optional element format. Same as str::format pattern. Default '%v'.

clicsvf

clicsvf(option string, values list of dynamic, ...format string) list of string

Create a CLI option with a CSV value using a custom option format.

Accept list, set, or tuple
Convert each element to string with a format (default "%v")
Ignore null and empty-string elements
If option ends with a space, output value as a separate argument
If no output value, return an empty list

Parameters

option (string): Option prefix (e.g., '--option=', '-I ', '/option'). Trailing space makes value a separate argument.
values (list of dynamic): Collection of values (list, set, or tuple). Can be null.

Variadic Parameter

format (string): Optional element format. Same as str::format pattern. Default '%v'.

cliflag

cliflag(name string, ...value dynamic) list of string

Generates a list of command-line interface (CLI) flags based on a given flag name and values. Single-character flags are prefixed with a single dash (-), while multi-character flags use a double dash (--).

true values add the flag to the output.
Numeric values repeat the flag the specified number of times.
false, null, and empty values are ignored.

Example Usage:

cliflag("v", true) → [-v]
cliflag("verbose", true, false, true) → [--verbose --verbose]
cliflag("debug", false) → [] (ignored because the value is false)
cliflag("f", true, true, false) → [-ff] (single-character flags are combined when true values appear consecutively)
cliflag("f", 3) → [-fff] (numeric values repeat the flag)

Parameters

name (string): The name of the CLI flag. Single-character names (e.g., 'v') will be prefixed with -, while longer names (e.g., 'verbose') will be prefixed with --.

Variadic Parameter

value (dynamic): Boolean or numeric values:
true: Adds the flag to the output.
false: Ignored.
A number: Adds the flag multiple times equal to the given number.
null and empty values are ignored.

cliflagf

cliflagf(flag string, ...value dynamic) list of string

Generates a list of CLI flags using a user-defined flag format.

Adds the flag for each 'true' value
Repeats the flag for numeric values (e.g., 3 → add it 3 times)
Ignores false, null, and empty values

Supports any flag format (e.g., '-v', '--verbose', '/debug').

Example Usage:

cliflagf("-v", true) → [-v]
cliflagf("--verbose", true, false, true) → [--verbose --verbose]
cliflagf("/debug", false, true) → [/debug]
cliflagf("-f", 3) → [-f -f -f]
cliflagf("--retry", 2, false, 1) → [--retry --retry --retry]
cliflagf("-x", null, "", true) → [-x]

Parameters

flag (string): The full CLI flag (e.g., '-v', '--verbose', '/debug'). It is added to the output for each true or numeric value.

Variadic Parameter

value (dynamic): Values that determine how the flag is used:
true: add the flag once
number: repeat the flag N times
false, null, empty: ignored

cliflags

cliflags(...option_and_value tuple) list of string

Generates a single combined CLI shorthand flag(s) from flag-value pairs.

Only supports single-character flags (e.g., 'a', 'b', 'x')
Each input is a pair: [flag, boolean]
- true → includes the flag
- false, null → ignored
- If the flag is longer than 1 character → error

Example Usage:

cliflags(["a", true], ["b", false], ["c", true]) → [-ac]
cliflags(["x", true], ["y", true], ["z", true]) → [-xyz]
cliflags(["d", false], ["e", false]) → [] (no flags added)
cliflags(["long", true]) → Error: options must be one character but got: 4

Variadic Parameter

option_and_value (tuple): Each argument is a tuple [option, boolean]:
option: must be a 1-character string
boolean: if true, the flag is included
false, null, or longer strings are ignored or trigger errors

cliopt

cliopt(name string, ...value dynamic) list of string

Constructs a list of command-line interface (CLI) option arguments by formatting a given option flag with its associated values. The function supports:

Single-letter options prefixed with '-' (e.g., '-f' for 'f')
Multi-character options prefixed with '--' (e.g., '--file' for 'file')

Each provided value is paired with the option flag. Non-primitive values, null values, and empty strings are ignored.

Example Usage:

cliopt("f", "test.txt") → [-f test.txt]
cliopt("file", "config.json", "settings.yaml") → [--file config.json --file settings.yaml]
cliopt("v", true) → [-v true]
cliopt("verbose", 1, false, "debug") → [--verbose 1 --verbose false --verbose debug]
cliopt("log", null, "", "output.log") → [--log output.log] (ignores null and empty values)

Parameters

name (string): The name of the CLI option. If it's one character, it's prefixed with -. Otherwise, it's prefixed with --.

Variadic Parameter

value (dynamic): Values to assign to the option. Must be primitive (string, number, boolean). Null, empty strings, and non-primitive types are ignored.

clioptf

clioptf(option string, ...value dynamic) list of string

Constructs a list of command-line interface (CLI) option arguments using a customizable format. Supports different styles of flags:

'--option=value' (value is joined with '=')
'-option value' (value is separate from the flag)
'/optionValue' (value is directly appended)

If the option format ends with a space, values are added as separate arguments.

Example Usage:

clioptf("--config=", "settings.json") → [--config=settings.json]
clioptf("-o ", "output.txt") → [-o output.txt]
clioptf("/D", "DEBUG") → [/DDEBUG]
clioptf("--flag ", true, 42, "test") → [--flag true --flag 42 --flag test]
clioptf("/verbose=", "yes", "no") → [/verbose=yes /verbose=no]
clioptf("-t ", null, "", "value") → [-t value] (null and empty values are ignored)

Parameters

option (string): The option format string. Examples: '--option=', '-option ', '/option'. If it ends with a space, the value will be separate in the output.

Variadic Parameter

value (dynamic): The values to pair with the option. Must be primitive (string, number, boolean). Nulls, empty strings, and non-primitive types are ignored.

System & Environment

Read information from the host system and environment.

sysarch

sysarch() string

Get the system architecture (e.g., amd64, arm, 386).

syscpus

syscpus() number

Get the number of logical CPU cores available.

sysenv

sysenv(envKey string) string

Get the value of a specific environment variable. Returns an empty string if not set.

Parameters

envKey (string): The name of the environment variable to get.

sysenvs

sysenvs() map of string

Get all environment variables as a map of strings.

syshostname

syshostname() string

Get the system hostname from the operating system.

sysnics

sysnics() list of object

Retrieves a list of network interfaces available on the system. Each network interface is represented as an object containing its name, MTU (Maximum Transmission Unit), MAC address, and associated IP addresses.

sysos

sysos() string

Get the operating system name (e.g., linux, darwin, windows).