Functions

aux4 provides built-in functions that can be used in your execute instructions to format and transform variable values.

if

The if function allows you to execute instructions based on variable conditions. It uses the if() syntax followed by && for the true case and || for the false case.

Check if variable exists

Check if variable is empty

Use == with no value after it to check if a variable is empty.

Check if variable has specific value

Check if variable equals another variable

Check if variable is not equal

Use != to check inequality.

param

The param function formats a variable as a command-line parameter. If the variable has a value, it outputs --name 'value'. If the variable is undefined, it outputs nothing.

param with alias

You can specify an alias for the parameter name using param(variable:alias):

param with multiple values

For variables with multiple: true, use param(variable**) to output each value as a separate parameter:

params

The params function formats multiple variables as command-line parameters in a single call:

Only defined variables are included in the output.

value

The value function outputs just the value without the parameter name:

value with multiple values

For variables with multiple: true, use value(variable*) to get all values as a JSON array:

values

The values function outputs multiple values separated by spaces:

Unlike params, this outputs empty strings for undefined variables.

object

The object function creates a JSON object from the specified variables:

Only defined variables are included in the JSON object. Undefined variables are omitted.

Values are strings by default ("age":"20"). Give a variable a type — number, boolean or json — and object emits it typed ("age":20), so you rarely need a separate conversion step.

object with aliases

You can rename fields using variable:alias syntax, similar to param():

Without aliases, nested fields use underscores: response.name becomes response_name. With aliases, you control the key names.

object with dynamic fields

You can use a variable to specify which fields to include:

object with all parameters

Use * to include every current parameter. The parameters are spread directly into the object (each becomes its own field) — * is not a field name. You can combine it with named fields, e.g. object(id, *).

Note that * includes aux4's injected parameters too (such as aux4HomeDir and packageDir), so pick named fields instead when you only want specific values.

You can also give the wildcard an alias to nest all parameters under a single key (as a real object, not a string), and combine it with named fields:

nvl

The nvl function returns the first non-null, non-empty value from a list of candidates. It accepts any number of variable names and quoted literal strings as fallbacks.

It checks each candidate left to right:

1. response.avatar[0].path — if the path exists and is non-empty, use it
2. defaultAvatar — if this variable is set, use it
3. '/images/default.png' — literal fallback (quoted with single or double quotes)

path

The path function builds an absolute filesystem path from one or more segments, resolving it against the current working directory. It replaces the common case "${x}" in /*) ACFG='${x}';; *) ACFG="$PWD/${x}";; esac shell idiom.

Segments are separated by /:

• a bare word is resolved as a variable value
• .. and . are kept as literal path segments
• a quoted string (single or double quotes) is a literal segment

A relative result is made absolute against the current directory, an already-absolute value is returned unchanged, and an empty result stays empty.

Multiple segments are joined into a single path. Quote fixed folder names, and use .. to walk up:

arg

The arg function accesses positional arguments by index, without needing to define a variable with arg: true. Position 0 is the command name, 1 is the first argument, and so on. If the index is out of bounds, it returns an empty string.

You can use arg at any position and in any order:

args

The args function returns positional arguments as a JSON array. Use args(*) to get all arguments, or specify indices with args(0,1,2).

args with all arguments

args with specific indices

args with single index

Even with a single index, args always returns a JSON array:

exists

The exists function checks if a file exists at the path stored in a variable. It resolves to a shell test [ -f 'path' ], so it works with && and || for branching.

If default.png exists:

If it doesn't:

Note: Since exists() resolves to a shell test, use shell commands (echo, cp, etc.) in the &&/|| branches, not aux4 executors like log:.

date, time, datetime, utc and epoch

These functions return the current date and time. With no argument they produce ISO output; pass a format string to customize it.

datetime() is local time with no offset; use utc() when you need an unambiguous UTC timestamp (for logs, APIs, or cross-machine comparisons). A single call captures one timestamp, so date() and time() used in the same command stay consistent.

Custom formats

date(), time(), datetime() and utc() accept a format string built from moment-style tokens.

Doubled tokens are zero-padded, single tokens are not. Any character that isn't a token (like -, :, /, , or T) is emitted verbatim. To emit token letters literally, wrap them in square brackets — e.g. date(YYYY-MM-DD[T]HH:mm) keeps the T literal instead of formatting it.

epoch units

epoch() returns seconds by default. Pass a unit to change the resolution — epoch(ms) for milliseconds or epoch(ns) for nanoseconds.

data safety

date(), time(), datetime(), utc(), epoch() and uuid() are common names in SQL and other languages, so aux4 resolves them before variables are expanded. This means they only act on the text you write in the execute array — tokens that arrive at runtime inside a ${variable}, command output, or a file are left untouched, so data or SQL flowing through a variable is safe. (Formats must be literal too: date(${fmt}) does not expand the variable, since resolution happens first.)

To keep a call you author yourself literal — for example a database's own uuid() or date(column) in an inline query — escape it with a backslash, as described in Escaping functions.

uuid

The uuid function generates a UUID. It defaults to version 7 (time-ordered, RFC 9562), which sorts chronologically and works well as a database key. Pass uuid(4) for a classic random version 4. A fresh value is generated for every occurrence, so uuid() uuid() yields two distinct identifiers. As with the date functions above, it resolves only in authored execute text (not in interpolated data), and a backslash keeps it literal (see Escaping functions).

Escaping functions

Any function call can be kept literal by prefixing it with a backslash. aux4 strips the backslash and emits the call verbatim instead of resolving it — useful when the text is meant for something else, such as a database's own uuid() or date(column) in an inline query.

This works for every function — \value(...), \values(...), \param(...), \params(...), \object(...), \nvl(...), \path(...), \if(...), \exists(...), \arg(...), \args(...), \date(...), \time(...), \datetime(...), \utc(...), \epoch(...) and \uuid().

Because a .aux4 file is JSON — and JSON also uses the backslash as an escape character — write two backslashes in the file (\\uuid()), which becomes \uuid() in the resolved command. Note that a quoted string does not protect a call: 'uuid()' still resolves (to an aux4 UUID inside the quotes); only the backslash does.

Working with Nested Data

All functions support nested data from JSON responses:

Given data.json:

For values with nested data:

---

See Also

• Variables
• Executors
• Config
• Commands
• Testing
• Package Manager
• Packaging
• Docker