Built-in Functions

len(value)

Return the length (in characters) of the rendered value.

<% echo len(123.45) %>

substr(text, start[, length])

Slice text at the given start (negative values count from the end) and optional length.

<% echo substr("polonio", -3) %>

lower(text)

Convert ASCII characters to lowercase.

<% echo lower("Hola") %>

upper(text)

Convert ASCII characters to uppercase.

<% echo upper("hola") %>

trim(text)

Strip whitespace on both ends.

<% echo trim("  hi 
") %>

replace(text, from, to)

Replace every occurrence of one substring with another.

<% echo replace("a-b-a", "-", "/") %>

split(text, sep)

Split into an array of segments using the separator.

<% var parts = split("a,b,c", ",") %>
<% echo parts[1] %>

contains(haystack, needle)

Return true if the substring exists.

<% echo contains("preview", "view") %>

starts_with(text, prefix)

Return true if text begins with prefix.

<% echo starts_with("docs/home", "docs/") %>

ends_with(text, suffix)

Return true if text ends with suffix.

<% echo ends_with("index.html", ".html") %>

html_escape(value)

Compatibility alias: htmlspecialchars(value). Both names have identical behavior.

Escape &, <, >, " and ' for HTML output.

<% echo html_escape("Rock & Roll") %>

count(arrayOrObject)

Return element (array) or key (object) count.

<% echo count([1,2,3]) %>

push(array, value)

Append and return the new length.

<% var todos = ["a"]; echo push(todos, "b") %>

pop(array)

Remove and return the last element (or null).

<% var todos = ["x","y"]; echo pop(todos) %>

shift(array)

Remove and return the first element.

<% var todos = ["x","y"]; echo shift(todos) %>

unshift(array, value)

Insert at the beginning and return the new length.

<% var todos = ["x"]; echo unshift(todos, "y") %>

concat(a, b)

Return a new array containing both inputs.

<% var both = concat([1,2],[3]); echo count(both) %>

join(array, sep)

Join elements into a string using the separator.

<% echo join(["a","b"], ":") %>

slice(array, start[, length])

Return a shallow slice from start with optional length.

<% echo count(slice([1,2,3,4], 1, 2)) %>

range(count)

Produce [0, 1, ..., count-1].

<% echo join(range(3), ",") %>

keys(object)

Return sorted keys.

<% echo join(keys({"b":1,"a":2}), ",") %>

values(object)

Return values sorted by key order.

<% echo join(values({"b":1,"a":2}), ",") %>

has_key(object, name)

Return true if a key exists.

<% echo has_key({"x":1}, "x") %>

get(object, name[, default])

Fetch a value or default (null).

<% echo get({"x":1}, "x", 0) %>

set(object, name, value)

Assign and return the stored value.

<% var obj = {}; echo set(obj, "lang", "es") %>

abs(n)

Absolute value.

<% echo abs(-3) %>

floor(n)

Round down.

<% echo floor(3.8) %>

ceil(n)

Round up.

<% echo ceil(3.1) %>

round(n)

Round to nearest integer.

<% echo round(3.6) %>

pow(base, exp)

Raise base to exponent.

<% echo pow(2, 5) %>

sqrt(n)

Square root (throws on negative input).

<% echo sqrt(9) %>

min(a, b)

Return the smaller number.

<% echo min(4, 7) %>

max(a, b)

Return the larger number.

<% echo max(4, 7) %>

rand()

Random floating-point value in [0, 1).

<% echo rand() > 0 %>

randint(min, max)

Random integer in inclusive range.

<% echo randint(1, 3) >= 1 %>

type(value)

Return the runtime type name.

<% echo type(123) %>

to_string(value)

Compatibility alias: tostring(value). Both names have identical behavior.

Serialize a value exactly as the output buffer would.

<% echo to_string([1,2]) %>

to_number(value)

Convert strings/bools/null to numbers.

<% echo to_number(" 42 ") %>

is_null(value)

Return true if the value is null.

<% echo is_null(null) %>

is_bool(value)

Return true for booleans.

<% echo is_bool(false) %>

is_number(value)

Return true for numeric values.

<% echo is_number(3.14) %>

is_string(value)

Return true for strings.

<% echo is_string("hi") %>

is_array(value)

Return true for arrays.

<% echo is_array([1]) %>

is_object(value)

Return true for objects.

<% echo is_object({}) %>

is_function(value)

Return true for user or builtin functions.

<% echo is_function(type) %>

now()

Return current UNIX timestamp.

<% echo now() > 0 %>

date_format(epoch, pattern)

Token-based formatter (YYYY, MM, DD, HH, mm, SS).

<% echo date_format(0, "YYYY-MM-DD") %>

date_parts(epoch)

Return an object with year/month/day/hour/minute/second.

<% var p = date_parts(0); echo p["year"] %>

date_add_days(epoch, days)

Add days (can be fractional) via 86,400-second units.

<% echo date_add_days(0, 1) %>

date_parse(text)

Parse YYYY-MM-DD or YYYY-MM-DD HH:MM:SS/T.

<% echo date_parse("2026-01-05") %>

print(...values)

Alias for echo.

<% print("hi") %>

println(...values)

Print followed by newline.

<% println("hi") %>

nl2br(text)

Convert newlines to <br>+ sequences.

<% echo nl2br("a
b") %>

debug(value)

Describe a value on stderr (does not affect HTML).

<% debug(_SERVER) %>

http_status(code)

Compatibility alias: status(code). Both names have identical behavior.

Set the outgoing HTTP status line (100–599).

<% http_status(302) %>

http_header(name, value)

Compatibility alias: header(name, value). Both names have identical behavior.

Add or overwrite headers.

<% http_header("X-Test", "ok") %>

http_content_type(value)

Set the Content-Type header.

<% http_content_type("text/plain") %>

redirect(target[, status])

Set Location header plus 3xx status (default 302).

<% redirect("/login") %>

urlencode(text)

Percent-encode query-string fragments.

<% echo urlencode("hola mundo") %>

urldecode(text)

Decode percent-encoded strings.

<% echo urldecode("hola+mundo") %>

file_read(path)

Read the contents of a file inside the storage root and return it as a string.

Arguments:

• path — relative path to a regular file

Returns: string containing the file contents.

Errors:

• storage root not configured
• absolute or escaping path
• file missing
• path refers to a directory

Example:

<%
var text = file_read("notes/welcome.txt")
echo text
%>

file_write(path, content)

Write the provided content to a file. The file is created or replaced atomically; parent directories must already exist.

Arguments:

• path — relative file path (parent directory must exist)
• content — value converted to a string before writing

Returns: null.

Errors:

• storage root not configured
• absolute or escaping path
• missing parent directory
• target is a directory

Example:

<%
dir_create("drafts")
file_write("drafts/post.txt", "Hello from Polonio!")
%>

file_append(path, content)

Append content to a file, creating the file when it does not exist. Parent directories must exist and the target cannot be a directory.

Arguments:

• path — relative file path
• content — value converted to a string before appending

Returns: null.

Errors:

• storage root not configured
• absolute or escaping path
• missing parent directory
• target is a directory

Example:

<%
dir_create("logs")
file_append("logs/app.log", "started\n")
%>

file_exists(path)

Test whether a regular file exists at the given relative path.

Arguments:

• path — relative file path

Returns: true if a regular file exists, otherwise false.

Errors:

• storage root not configured
• absolute or escaping path

Example:

<% echo file_exists("drafts/post.txt") %>

file_delete(path)

Delete a regular file if it exists under the storage root.

Arguments:

• path — relative file path

Returns: true if a file was deleted, false if nothing existed.

Errors:

• storage root not configured
• absolute or escaping path
• path refers to a directory

Example:

<%
if file_delete("drafts/post.txt")
  echo "Removed draft"
end
%>

file_size(path)

Return the size of a regular file in bytes.

Arguments:

• path — relative file path

Returns: number representing the byte length.

Errors:

• storage root not configured
• absolute or escaping path
• file missing
• path refers to a directory

Example:

<%
var size = file_size("drafts/post.txt")
echo "Size: " .. size .. " bytes"
%>

file_modified(path)

Return the last modification timestamp of a file as Unix epoch seconds.

Arguments:

• path — relative file path

Returns: number representing seconds since the Unix epoch.

Errors:

• storage root not configured
• absolute or escaping path
• file missing
• path refers to a directory

Example:

<%
var updated_at = file_modified("drafts/post.txt")
echo "Last updated: " .. updated_at
%>

dir_create(path)

Create the requested directory (and any intermediate directories) under the storage root.

Arguments:

• path — relative directory path

Returns: true whether the directory already existed or was just created.

Errors:

• storage root not configured
• absolute or escaping path
• path already exists as a file

Example:

<% dir_create("uploads/images") %>

dir_exists(path)

Check whether a directory exists.

Arguments:

• path — relative directory path

Returns: true if the path exists and is a directory; otherwise false.

Errors:

• storage root not configured
• absolute or escaping path

Example:

<%
if dir_exists("uploads")
  echo "Uploads ready"
end
%>

dir_list(path)

Return an array of entry names (files and directories) sorted ascending for the requested directory.

Arguments:

• path — relative directory path

Returns: array of strings (entry names).

Errors:

• storage root not configured
• absolute or escaping path
• path missing or not a directory

Example:

<%
var entries = dir_list("posts")
for name in entries
  echo "<li>" .. name .. "</li>"
end
%>

db_connect(path)

Open (or create) a SQLite database inside the storage sandbox.

Arguments:

• path — relative path to the database file (parent directory must exist)

Returns: null.

Errors:

• storage root not configured
• absolute or escaping path
• parent directory missing
• SQLite open failure

Example:

<%
dir_create("data")
db_connect("data/app.db")
%>

db_close()

Close the active database connection.

Arguments: none.

Returns: null.

Errors:

• database not connected

Example:

<% db_close() %>

db_query(sql[, params])

Execute a SELECT statement and return an array of objects (one per row). Column values map to strings, numbers, or null depending on SQLite types:

[
  {"id": 1, "name": "Ada"},
  {"id": 2, "name": "Grace"}
]

Arguments:

• sql — SQL string
• params (optional) — array of positional parameters bound to ?

Returns: array of row objects.

Errors:

• database not connected
• unsupported parameter type
• SQLite prepare/step error

Example:

<%
var users = db_query("select id, name from users where active = ?", [true])
for user in users
  echo user["name"]
end
%>

db_exec(sql[, params])

Execute INSERT/UPDATE/DELETE/DDL statements and return the number of rows affected (per sqlite3_changes()).

Arguments:

• sql — SQL string
• params (optional) — array of positional parameters

Returns: number of rows changed.

Errors: same as db_query.

Example:

<% db_exec("insert into users(name) values(?)", ["Ada"]) %>

db_last_insert_id()

Return the row id generated by the most recent insert on the connection.

Arguments: none.

Returns: number (row id).

Errors: database not connected.

Example:

<%
db_exec("insert into users(name) values(?)", ["Ada"])
var id = db_last_insert_id()
%>

db_begin()

Start a transaction. Only one transaction can be active at a time.

Arguments: none.

Returns: null.

Errors:

• database not connected
• transaction already active

Example:

<%
db_begin()
db_exec("insert into logs(message) values(?)", ["start"])
db_commit()
%>

db_commit()

Commit the active transaction.

Arguments: none.

Returns: null.

Errors:

• database not connected
• no active transaction
• SQLite commit failure

Example:

<%
db_begin()
db_exec("update counters set value = value + 1")
db_commit()
%>

db_rollback()

Roll back the active transaction.

Arguments: none.

Returns: null.

Errors:

• database not connected
• no active transaction
• SQLite rollback failure

Example:

<%
db_begin()
db_exec("delete from users where id = ?", [user_id])
db_rollback()
%>

Request

request_body()

Returns the raw request body string. Example: var raw = request_body().

request_header(name)

Accepts a string header name and returns its string value or null. Example: request_header("Content-Type").

request_headers()

Returns an object of request headers. Example: keys(request_headers()).

request_json()

Parses the raw body and returns the JSON value; invalid JSON raises an error. Example: var data = request_json().

cookies()

Returns the parsed cookie object. Example: cookies()["theme"].

Sessions

Require POLONIO_SESSION_SECRET; otherwise they raise an error. Data is stored in a signed cookie and persists only when the response can emit the updated cookie.

session_get(key[, default])

String key; returns the stored value, default, or null. Example: session_get("user_id").

session_set(key, value)

String key and any value; stores it and returns null. Example: session_set("flash", "Saved").

session_unset(key)

String key; removes it and returns null. Example: session_unset("flash").

session_clear()

Removes all session values and returns null. Example: session_clear().

Security

random_token(bytes)

Number of random bytes (1 through 1024); returns a URL-safe token. Invalid sizes raise an error. Example: random_token(32).

csrf_token()

Requires a session; returns the current session-backed token. Example: <input value="<% echo csrf_token() %>">.

csrf_verify(token)

Requires a session and a string token; returns bool. Example: if csrf_verify(_POST["csrf"]).

hash_password(password)

Accepts a string and returns a password hash. Example: var hash = hash_password("secret").

verify_password(password, hash)

Accepts strings and returns bool. Example: verify_password(input, hash).

Uploads, file responses, and mail

upload_save(file, path)

Accepts a `_FILES` file object and a relative storage path; moves the temporary upload and returns the saved path. Requires POLONIO_STORAGE_PATH. Example: upload_save(_FILES["photo"], "uploads/photo.bin").

send_file(path[, opts])

Accepts a relative sandboxed path and optional object with string content_type and/or download_name, finalizes the CGI/server response, and returns null. Missing/unsafe files raise errors. Example: send_file("reports/latest.txt").

send_mail(to, subject, body[, headers])

Accepts strings and optional header object; writes an .eml file to storage outbox and returns its path. Reserved/injected headers raise errors. It does not send SMTP mail. Example: send_mail("[email protected]", "Hi", "Body").

Compatibility aliases

http_status(code) has the compatibility alias status(code); http_header(name, value) has header(name, value). Both aliases have identical behavior, including response effects. http_content_type(value) sets a string content type. redirect(target[, status]) accepts a string target and optional 3xx-compatible number, sets Location/status, and returns null.

html_escape(value) has compatibility alias htmlspecialchars(value); to_string(value) has compatibility alias tostring(value). Both pairs have identical successful behavior.