{ "catalogVersion" : 1, "types" : [ { "name" : "Assert", "kind" : "library", "description" : "Checks conditions in a script and fails with a readable message when they do not hold.\n\nA failed check throws an error, which ends the script unless it is caught with `pcall` or the check runs inside `Retry.run`. Every check returns the value it checked, so it can be used inline (`local id = Assert.notNil(response.id)`). The optional last argument is a message that is put in front of the standard text: `my check: Expected 1 but was 2`.", "library" : "Assert", "category" : "utils", "variable" : "Assert", "functions" : [ { "name" : "that", "description" : "Fails with `Condition was not true` unless the value is truthy. In Lua only `false` and `nil` are falsy: `0` and the empty string pass.", "returns" : { "kind" : "any", "description" : "The checked value, returned unchanged so the call can be used inline" }, "overloads" : [ { "params" : [ { "kind" : "any", "description" : "Condition to check", "name" : "condition" } ] }, { "params" : [ { "kind" : "any", "description" : "Condition to check", "name" : "condition" }, { "kind" : "string", "description" : "Text put in front of the failure message", "name" : "message" } ] } ], "examples" : [ { "code" : "local value = Assert.that(1 + 1 == 2, \"math still works\")\nAssert.equals(4, 2 * 2)\nAssert.contains(\"hello world\", \"world\")", "runnable" : true } ] }, { "name" : "equals", "description" : "Fails with `Expected x but was y` unless both values are equal. Tables are compared by content, including nested tables, regardless of the order of their keys. Numbers are compared as numbers (`1` equals `1.0`) and a number equals text that reads as the same number (`1` equals `\"1\"`); a boolean never equals a number. Tables in the failure message are shown up to three levels deep.", "returns" : { "kind" : "any", "description" : "The actual value, returned unchanged so the call can be used inline" }, "overloads" : [ { "params" : [ { "kind" : "any", "description" : "The value you expect", "name" : "expected" }, { "kind" : "any", "description" : "The value you got", "name" : "actual" } ] }, { "params" : [ { "kind" : "any", "description" : "The value you expect", "name" : "expected" }, { "kind" : "any", "description" : "The value you got", "name" : "actual" }, { "kind" : "string", "description" : "Text put in front of the failure message", "name" : "message" } ] } ] }, { "name" : "notNil", "description" : "Fails with `Expected a non-nil value` when the value is `nil`. `false` passes.", "returns" : { "kind" : "any", "description" : "The checked value, returned unchanged so the call can be used inline" }, "overloads" : [ { "params" : [ { "kind" : "any", "description" : "Value to check", "name" : "value" } ] }, { "params" : [ { "kind" : "any", "description" : "Value to check", "name" : "value" }, { "kind" : "string", "description" : "Text put in front of the failure message", "name" : "message" } ] } ] }, { "name" : "isNil", "description" : "Fails with `Expected nil but was ...` unless the value is `nil`. `false` fails.", "returns" : { "kind" : "nil" }, "overloads" : [ { "params" : [ { "kind" : "any", "description" : "Value to check", "name" : "value" } ] }, { "params" : [ { "kind" : "any", "description" : "Value to check", "name" : "value" }, { "kind" : "string", "description" : "Text put in front of the failure message", "name" : "message" } ] } ] }, { "name" : "contains", "description" : "Fails unless the text contains the other text. Both values are converted to text first, so numbers work too; the comparison is case-sensitive. A `nil` haystack fails.", "returns" : { "kind" : "any", "description" : "The checked value, returned unchanged so the call can be used inline" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "Text that should contain `needle`", "name" : "haystack" }, { "kind" : "string", "description" : "Text it must contain", "name" : "needle" } ] }, { "params" : [ { "kind" : "string", "description" : "Text that should contain `needle`", "name" : "haystack" }, { "kind" : "string", "description" : "Text it must contain", "name" : "needle" }, { "kind" : "string", "description" : "Text put in front of the failure message", "name" : "message" } ] } ] } ] }, { "name" : "Codex", "kind" : "library", "description" : "Lets a script hand work to the OpenAI Codex CLI (`codex exec`): Codex.task runs one instruction, Codex.session keeps a conversation going over several messages. Use it to let an AI agent analyse, generate or change files in the project and then check the result in the script.\n\nThings to know: the CLI runs on the machine of the Reflex agent. It must be installed there, on the PATH of the agent process (or set REFLEX_CODEX_COMMAND), and already be signed in; Reflex passes no credentials. Check with Codex.available(). It runs non-interactively in the project workspace of the current run with the workspace-write sandbox and approvals disabled, so it can change files there without asking. Prompts and file contents are processed by an external AI service. Arguments are positional (use nil to skip one). A run is killed after 30 minutes unless you give a timeout. A CLI that fails or times out does not raise an error: check result.success (exit is -1 on a timeout). Errors are raised for a missing CLI, a bad argument or an invalid reasoning value.", "library" : "Codex", "category" : "ai", "variable" : "Codex", "functions" : [ { "name" : "available", "description" : "Returns true when the codex command can be found on the PATH of the agent process (or at the path in REFLEX_CODEX_COMMAND). Does not check that it is signed in.", "returns" : { "kind" : "boolean" }, "overloads" : [ { "params" : [ ] } ] }, { "name" : "version", "description" : "Returns the first line printed by `codex --version`. Raises an error when the CLI is missing or prints nothing within 10 seconds.", "returns" : { "kind" : "string" }, "overloads" : [ { "params" : [ ] } ] }, { "name" : "close", "description" : "Closes every Codex session of this script and stops Codex processes that are still running for it. The conversations stay in the CLI's own history; sessions that were closed cannot send again.", "returns" : { "kind" : "self" }, "overloads" : [ { "params" : [ ] } ] }, { "name" : "session", "description" : "Starts a Codex conversation: runs `codex exec --json` with the prompt, waits for it to finish and returns the session table. Later messages go to the same conversation through session.send (using `codex exec resume `), so Codex remembers the earlier messages and the files it already looked at. The returned table has the functions send, id and close and the fields sessionId, last (the result of the latest message, see AgentSessionResult) and closed. Raises an error when the CLI does not report a session id.", "returns" : { "kind" : "object", "ref" : "CodexSession" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "The instruction for the agent, a non-empty string", "name" : "prompt" }, { "kind" : "string", "description" : "Model name handed to the CLI; nil uses the CLI's configured default", "name" : "model", "optional" : true }, { "kind" : "string", "description" : "\"low\", \"medium\" or \"high\" (anything else is an error); nil uses the CLI default", "name" : "reasoning", "optional" : true }, { "kind" : "number", "description" : "Kill the CLI when it runs longer than this many seconds, must be above 0; default 1800 (30 minutes)", "name" : "timeoutSeconds", "optional" : true } ] } ] }, { "name" : "task", "description" : "Runs one instruction through `codex exec` and waits for it to finish. The result is a table, not text: success (exit code 0), exit, text (the final answer of Codex), all (the complete output including progress lines), and duration (milliseconds). Each task starts with a fresh context; use Codex.session for follow-up questions. With showReasoning true Codex also produces reasoning summaries and its progress output is printed to the script console while it runs.", "returns" : { "kind" : "shape", "ref" : "AgentTaskResult" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "The instruction for the agent, a non-empty string", "name" : "prompt" }, { "kind" : "string", "description" : "Model name handed to the CLI; nil uses the CLI's configured default", "name" : "model", "optional" : true }, { "kind" : "string", "description" : "\"low\", \"medium\" or \"high\" (anything else is an error); nil uses the CLI default", "name" : "reasoning", "optional" : true }, { "kind" : "number", "description" : "Kill the CLI when it runs longer than this many seconds, must be above 0; default 1800 (30 minutes)", "name" : "timeoutSeconds", "optional" : true }, { "kind" : "boolean", "description" : "Include the reasoning output in the console log", "name" : "showReasoning", "optional" : true } ] } ], "examples" : [ { "code" : "local result = Codex.task(\"Read scripts/login.lua and list any step that has no assertion. Reply as a bullet list.\")\nif not result.success then\n error(\"Codex failed (exit \" .. result.exit .. \"): \" .. result.all)\nend\nprint(result.text)", "description" : "Ask for a review and fail the script when Codex fails" }, { "code" : "-- model, reasoning effort and a 10 minute limit; nil keeps the CLI default for the model\nlocal result = Codex.task(\"Add a smoke test for the checkout page to tests/checkout.lua\", nil, \"high\", 600)\nprint(result.success, result.duration .. \" ms\")", "description" : "Let Codex write a file in the project, with a time limit" } ] } ] }, { "name" : "CodexSession", "kind" : "object", "description" : "A Codex conversation started by Codex.session. The first prompt has already been answered when you get it (see last); send continues the same thread, so Codex remembers earlier messages.", "library" : "Codex", "category" : "ai", "variable" : "chat", "howToGet" : [ { "type" : "Codex", "function" : "session", "call" : "Codex.session(prompt)", "returns" : "CodexSession" } ], "returnedBy" : [ { "type" : "Codex", "function" : "session" } ], "functions" : [ { "name" : "send", "description" : "Sends the next message of the conversation and waits for the answer. Returns the result table, which is also stored as session.last. Raises an error when the session is closed.", "returns" : { "kind" : "shape", "ref" : "AgentSessionResult" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "The next message in the conversation", "name" : "prompt" } ] } ], "examples" : [ { "code" : "local chat = Codex.session(\"Read tests/checkout.lua and remember its structure.\")\nlocal answer = chat.send(\"Which steps are missing assertions?\")\nprint(answer.text)\nchat.close()" } ] }, { "name" : "id", "description" : "Returns the Codex thread id of this conversation, the same value as the sessionId field.", "returns" : { "kind" : "string", "description" : "The session id, nil until the CLI has reported it", "nullable" : true }, "overloads" : [ { "params" : [ ] } ] }, { "name" : "close", "description" : "Closes this session and stops its Codex process if one is still running. Afterwards send raises an error.", "returns" : { "kind" : "self" }, "overloads" : [ { "params" : [ ] } ] } ] }, { "name" : "Concurrent", "kind" : "library", "description" : "Runs several Lua functions at the same time on worker threads and waits until all of them are done.\n\nThe functions share the global variables of the script and nothing is synchronised, so keep them independent and let each write to its own variable or table slot. Browser sessions and other library objects are not made thread-safe by this library.", "library" : "Concurrent", "category" : "concurrency", "variable" : "Concurrent", "functions" : [ { "name" : "run", "description" : "Starts a pool of `threads` worker threads, runs every function of the table on it and blocks until all have finished. Functions are called without arguments, their results are discarded, and entries of the table that are not functions are ignored. With fewer threads than functions the rest waits for a free thread.\n\nA function that fails does not stop the others and does not raise an error here: its error is collected instead. The call returns two values, a boolean that is true when nothing failed and a list with one text per failure. That text is the plain error message, such as `script.lua:3: message`, without Java class names. The order of the list is the order in which the failures happened.\n\nThrows when `threads` is not a whole number (`First parameter must be a integer`), when it is below 1, or when the second argument is not a table.", "returns" : { "kind" : "boolean", "description" : "Two values: true when no function failed, and a list of error texts (empty when none failed)" }, "overloads" : [ { "params" : [ { "kind" : "number", "description" : "Number of worker threads, a whole number of at least 1", "name" : "threads" }, { "kind" : "table", "description" : "List of Lua functions to run, like `{ fnA, fnB }`", "name" : "functions" } ] } ], "examples" : [ { "code" : "local ok, errors = Concurrent.run(2, {\n function() print(\"first\") end,\n function() print(\"second\") end,\n})\nprint(ok, #errors)", "runnable" : true } ] } ] }, { "name" : "Copilot", "kind" : "library", "description" : "Lets a script hand work to the GitHub Copilot CLI (`copilot -p`): Copilot.task runs one instruction, Copilot.session keeps a conversation going over several messages. Use it to let an AI agent analyse, generate or change files in the project and then check the result in the script.\n\nThings to know: the CLI runs on the machine of the Reflex agent. It must be installed there, on the PATH of the agent process (or set REFLEX_COPILOT_COMMAND), and already be signed in with a Copilot subscription; Reflex passes no credentials. Check with Copilot.available(). It runs non-interactively with --allow-all-tools and --no-ask-user, so it may run any shell command and change files without asking, and the project workspace of the current run is added as its working folder. Prompts and file contents are processed by an external AI service. Arguments are positional (use nil to skip one). A run is killed after 30 minutes unless you give a timeout. A CLI that fails or times out does not raise an error: check result.success (exit is -1 on a timeout). Errors are raised for a missing CLI, a bad argument or an invalid reasoning value.", "library" : "Copilot", "category" : "ai", "variable" : "Copilot", "functions" : [ { "name" : "available", "description" : "Returns true when the copilot command can be found on the PATH of the agent process (or at the path in REFLEX_COPILOT_COMMAND). Does not check that it is signed in.", "returns" : { "kind" : "boolean" }, "overloads" : [ { "params" : [ ] } ] }, { "name" : "version", "description" : "Returns the first line printed by `copilot --version`. Raises an error when the CLI is missing or prints nothing within 10 seconds.", "returns" : { "kind" : "string" }, "overloads" : [ { "params" : [ ] } ] }, { "name" : "close", "description" : "Closes every Copilot session of this script and stops Copilot processes that are still running for it. The conversations stay in the CLI's own history; sessions that were closed cannot send again.", "returns" : { "kind" : "self" }, "overloads" : [ { "params" : [ ] } ] }, { "name" : "session", "description" : "Starts a Copilot conversation: runs `copilot -p --output-format json`, waits for it to finish and returns the session table. Later messages go to the same conversation through session.send (using `--resume=`), so Copilot remembers earlier messages. The returned table has the functions send, id and close and the fields sessionId, last (the result of the latest message, see AgentSessionResult) and closed. Raises an error when the CLI does not report a session id.", "returns" : { "kind" : "object", "ref" : "CopilotSession" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "The instruction for the agent, a non-empty string", "name" : "prompt" }, { "kind" : "string", "description" : "Model name passed to the CLI as --model; nil uses the CLI's configured default", "name" : "model", "optional" : true }, { "kind" : "string", "description" : "\"low\", \"medium\" or \"high\" (anything else is an error); nil uses the CLI default", "name" : "reasoning", "optional" : true }, { "kind" : "number", "description" : "Kill the CLI when it runs longer than this many seconds, must be above 0; default 1800 (30 minutes)", "name" : "timeoutSeconds", "optional" : true } ] } ] }, { "name" : "task", "description" : "Runs one instruction through `copilot -p` and waits for it to finish. The result is a table, not text: success (exit code 0), exit, text (the last answer message of Copilot), all (the complete output: JSON event lines, or readable text with showReasoning), and duration (milliseconds). Each task starts with a fresh context; use Copilot.session for follow-up questions.", "returns" : { "kind" : "shape", "ref" : "AgentTaskResult" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "The instruction for the agent, a non-empty string", "name" : "prompt" }, { "kind" : "string", "description" : "Model name passed to the CLI as --model; nil uses the CLI's configured default", "name" : "model", "optional" : true }, { "kind" : "string", "description" : "\"low\", \"medium\" or \"high\" (anything else is an error); nil uses the CLI default", "name" : "reasoning", "optional" : true }, { "kind" : "number", "description" : "Kill the CLI when it runs longer than this many seconds, must be above 0; default 1800 (30 minutes)", "name" : "timeoutSeconds", "optional" : true }, { "kind" : "boolean", "description" : "true to print the agent's reasoning and answers to the script console while it works, and to make all a readable text instead of raw JSON events; default false", "name" : "showReasoning", "optional" : true } ] } ], "examples" : [ { "code" : "local result = Copilot.task(\"Read scripts/login.lua and list any step that has no assertion. Reply as a bullet list.\")\nif not result.success then\n error(\"Copilot failed (exit \" .. result.exit .. \"): \" .. result.all)\nend\nprint(result.text)", "description" : "Ask for a review and fail the script when Copilot fails" }, { "code" : "-- model, reasoning effort, 10 minute limit and live output in the console\nlocal result = Copilot.task(\"Add a smoke test for the checkout page to tests/checkout.lua\", nil, \"high\", 600, true)\nprint(result.success, result.duration .. \" ms\")", "description" : "Let Copilot write a file in the project, with a time limit" } ] } ] }, { "name" : "CopilotSession", "kind" : "object", "description" : "A Copilot conversation started by Copilot.session. The first prompt has already been answered when you get it (see last); send continues the same thread, so Copilot remembers earlier messages.", "library" : "Copilot", "category" : "ai", "variable" : "chat", "howToGet" : [ { "type" : "Copilot", "function" : "session", "call" : "Copilot.session(prompt)", "returns" : "CopilotSession" } ], "returnedBy" : [ { "type" : "Copilot", "function" : "session" } ], "functions" : [ { "name" : "send", "description" : "Sends the next message of the conversation and waits for the answer. Returns the result table, which is also stored as session.last. Raises an error when the session is closed.", "returns" : { "kind" : "shape", "ref" : "AgentSessionResult" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "The next message in the conversation", "name" : "prompt" } ] } ], "examples" : [ { "code" : "local chat = Copilot.session(\"Read tests/checkout.lua and remember its structure.\")\nlocal answer = chat.send(\"Which steps are missing assertions?\")\nprint(answer.text)\nchat.close()" } ] }, { "name" : "id", "description" : "Returns the Copilot session id of this conversation, the same value as the sessionId field.", "returns" : { "kind" : "string", "description" : "The session id, nil until the CLI has reported it", "nullable" : true }, "overloads" : [ { "params" : [ ] } ] }, { "name" : "close", "description" : "Closes this session and stops its Copilot process if one is still running. Afterwards send raises an error.", "returns" : { "kind" : "self" }, "overloads" : [ { "params" : [ ] } ] } ] }, { "name" : "Couch", "kind" : "library", "description" : "Talks to the CouchDB server that is configured in the project settings (URL, user name and password under Project settings > CouchDB in Reflex). The four functions map to the HTTP verbs, and every path is relative to that URL, so Couch.get(\"mydb/doc-1\") requests URL/mydb/doc-1.\n\nThings to know: every function returns a table with status, json and table. Non-2xx statuses such as 404 or 409 (revision conflict) are returned, not raised; only connection failures raise an error. When a user name or password is configured, every request carries Basic authentication (a missing user name or password counts as empty); there is no way to use other credentials from Lua. Updating or deleting a document needs its current revision (_rev in the body, or ?rev= for delete). A table passed as body is encoded as JSON.", "library" : "Couch", "category" : "databases", "variable" : "Couch", "functions" : [ { "name" : "get", "description" : "Sends a GET request to CouchDB: reads a document, a view, _all_docs, database info and so on. The second argument is optional and, when given, is sent as a JSON body (rarely needed for GET). Only the characters [ ] space and \" are escaped in the path, so URL-encode other special characters yourself.", "returns" : { "kind" : "shape", "ref" : "CouchResponse" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "Path and query string relative to the configured CouchDB URL, for example mydb/doc-1 or mydb/_all_docs?limit=10", "name" : "query" } ] }, { "params" : [ { "kind" : "string", "description" : "Path and query string relative to the configured CouchDB URL, for example mydb/doc-1 or mydb/_all_docs?limit=10", "name" : "query" }, { "kind" : "table", "description" : "Request body: a table that is sent as JSON (application/json)", "name" : "table" } ] } ], "examples" : [ { "code" : "local doc = Couch.get(\"mydb/order-1001\")\nAssert.equals(200, doc.status)\nprint(doc.table.customer, doc.table.total)\n\nlocal all = Couch.get(\"mydb/_all_docs?include_docs=true&limit=10\")\nfor _, row in ipairs(all.table.rows) do\n print(row.id)\nend", "description" : "Read a document and list documents" } ] }, { "name" : "put", "description" : "Sends a PUT request to CouchDB: creates a document under a chosen id, or updates it when the body contains the current _rev (otherwise CouchDB answers 409). Also used to create a database (Couch.put(\"newdb\")). On success the response table has the new revision as table.rev.", "returns" : { "kind" : "shape", "ref" : "CouchResponse" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "Path and query string relative to the configured CouchDB URL, for example mydb/doc-1 or mydb/_all_docs?limit=10", "name" : "query" } ] }, { "params" : [ { "kind" : "string", "description" : "Path and query string relative to the configured CouchDB URL, for example mydb/doc-1 or mydb/_all_docs?limit=10", "name" : "query" }, { "kind" : "table", "description" : "Request body: a table that is sent as JSON (application/json)", "name" : "table" } ] } ], "examples" : [ { "code" : "local created = Couch.put(\"mydb/order-1001\", { type = \"order\", customer = \"ACME\", total = 42.5 })\nAssert.equals(201, created.status)\n\nlocal current = Couch.get(\"mydb/order-1001\")\nlocal updated = Couch.put(\"mydb/order-1001\", {\n _rev = current.table._rev,\n type = \"order\",\n customer = \"ACME\",\n total = 45,\n})\nAssert.equals(201, updated.status)" } ] }, { "name" : "post", "description" : "Sends a POST request to CouchDB: creates a document with a generated id (POST to the database), or runs a query such as mydb/_find (Mango) or mydb/_bulk_docs. The body table is sent as JSON.", "returns" : { "kind" : "shape", "ref" : "CouchResponse" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "Path and query string relative to the configured CouchDB URL, for example mydb/doc-1 or mydb/_all_docs?limit=10", "name" : "query" } ] }, { "params" : [ { "kind" : "string", "description" : "Path and query string relative to the configured CouchDB URL, for example mydb/doc-1 or mydb/_all_docs?limit=10", "name" : "query" }, { "kind" : "table", "description" : "Request body: a table that is sent as JSON (application/json)", "name" : "table" } ] } ], "examples" : [ { "code" : "local found = Couch.post(\"mydb/_find\", { selector = { type = \"order\", total = { [\"$gt\"] = 40 } }, limit = 20 })\nAssert.equals(200, found.status)\nfor _, doc in ipairs(found.table.docs) do\n print(doc._id, doc.total)\nend" } ] }, { "name" : "delete", "description" : "Sends a DELETE request to CouchDB: deletes a document (the current revision is required as ?rev=REV in the path) or a whole database (Couch.delete(\"mydb\")). The status is 200, or 409 when the revision is outdated.", "returns" : { "kind" : "shape", "ref" : "CouchResponse" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "Path and query string relative to the configured CouchDB URL, for example mydb/doc-1 or mydb/_all_docs?limit=10", "name" : "query" } ] }, { "params" : [ { "kind" : "string", "description" : "Path and query string relative to the configured CouchDB URL, for example mydb/doc-1 or mydb/_all_docs?limit=10", "name" : "query" }, { "kind" : "table", "description" : "Request body: a table that is sent as JSON (application/json)", "name" : "table" } ] } ], "examples" : [ { "code" : "local doc = Couch.get(\"mydb/order-1001\")\nlocal deleted = Couch.delete(\"mydb/order-1001?rev=\" .. doc.table._rev)\nAssert.equals(200, deleted.status)" } ] } ] }, { "name" : "Csv", "kind" : "library", "description" : "Reads delimited text files (CSV) into Lua tables.\n\nThe reader is deliberately simple: every line is split on the delimiter, quotes are not interpreted (a quoted value that contains the delimiter is split in two) and a line break inside a value is not supported. The first line is not treated specially, so a header row is just row 1. A leading byte order mark is removed and the text is read in the JVM default charset (UTF-8 on current Java versions).", "library" : "Csv", "category" : "files", "variable" : "Csv", "functions" : [ { "name" : "read", "description" : "Reads a CSV file and returns all rows, including the header row, as lists of text values.\n\nEach value is trimmed. The delimiter is a regular expression, not a plain character: `;`, `,` and a tab (`\"\\t\"`) work as expected, but a pipe must be written `\"\\\\|\"` (a bare `|` splits between every character). Empty cells at the end of a line are dropped, so rows can have different lengths, and an empty line becomes a row with one empty value. Throws `Failed to read csv` when the file cannot be read.", "returns" : { "kind" : "table", "description" : "List of rows; each row is a list of strings" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "CSV file to read, relative to the workspace", "name" : "fileLocation" }, { "kind" : "string", "description" : "Delimiter as a regular expression, for example `;` or `,` (required)", "name" : "delimiter" } ] } ], "examples" : [ { "code" : "Fl.write(\"people.csv\", \"name;city\\nAlice;Utrecht\\nBob;Delft\")\nlocal rows = Csv.read(\"people.csv\", \";\")\nprint(rows[2][1], rows[2][2])", "runnable" : true } ] }, { "name" : "readAddress", "description" : "Reads an address list from a CSV file and returns a helper that serves one random address at a time. The file needs a header row (it is never picked) followed by lines of `street and number`, `zip code`, `city`. The delimiter is a regular expression, as in `Csv.read`.\n\nMeant for test data; see `ListAddress` for how the parts are extracted.", "returns" : { "kind" : "object", "ref" : "ListAddress" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "CSV file to read, relative to the workspace", "name" : "fileLocation" }, { "kind" : "string", "description" : "Delimiter as a regular expression, for example `;`", "name" : "delimiter" } ] } ], "examples" : [ { "code" : "Fl.write(\"addresses.csv\", \"street;zip;city\\nMain Street 12a;1234 AB;Utrecht\\nSide Road 5;5678 CD;Delft\")\nlocal addresses = Csv.readAddress(\"addresses.csv\", \";\")\nprint(addresses.street(), addresses.number(), addresses.zipcode(), addresses.city())", "runnable" : true } ] } ] }, { "name" : "ListAddress", "kind" : "object", "description" : "A random address from the list read by `Csv.readAddress`, split into street, number, number addition, zip code and city.\n\nThe first call to any part function picks a random data row (never the header row) and keeps it: all following calls return parts of that same address. `scramble` forgets it so the next call picks a new one. The file needs the header row and at least one data row; a file with only a header line or no lines throws an error when a part is requested. Column 1 is street and number (`Main Street 12a`), column 2 the zip code and column 3 the city.", "library" : "Csv", "category" : "files", "variable" : "listAddress", "howToGet" : [ { "type" : "Csv", "function" : "readAddress", "call" : "Csv.readAddress(fileLocation, delimiter)", "returns" : "ListAddress" } ], "returnedBy" : [ { "type" : "Csv", "function" : "readAddress" } ], "functions" : [ { "name" : "number", "description" : "Returns the digits of the street column with everything else removed (`Main Street 12a` gives `12`).", "returns" : { "kind" : "string" }, "overloads" : [ { "params" : [ ] } ] }, { "name" : "numberAddon", "description" : "Returns the text after the house number in the street column (`Main Street 12a` gives `a`), or an empty string when there is none.", "returns" : { "kind" : "string" }, "overloads" : [ { "params" : [ ] } ] }, { "name" : "zipcode", "description" : "Returns the zip code column with every character removed that is not a letter, digit or whitespace.", "returns" : { "kind" : "string" }, "overloads" : [ { "params" : [ ] } ] }, { "name" : "street", "description" : "Returns the street column with the digits removed (`Main Street 12a` gives `Main Street a`).", "returns" : { "kind" : "string" }, "overloads" : [ { "params" : [ ] } ] }, { "name" : "city", "description" : "Returns the city column of the current address, trimmed.", "returns" : { "kind" : "string" }, "overloads" : [ { "params" : [ ] } ] }, { "name" : "scramble", "description" : "Forgets the current address so the next part function picks a new random one. Returns the address helper itself, so it can be chained: `addresses.scramble().city()`.", "returns" : { "kind" : "self" }, "overloads" : [ { "params" : [ ] } ] } ] }, { "name" : "Dashboard", "kind" : "library", "description" : "Builds the dashboard of a run: headers, paragraphs, lists, tables, dividers and charts that the server shows on the dashboard tab of the run.\n\nEvery function appends one block after the previous ones and returns `Dashboard`, so calls can be chained. Blocks cannot be removed or reordered. The dashboard is stored as JSON when the run ends and `Dashboard.json` returns that same JSON.\n\nText is given as a text table `{ value = \"text\", color = \"red\", background = \"#eee\", size = 14 }` in which only `value` is required. `color` and `background` are CSS colors and `size` is a font size in pixels. In lists and tables, give the items as a plain Lua list (`{ {value = \"a\"}, {value = \"b\"} }`): entries with a non-numeric key are rejected.", "library" : "Dashboard", "category" : "api", "variable" : "Dashboard", "functions" : [ { "name" : "d", "description" : "Adds a divider: a horizontal line, with the text in it when text is given. Without text it is a plain line. Only the text color and the size (in pixels) can be set; there is no background.", "returns" : { "kind" : "self" }, "overloads" : [ { "params" : [ ] }, { "params" : [ { "kind" : "string", "description" : "Text shown in the divider; empty for a plain line", "name" : "text" } ] }, { "params" : [ { "kind" : "string", "description" : "Text shown in the divider; empty for a plain line", "name" : "text" }, { "kind" : "string", "description" : "Text color as a CSS color, like `red` or `#ff8800`", "name" : "color" } ] }, { "params" : [ { "kind" : "string", "description" : "Text shown in the divider; empty for a plain line", "name" : "text" }, { "kind" : "string", "description" : "Text color as a CSS color, like `red` or `#ff8800`", "name" : "color" }, { "kind" : "number", "description" : "Font size in pixels", "name" : "size" } ] } ], "examples" : [ { "code" : "Dashboard.h({ value = \"Nightly results\" }).p({ value = \"All checks passed\" })\nprint(Dashboard.json())", "runnable" : true } ] }, { "name" : "h", "description" : "Adds a header. The text must be a text table, a plain string is rejected with `First parameter must be a text table`. The level is 1 (largest) to 6; a value below 1 becomes 1 and a value above 6 throws. The default is 1. The server shows levels 1 to 5 as `h1` to `h5`; level 6 is currently shown as level 1.", "returns" : { "kind" : "self" }, "overloads" : [ { "params" : [ { "kind" : "shape", "ref" : "DashboardTextOptions", "description" : "The header text", "name" : "text" } ] }, { "params" : [ { "kind" : "shape", "ref" : "DashboardTextOptions", "description" : "The header text", "name" : "text" }, { "kind" : "number", "description" : "Header level from 1 (largest) to 6", "name" : "size" } ] } ] }, { "name" : "p", "description" : "Adds a paragraph of text. The text must be a text table; a plain string is rejected.", "returns" : { "kind" : "self" }, "overloads" : [ { "params" : [ { "kind" : "shape", "ref" : "DashboardTextOptions", "description" : "The paragraph text", "name" : "text" } ] } ] }, { "name" : "l", "description" : "Adds a list. The items are text tables in a plain Lua list; entries with a non-numeric key throw. The second argument marks the list as ordered (`true`) or unordered (`false`, the default) and must be a boolean, otherwise the call throws. The server shows ordered lists with numbers and unordered lists with bullets.", "returns" : { "kind" : "self" }, "overloads" : [ { "params" : [ { "kind" : "table", "description" : "List of text tables, one per item", "name" : "value" } ] }, { "params" : [ { "kind" : "table", "description" : "List of text tables, one per item", "name" : "value" }, { "kind" : "boolean", "description" : "true for an ordered list, false for an unordered one", "name" : "ordered" } ] } ], "examples" : [ { "code" : "Dashboard.l({ { value = \"login works\" }, { value = \"checkout fails\", color = \"red\" } })\nprint(Dashboard.json())", "runnable" : true } ] }, { "name" : "t", "description" : "Adds a table. The header cells and every cell of every row are text tables. A row may have fewer cells than there are headers but not more (that throws `Cell size ... can't be bigger than headers size`); entries of `rows` that are not tables are skipped.", "returns" : { "kind" : "self" }, "overloads" : [ { "params" : [ { "kind" : "table", "description" : "List of text tables for the header cells", "name" : "headers" }, { "kind" : "table", "description" : "List of rows; each row is a list of text tables, like `{ { {value = \"a\"}, {value = \"b\"} } }`", "name" : "values" } ] } ], "examples" : [ { "code" : "Dashboard.t(\n { { value = \"Check\" }, { value = \"Result\" } },\n {\n { { value = \"login\" }, { value = \"PASS\", color = \"green\" } },\n { { value = \"checkout\" }, { value = \"FAIL\", color = \"red\" } },\n })\nprint(Dashboard.json())", "runnable" : true } ] }, { "name" : "c", "description" : "Adds one or more charts, drawn in the browser with Chart.js. Pass a list of chart entries; each entry is a table with `height` and `width` (numbers; the server uses them as a percentage of the viewport height and width) and `chart`, a Chart.js configuration table with `type`, `data` and optionally `options`. The `chart` table is converted to JSON, so it can only hold strings, numbers, booleans and tables.\n\nThrows when the argument or an entry is not a table, when `height` or `width` is not a number, or when `chart` is not a table.", "returns" : { "kind" : "self" }, "overloads" : [ { "params" : [ { "kind" : "table", "description" : "List of chart entries `{ height, width, chart }`", "name" : "charts" } ] } ], "examples" : [ { "code" : "Dashboard.c({\n {\n height = 40,\n width = 30,\n chart = {\n type = \"bar\",\n data = {\n labels = { \"passed\", \"failed\" },\n datasets = { { label = \"Checks\", data = { 12, 3 } } },\n },\n },\n },\n})\nprint(Dashboard.json())", "runnable" : true } ] }, { "name" : "json", "description" : "Returns the dashboard built so far as pretty-printed JSON, the same text that is stored when the run ends. It is an object whose keys are the block positions (`\"0\"`, `\"1\"`, ...) in call order; with no blocks it is an empty object.", "returns" : { "kind" : "string", "description" : "The dashboard as JSON text" }, "overloads" : [ { "params" : [ ] } ] } ] }, { "name" : "Data", "kind" : "library", "description" : "Collects the result data of a run in one table.\n\nWhat you put in with `Data.set` is encoded as JSON when the run ends and stored with the run log, where the server shows it as the data of that run. The table is empty (`{}`) when nothing was set. Because the table is encoded like `Json.encode`, it may only hold strings, numbers, booleans and nested tables; a value JSON cannot hold makes the encoding fail.", "library" : "Data", "category" : "api", "variable" : "Data", "functions" : [ { "name" : "set", "description" : "Sets run data. With one argument, the given table replaces all data collected so far; the table is used as it is, not copied, so later changes to it are part of the data. With two arguments, one key is set; setting a key to `nil` removes it.\n\nWith a single argument that is not a table the call throws.", "returns" : { "kind" : "self" }, "overloads" : [ { "params" : [ { "kind" : "table", "description" : "Table that becomes the run data, replacing the current one", "name" : "luaTable" } ] }, { "params" : [ { "kind" : "any", "description" : "Key, normally a string", "name" : "key" }, { "kind" : "any", "description" : "Value to store: string, number, boolean or table", "name" : "value" } ] } ], "examples" : [ { "code" : "Data.set(\"status\", \"ok\")\nData.set(\"count\", 3)\nprint(Data.json())", "runnable" : true } ] }, { "name" : "clear", "description" : "Removes all run data collected so far.", "returns" : { "kind" : "self" }, "overloads" : [ { "params" : [ ] } ] }, { "name" : "get", "description" : "Returns the data table itself (not a copy), so changes to it change the run data.", "returns" : { "kind" : "table", "description" : "The current run data" }, "overloads" : [ { "params" : [ ] } ] }, { "name" : "json", "description" : "Returns the run data encoded as pretty-printed JSON, the same text that is stored when the run ends. Throws for values JSON cannot hold, as `Json.encode` does.", "returns" : { "kind" : "string", "description" : "The run data as JSON text" }, "overloads" : [ { "params" : [ ] } ] } ] }, { "name" : "Dates", "kind" : "library", "description" : "Formats, shifts and compares dates that are passed around as text.\n\nPatterns use Joda-Time letters: `yyyy` year, `MM` month, `dd` day, `HH` hour (0-23), `hh` hour (1-12) with `a` for AM/PM, `mm` minutes, `ss` seconds, `EEEE` day name, `MMMM` month name, `Z` zone offset; put literal letters in single quotes (`yyyy-MM-dd'T'HH:mm`). A date without a time is midnight in the time zone of the agent. Day and month names follow the language set with `Dates.locale`, by default that of the agent.\n\nWhen dates are shifted the order is days, weeks, months, years, and a day that does not exist in the target month moves to the end of that month (31-01-2024 plus one month is 29-02-2024). A date that does not fit its pattern, or does not exist (31-02-2024), throws.", "library" : "Dates", "category" : "dates", "variable" : "Dates", "functions" : [ { "name" : "today", "description" : "Returns today's date, and optionally the time, formatted as text, in the time zone of the agent. Without arguments the pattern is `dd-MM-yyyy`. Five arguments shift the date by a number of days, weeks, months and years (negative numbers go back; pass 0 to skip one).\n\nUse exactly 0, 1 or 5 arguments: with 2, 3 or 4 arguments only the pattern is used and the shifts are silently ignored.", "returns" : { "kind" : "string", "description" : "Today's date in the requested pattern" }, "overloads" : [ { "params" : [ ] }, { "params" : [ { "kind" : "string", "description" : "Output pattern, for example `yyyy-MM-dd HH:mm`", "name" : "pattern" } ] }, { "params" : [ { "kind" : "string", "description" : "Output pattern, for example `yyyy-MM-dd HH:mm`", "name" : "pattern" }, { "kind" : "number", "description" : "Days to add (negative to subtract)", "name" : "day" }, { "kind" : "number", "description" : "Weeks to add (negative to subtract)", "name" : "week" }, { "kind" : "number", "description" : "Months to add (negative to subtract)", "name" : "month" }, { "kind" : "number", "description" : "Years to add (negative to subtract)", "name" : "year" } ] } ], "examples" : [ { "code" : "print(Dates.today(\"yyyy-MM-dd\"))\nprint(Dates.format(\"31-12-2024\", \"dd-MM-yyyy\", \"yyyy/MM/dd\"))\nprint(Dates.daysBetween(\"01-01-2024\", \"31-01-2024\"))", "runnable" : true } ] }, { "name" : "format", "description" : "Converts a date from one pattern to another, optionally shifting it on the way. Seven arguments shift the date by days, weeks, months and years (negative numbers go back; 0 skips one).\n\nUse exactly 3 or 7 arguments: with 4, 5 or 6 arguments the shifts are silently ignored. Throws when the date does not fit the `from` pattern.", "returns" : { "kind" : "string", "description" : "The date in the `to` pattern" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "The date as text", "name" : "date" }, { "kind" : "string", "description" : "Pattern the date is written in", "name" : "from" }, { "kind" : "string", "description" : "Pattern of the result", "name" : "to" } ] }, { "params" : [ { "kind" : "string", "description" : "The date as text", "name" : "date" }, { "kind" : "string", "description" : "Pattern the date is written in", "name" : "from" }, { "kind" : "string", "description" : "Pattern of the result", "name" : "to" }, { "kind" : "number", "description" : "Days to add (negative to subtract)", "name" : "day" }, { "kind" : "number", "description" : "Weeks to add (negative to subtract)", "name" : "week" }, { "kind" : "number", "description" : "Months to add (negative to subtract)", "name" : "month" }, { "kind" : "number", "description" : "Years to add (negative to subtract)", "name" : "year" } ] } ], "examples" : [ { "code" : "print(Dates.format(\"31-01-2024\", \"dd-MM-yyyy\", \"yyyy/MM/dd\"))\nprint(Dates.format(\"31-01-2024\", \"dd-MM-yyyy\", \"dd-MM-yyyy\", 0, 0, 1, 0))", "runnable" : true } ] }, { "name" : "yearsBetween", "description" : "Returns the number of complete years from the first date to the second. The result is negative when the second date is earlier. Both dates must be written as `dd-MM-yyyy`; other formats throw.", "returns" : { "kind" : "number", "description" : "Whole years, negative when the second date is earlier" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "First date as `dd-MM-yyyy`", "name" : "date1" }, { "kind" : "string", "description" : "Second date as `dd-MM-yyyy`", "name" : "date2" } ] } ] }, { "name" : "monthsBetween", "description" : "Returns the number of complete months from the first date to the second. The result is negative when the second date is earlier. Both dates must be written as `dd-MM-yyyy`; other formats throw.", "returns" : { "kind" : "number", "description" : "Whole months, negative when the second date is earlier" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "First date as `dd-MM-yyyy`", "name" : "date1" }, { "kind" : "string", "description" : "Second date as `dd-MM-yyyy`", "name" : "date2" } ] } ] }, { "name" : "daysBetween", "description" : "Returns the number of complete days from the first date to the second. The result is negative when the second date is earlier. Both dates must be written as `dd-MM-yyyy`; other formats throw.", "returns" : { "kind" : "number", "description" : "Whole days, negative when the second date is earlier" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "First date as `dd-MM-yyyy`", "name" : "date1" }, { "kind" : "string", "description" : "Second date as `dd-MM-yyyy`", "name" : "date2" } ] } ] }, { "name" : "locale", "description" : "Sets the language used for day and month names, when parsing and when formatting, for all later calls of this library. Only a plain language code works (`nl`, `en`, `de`, `fr`): a value like `nl-NL` or `nl_NL` is accepted but does not select a language, so names stay in English. An empty value goes back to the language of the agent.", "returns" : { "kind" : "self" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "Language code, like `nl` or `en`", "name" : "value" } ] } ], "examples" : [ { "code" : "Dates.locale(\"nl\")\nprint(Dates.format(\"01-03-2024\", \"dd-MM-yyyy\", \"EEEE d MMMM yyyy\"))", "runnable" : true } ] }, { "name" : "with", "description" : "Sets parts of a date to fixed values and returns the date in the same pattern. Unlike the shifting arguments of `Dates.format`, the numbers here are the new values (day 1 means the first of the month); 0 keeps the current value. The parts are applied in this order: day of the month, ISO week of the year, month, year. A part that does not exist for the date at that moment (day 31 in a 30-day month, month 13) throws, and a day that is valid when set can still move to the end of the month when the month is changed afterwards.\n\nAll six arguments are required. Throws when the date does not fit the pattern.", "returns" : { "kind" : "string", "description" : "The changed date, written in `pattern`" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "Pattern of the date, also used for the result, for example `dd-MM-yyyy`", "name" : "pattern" }, { "kind" : "string", "description" : "The date as text", "name" : "date" }, { "kind" : "number", "description" : "Day of the month to set (1-31), 0 to keep it", "name" : "day" }, { "kind" : "number", "description" : "ISO week of the year to set (1-53), 0 to keep it", "name" : "week" }, { "kind" : "number", "description" : "Month to set (1-12), 0 to keep it", "name" : "month" }, { "kind" : "number", "description" : "Year to set, 0 to keep it", "name" : "year" } ] } ], "examples" : [ { "code" : "print(Dates.with(\"dd-MM-yyyy\", \"15-03-2024\", 1, 0, 0, 0)) -- first of the month\nprint(Dates.with(\"dd-MM-yyyy\", \"15-03-2024\", 0, 0, 12, 2030))", "runnable" : true } ] } ] }, { "name" : "Fl", "kind" : "library", "description" : "Reads, writes, copies, moves, removes, inspects and searches files in the project workspace.\n\nPaths are relative to the workspace of the run, which is the project folder on the agent. Text files are read and written in the JVM default charset (UTF-8 on current Java versions).\n\nWhen a script runs through a Reflex server, a file or folder that is not on the agent yet is first fetched from the project's files on the server, `Fl.remove` also deletes it there, and the files a run leaves behind (except `.lua` files) are copied back to the project when the run ends. A script run directly on the agent (for example with the CLI) only uses its local project folder.\n\nBy default paths are not confined to the workspace: `..` is followed, and so are absolute paths when the script runs directly on the agent. An agent started with `agent.files.confineToWorkspace=true` (`AGENT_FILES_CONFINE_TO_WORKSPACE`) rejects absolute paths and anything that leaves the workspace, symlinks included, in every file function of the libraries.", "library" : "Fl", "category" : "files", "variable" : "Fl", "functions" : [ { "name" : "mkdir", "description" : "Creates a directory including any missing parent directories. Does nothing when it exists.", "returns" : { "kind" : "self" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "Directory to create, relative to the workspace", "name" : "folderDir" } ] } ] }, { "name" : "getFiles", "description" : "Lists the files directly inside a directory, most recently modified first. Subdirectories are not listed and the search is not recursive: use `Fl.find` or `Fl.glob` for that.\n\nEvery entry is the path of the file relative to the workspace, so it starts with the directory you passed (`./report.csv` for `.`, `exports/report.csv` for `exports`). A directory that does not exist gives an empty list.", "returns" : { "kind" : "table", "description" : "List of file paths (strings), newest first" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "Directory to list, relative to the workspace", "name" : "location" } ] } ], "examples" : [ { "code" : "Fl.write(\"exports/a.txt\", \"a\")\nFl.write(\"exports/b.txt\", \"b\")\nfor _, file in ipairs(Fl.getFiles(\"exports\")) do\n print(file)\nend", "runnable" : true } ] }, { "name" : "beingWritten", "description" : "Tells whether a file is still growing: reads its size, waits 500 ms, reads it again and returns `true` when the size changed. Use it to wait until a download or export has finished before reading the file.\n\nBlocks the script for 500 ms and throws when the file does not exist.", "returns" : { "kind" : "boolean", "description" : "true when the size changed during the 500 ms" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "File to check, relative to the workspace", "name" : "file" } ] } ] }, { "name" : "remove", "description" : "Deletes a file, or a directory together with everything in it. When the script runs through a Reflex server the file or directory is also deleted from the project's files on the server.\n\nThrows an error when the path does not exist.", "returns" : { "kind" : "self" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "File or directory to delete, relative to the workspace", "name" : "fileLua" } ] } ], "examples" : [ { "code" : "Fl.write(\"scratch/tmp.txt\", \"temporary\")\nFl.remove(\"scratch\")\nprint(Fl.exists(\"scratch\"))", "runnable" : true } ] }, { "name" : "copy", "description" : "Copies one file. The target is overwritten when it exists and its missing parent directories are created. Directories cannot be copied: the call throws `Failed to copy file`, as it does when the source is missing.", "returns" : { "kind" : "self" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "File to copy, relative to the workspace", "name" : "source" }, { "kind" : "string", "description" : "Path of the copy, relative to the workspace", "name" : "target" } ] } ] }, { "name" : "exists", "description" : "Checks whether a file or directory exists. When the script runs through a Reflex server, a path that is not on the agent yet is looked up in the project's files on the server and fetched, so project files count as existing.", "returns" : { "kind" : "boolean" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "File or directory, relative to the workspace", "name" : "location" } ] } ] }, { "name" : "move", "description" : "Moves a file or directory to a new path. Missing parent directories of the target are created and an existing target file is replaced. Throws `Source path not found` when the source does not exist. To change only the name, use `Fl.rename`.", "returns" : { "kind" : "self" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "File or directory to move, relative to the workspace", "name" : "source" }, { "kind" : "string", "description" : "New path, relative to the workspace", "name" : "target" } ] } ] }, { "name" : "rename", "description" : "Renames a file or directory inside its current directory. An existing item with the new name is replaced. Throws when the new name contains a directory part or is absolute, and when the source does not exist. To move something to another directory, use `Fl.move`.", "returns" : { "kind" : "self" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "File or directory to rename, relative to the workspace", "name" : "source" }, { "kind" : "string", "description" : "New name only, without any directory, like `new.txt`", "name" : "newName" } ] } ] }, { "name" : "stat", "description" : "Returns metadata of a file or directory: type, size in bytes and timestamps. A path that does not exist is not an error: the table then only has `path` and `exists = false`.", "returns" : { "kind" : "shape", "ref" : "FileStat" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "File or directory, relative to the workspace", "name" : "location" } ] } ], "examples" : [ { "code" : "Fl.write(\"report.txt\", \"hello\")\nlocal info = Fl.stat(\"report.txt\")\nprint(info.exists, info.type, info.size, info.modifiedAt)\nprint(Fl.stat(\"missing.txt\").exists)", "runnable" : true } ] }, { "name" : "find", "description" : "Searches a directory recursively and returns every file and directory found below it (not the directory itself), sorted alphabetically. With a pattern only the matching entries are returned. When `root` is a single file, the result is that file (if it matches). A path that does not exist gives an empty list.\n\nThe returned paths are relative to the workspace (not to `root`) and always use `/`.\n\nThe pattern is a glob such as `*.csv` or `reports/**/*.pdf`, matched against the path relative to `root`. A pattern without `/` is also matched against the bare name of every entry, so `*.csv` finds CSV files at any depth, and a leading `**/` also matches entries directly in `root`. `Fl.glob` does the same with the pattern as the main argument.", "returns" : { "kind" : "table", "description" : "List of paths (strings) relative to the workspace" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "Directory or file to search from, relative to the workspace", "name" : "root" } ] }, { "params" : [ { "kind" : "string", "description" : "Directory or file to search from, relative to the workspace", "name" : "root" }, { "kind" : "string", "description" : "Glob pattern the entries must match, like `*.csv`", "name" : "pattern" } ] } ], "examples" : [ { "code" : "Fl.write(\"data/a.csv\", \"1\")\nFl.write(\"data/nested/b.csv\", \"2\")\nFl.write(\"data/c.txt\", \"3\")\nfor _, path in ipairs(Fl.find(\"data\", \"*.csv\")) do\n print(path)\nend", "runnable" : true } ] }, { "name" : "glob", "description" : "Returns the files and directories whose path matches a glob pattern, searching the whole workspace or the directory given as first argument. Same as `Fl.find` with a pattern, including how patterns are matched: `*.csv` matches CSV files at any depth. Paths are relative to the workspace, use `/` and are sorted alphabetically.", "returns" : { "kind" : "table", "description" : "List of matching paths (strings) relative to the workspace" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "Glob pattern like `*.csv` or `reports/**/*.pdf`", "name" : "pattern" } ] }, { "params" : [ { "kind" : "string", "description" : "Directory to search from, relative to the workspace", "name" : "root" }, { "kind" : "string", "description" : "Glob pattern like `*.csv` or `reports/**/*.pdf`", "name" : "pattern" } ] } ], "examples" : [ { "code" : "Fl.write(\"out/one.csv\", \"1\")\nFl.write(\"out/two.csv\", \"2\")\nprint(#Fl.glob(\"*.csv\"))\nprint(#Fl.glob(\"out\", \"one.*\"))", "runnable" : true } ] }, { "name" : "read", "description" : "Reads a text file and returns its lines as a list. Line breaks are removed, a final line break does not add an empty entry and an empty file gives an empty list. The whole file is read into memory.\n\nThrows `File not found` when the file cannot be read. For structured files use `Json`, `Yaml`, `Csv`, `Xml` or `Xlsx`.", "returns" : { "kind" : "table", "description" : "List of strings, one per line" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "File to read, relative to the workspace", "name" : "fileLoc" } ] } ], "examples" : [ { "code" : "Fl.write(\"notes.txt\", \"first line\\nsecond line\")\nlocal lines = Fl.read(\"notes.txt\")\nprint(#lines, lines[1])\nprint(Fl.exists(\"notes.txt\"))", "runnable" : true } ] }, { "name" : "write", "description" : "Writes text to a file and creates missing parent directories.\n\nWith two arguments the text is appended to the file, not written over it: when the file already has content a line break is inserted first, so every call adds one line and the file never ends with a trailing line break. To replace the content of the file call it with four arguments and `append = false`.\n\nPass exactly 2 or 4 arguments. With 3 arguments the third is ignored and the call appends. Numbers and other values are converted to text.", "returns" : { "kind" : "self" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "File to write, relative to the workspace", "name" : "fileName" }, { "kind" : "string", "description" : "Text to write", "name" : "content" } ] }, { "params" : [ { "kind" : "string", "description" : "File to write, relative to the workspace", "name" : "fileName" }, { "kind" : "string", "description" : "Text to write", "name" : "content" }, { "kind" : "boolean", "description" : "true to append to the existing content, false to replace the file", "name" : "append" }, { "kind" : "boolean", "description" : "Only used when appending to a file that already has content: true to put a line break before the text", "name" : "newLine" } ] } ], "examples" : [ { "code" : "Fl.write(\"log.txt\", \"first\")\nFl.write(\"log.txt\", \"second\") -- appended on a new line\nFl.write(\"log.txt\", \"only line\", false, false) -- replaces the content\nprint(#Fl.read(\"log.txt\"))", "runnable" : true } ] } ] }, { "name" : "Json", "kind" : "library", "description" : "Reads, encodes, decodes and converts JSON.\n\n`Json.decode` turns JSON text into Lua tables and `Json.encode` does the reverse. Lua has no null: a JSON `null` becomes `nil`, so object keys with a null value are absent from the decoded table and a null array item leaves a hole in it.\n\nWhen encoding, a table is written as an array if it has a key `1` (or is empty) and as an object otherwise. Object keys must be strings, arrays must not have holes, and objects are written in Lua's table order, which is neither alphabetical nor the order the keys were added.", "library" : "Json", "category" : "files", "variable" : "Json", "functions" : [ { "name" : "open", "description" : "Reads a JSON file and decodes it like `Json.decode`. The file is parsed first with a standard JSON parser, so its parse errors are the ones you see. Throws `Failed to read JSON file` when the file is missing or is not valid JSON. An empty file gives `nil`.", "returns" : { "kind" : "any", "description" : "The decoded value: a table for an object or array, otherwise a string, number or boolean" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "JSON file to read, relative to the workspace", "name" : "file" } ] } ], "examples" : [ { "code" : "Fl.write(\"config.json\", '{\"name\": \"demo\", \"retries\": 3, \"tags\": [\"a\", \"b\"]}')\nlocal config = Json.open(\"config.json\")\nprint(config.name, config.retries, config.tags[2])", "runnable" : true } ] }, { "name" : "encode", "description" : "Encodes a table as JSON text, pretty-printed with two spaces of indentation. An empty table gives `{}`.\n\nThrows when the argument is not a table, when an object has non-string keys or an array has holes, when a table contains itself, and for values JSON cannot hold (functions, `NaN`, infinity). Write the result to a file with `Fl.write(path, text, false, false)`.", "returns" : { "kind" : "string", "description" : "The JSON text" }, "overloads" : [ { "params" : [ { "kind" : "table", "description" : "Table to encode: an array or an object with string keys", "name" : "table" } ] } ] }, { "name" : "decode", "description" : "Decodes JSON text. Objects and arrays become tables, numbers become Lua numbers and unicode escapes (backslash, u and four hex digits, including surrogate pairs) become UTF-8 text. `null` becomes `nil`.\n\nThrows an error naming the line and column when the text is not valid JSON, including when anything other than whitespace follows the value.", "returns" : { "kind" : "any", "description" : "The decoded value: a table for an object or array, otherwise a string, number or boolean" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "JSON text to decode", "name" : "json" } ] } ], "examples" : [ { "code" : "local data = Json.decode('{\"name\": \"Alice\", \"tags\": [\"a\", \"b\"]}')\nprint(data.name, data.tags[2])\nprint(Json.encode({ answer = 42 }))", "runnable" : true } ] }, { "name" : "format", "description" : "Re-indents JSON text with two spaces without turning it into a table, so the order of the keys is kept. Throws a parser error when the text is not valid JSON.", "returns" : { "kind" : "string", "description" : "The formatted JSON text" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "JSON text to format", "name" : "js" } ] } ], "examples" : [ { "code" : "print(Json.format('{\"b\":1,\"a\":[1,2]}'))", "runnable" : true } ] }, { "name" : "xml", "description" : "Converts XML text to JSON text. Pass the result to `Json.decode` to get a table. Attributes become keys that start with `-`, element text becomes `#text` when the element also has attributes, repeated elements become an array and empty elements get `\"-self-closing\": \"true\"`. All values are strings. Throws when the text is not valid XML. `Json.toXml` converts back.", "returns" : { "kind" : "string", "description" : "The JSON text" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "XML text to convert", "name" : "xml" } ] } ], "examples" : [ { "code" : "local json = Json.xml(\"WidgetGadget\")\nlocal order = Json.decode(json).order\nprint(order[\"-id\"], #order.item)", "runnable" : true } ] }, { "name" : "toXml", "description" : "Converts JSON text to XML text with an XML declaration. The single top-level key becomes the root element; with several top-level keys (or an array) a `root` element is added. Array items become repeated elements, keys that start with `-` become attributes and `#text` the text of the element. Numbers, booleans and nulls get an attribute `number=\"true\"`, `boolean=\"true\"` or `null=\"true\"`. Throws `Not a valid JSON string` when the text cannot be parsed.", "returns" : { "kind" : "string", "description" : "The XML text" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "JSON text to convert", "name" : "js" } ] } ], "examples" : [ { "code" : "print(Json.toXml('{\"order\": {\"-id\": \"7\", \"item\": [\"Widget\", \"Gadget\"]}}'))", "runnable" : true } ] } ] }, { "name" : "Mail", "kind" : "library", "description" : "Sends email over SMTP and reads a mailbox over IMAP or POP3. Mail.properties returns a Compose object to send with, Mail.imap and Mail.pop return a Mailbox to read with.\n\nThings to know: the SMTP server is configured with the short keys host, port, auth and starttls or with JavaMail property names ([\"mail.smtp.host\"]); both work. Mail.imap and Mail.pop connect immediately and raise an error when the login fails. Mailboxes are read-only: you can read and search but not delete, move or mark messages. No timeouts are set unless you add the JavaMail timeout properties. Keep passwords in secrets: secret(\"name\"). Close mailboxes with mailbox.close() or Mail.close().", "library" : "Mail", "category" : "mail", "variable" : "Mail", "functions" : [ { "name" : "properties", "description" : "Prepares sending mail over SMTP and returns a Compose object; no connection is made until you call send or sendFile on it. The table is handed to JavaMail as its properties, so JavaMail names work as well. Configure the server with host, port, auth = true to log in with user and password, starttls = true (port 587) or ssl = true (port 465) to encrypt. These are aliases for [\"mail.smtp.host\"], [\"mail.smtp.port\"], [\"mail.smtp.auth\"], [\"mail.smtp.starttls.enable\"] and [\"mail.smtp.ssl.enable\"]; the JavaMail key wins when both are given, and any other mail.smtp.* property can be added, such as [\"mail.smtp.connectiontimeout\"] and [\"mail.smtp.timeout\"] in milliseconds (default: wait forever). The keys user and password (or username) are used as login and the user is also the sender address of every mail. Without a host JavaMail tries localhost:25. An older list form {\"mail.smtp.host, smtp.example.com\"} also works. Raises an error when the argument is not a table.", "returns" : { "kind" : "object", "ref" : "Compose" }, "overloads" : [ { "params" : [ { "kind" : "shape", "ref" : "SmtpSettings", "description" : "JavaMail properties plus user and password", "name" : "list" } ] } ], "examples" : [ { "code" : "local smtp = Mail.properties({\n [\"mail.smtp.host\"] = \"smtp.example.com\",\n [\"mail.smtp.port\"] = 587,\n [\"mail.smtp.auth\"] = \"true\",\n [\"mail.smtp.starttls.enable\"] = \"true\",\n [\"mail.smtp.connectiontimeout\"] = 10000,\n [\"mail.smtp.timeout\"] = 20000,\n user = \"bot@example.com\",\n password = secret(\"smtp_password\"),\n})\nsmtp.send(\"alice@example.com\", \"Nightly report\", \"

The report is ready.

\")" } ] }, { "name" : "imap", "description" : "Connects to an IMAP server, logs in, opens a folder (INBOX unless folder is given) and returns the Mailbox. SSL is used by default (port 993). Raises an error when host, user or password is missing, when the login or connection fails (\"Failed to connect to mailbox: ...\") or when the folder does not exist. Add JavaMail properties such as [\"mail.imap.connectiontimeout\"] = 10000 to the table to set timeouts, which are unlimited by default. Close the mailbox when you are done.", "returns" : { "kind" : "object", "ref" : "Mailbox" }, "overloads" : [ { "params" : [ { "kind" : "shape", "ref" : "MailboxSettings", "description" : "Server, login and options; host, user and password are required", "name" : "list" } ] } ], "examples" : [ { "code" : "local mailbox = Mail.imap({\n host = \"imap.example.com\",\n user = \"bot@example.com\",\n password = secret(\"mail_password\"),\n [\"mail.imap.connectiontimeout\"] = 10000,\n})\nlocal unread = mailbox.search({ seen = false, subject = \"Invoice\", limit = 10 })\nfor _, message in ipairs(unread) do\n print(message.subject, message.from[1], message.has_attachments)\nend\nmailbox.close()" } ] }, { "name" : "pop", "description" : "Connects to a POP3 server, logs in and returns the Mailbox for its inbox. Same settings and errors as Mail.imap, but without SSL by default (port 110; set ssl = true or port 995 for SSL). POP3 has a single folder (INBOX) and no message flags, so seen is always false and the seen/unseen search criteria are not useful. Prefer IMAP when the server offers it.", "returns" : { "kind" : "object", "ref" : "Mailbox" }, "overloads" : [ { "params" : [ { "kind" : "shape", "ref" : "MailboxSettings", "description" : "Server, login and options; host, user and password are required", "name" : "list" } ] } ], "examples" : [ { "code" : "local mailbox = Mail.pop({ host = \"pop.example.com\", user = \"bot@example.com\", password = secret(\"mail_password\"), ssl = true })\nprint(#mailbox.messages() .. \" messages\")\nmailbox.close()" } ] }, { "name" : "close", "description" : "Closes every mailbox opened with Mail.imap or Mail.pop in this script. Use mailbox.close() to close one.", "returns" : { "kind" : "self" }, "overloads" : [ { "params" : [ ] } ] } ], "examples" : [ { "code" : "-- Send a notification, then wait for the answer in the inbox\nlocal smtp = Mail.properties({\n [\"mail.smtp.host\"] = \"smtp.example.com\",\n [\"mail.smtp.port\"] = 587,\n [\"mail.smtp.auth\"] = \"true\",\n [\"mail.smtp.starttls.enable\"] = \"true\",\n user = \"bot@example.com\",\n password = secret(\"mail_password\"),\n})\nsmtp.send(\"alice@example.com\", \"Please confirm\", \"

Reply to confirm the order.

\")\n\nlocal mailbox = Mail.imap({ host = \"imap.example.com\", user = \"bot@example.com\", password = secret(\"mail_password\") })\nlocal replies = mailbox.poll({ from = \"alice@example.com\", subject = \"Re: Please confirm\" }, 120)\nAssert.equals(1, #replies)\nmailbox.close()", "description" : "Send a mail and wait for the reply" } ] }, { "name" : "Compose", "kind" : "object", "description" : "Sends email through the SMTP server configured with Mail.properties. Every send opens a new connection, sends one HTML mail from the configured user and closes the connection again. Errors (connection refused, login rejected, invalid address, missing attachment file) are raised as \"Error caught while trying to send e-mail: ...\".", "library" : "Mail", "category" : "mail", "variable" : "smtp", "howToGet" : [ { "type" : "Mail", "function" : "properties", "call" : "Mail.properties(list)", "returns" : "Compose" } ], "returnedBy" : [ { "type" : "Mail", "function" : "properties" } ], "functions" : [ { "name" : "send", "description" : "Sends an email from the configured user. The body is sent as HTML (text/html, UTF-8), so use `
` or `

` for line breaks; plain newlines are collapsed by mail clients. The recipient argument takes one address or several separated by commas (\"a@x.com, b@x.com\"); there is no cc, bcc or reply-to. With logging true the log of the current step is attached as a text file, which is handy for failure notifications. Returns the Compose object when the server accepted the mail, which does not guarantee delivery.", "returns" : { "kind" : "self" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "Recipient address, or several separated by commas", "name" : "toEmail" }, { "kind" : "string", "description" : "Subject line", "name" : "subject" }, { "kind" : "string", "description" : "Message body as HTML", "name" : "body" } ] }, { "params" : [ { "kind" : "string", "description" : "Recipient address, or several separated by commas", "name" : "toEmail" }, { "kind" : "string", "description" : "Subject line", "name" : "subject" }, { "kind" : "string", "description" : "Message body as HTML", "name" : "body" }, { "kind" : "boolean", "description" : "true to attach the log of the current step; default false", "name" : "logging" } ] } ], "examples" : [ { "code" : "local smtp = Mail.properties({\n [\"mail.smtp.host\"] = \"smtp.example.com\",\n [\"mail.smtp.port\"] = 587,\n [\"mail.smtp.auth\"] = \"true\",\n [\"mail.smtp.starttls.enable\"] = \"true\",\n user = \"bot@example.com\",\n password = secret(\"mail_password\"),\n})\nsmtp.send(\"alice@example.com, bob@example.com\", \"Nightly run finished\", \"

All 42 checks passed.

\")\nsmtp.send(\"qa-team@example.com\", \"Nightly run FAILED\", \"See the attached log.\", true)" } ] }, { "name" : "sendFile", "description" : "Sends an HTML email with one file from the project attached. Recipients, body and errors work as in send. The file is attached as it is on disk (a missing file raises an error), under its own file name. With logging true the step log is attached as well.", "returns" : { "kind" : "self" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "Recipient address, or several separated by commas", "name" : "toEmail" }, { "kind" : "string", "description" : "Subject line", "name" : "subject" }, { "kind" : "string", "description" : "Message body as HTML", "name" : "body" }, { "kind" : "string", "description" : "Path of the file in the project to attach", "name" : "file" } ] }, { "params" : [ { "kind" : "string", "description" : "Recipient address, or several separated by commas", "name" : "toEmail" }, { "kind" : "string", "description" : "Subject line", "name" : "subject" }, { "kind" : "string", "description" : "Message body as HTML", "name" : "body" }, { "kind" : "string", "description" : "Path of the file in the project to attach", "name" : "file" }, { "kind" : "boolean", "description" : "true to attach the log of the current step; default false", "name" : "logging" } ] } ], "examples" : [ { "code" : "smtp.sendFile(\"alice@example.com\", \"Report\", \"

The report is attached.

\", \"reports/summary.pdf\")" } ] } ] }, { "name" : "Mailbox", "kind" : "object", "description" : "A logged-in IMAP or POP3 mailbox with one open folder. List, search and poll messages, and save their attachments to the project. The mailbox is read-only: nothing is deleted, moved or marked as read, so the same messages are found again by the next search. Messages are downloaded when you list or search them, so use search criteria and limit on large folders. The connection is re-established automatically if it was dropped, also after close().", "library" : "Mail", "category" : "mail", "variable" : "mailbox", "howToGet" : [ { "type" : "Mail", "function" : "imap", "call" : "Mail.imap(list)", "returns" : "Mailbox" } ], "returnedBy" : [ { "type" : "Mail", "function" : "imap" }, { "type" : "Mail", "function" : "pop" } ], "functions" : [ { "name" : "folder", "description" : "Opens another folder of the mailbox (for example \"Archive\" or \"INBOX/Invoices\"; the separator depends on the server). Raises an error when the folder does not exist, or for any folder other than INBOX on POP3. Later calls read from this folder, and message numbers refer to it.", "returns" : { "kind" : "self" }, "overloads" : [ { "params" : [ { "kind" : "string", "description" : "Folder name as the server knows it, case-sensitive on most servers", "name" : "name" } ] } ] }, { "name" : "refresh", "description" : "Closes and reopens the current folder so that messages that arrived since it was opened become visible. poll does this by itself on every round; use refresh before messages, search or get when you wait for mail some other way.", "returns" : { "kind" : "self" }, "overloads" : [ { "params" : [ ] } ] }, { "name" : "messages", "description" : "Returns every message in the current folder, newest first. All messages are downloaded and parsed, which is slow for a large folder; use search with a limit instead.", "returns" : { "kind" : "list", "ref" : "MailMessage" }, "overloads" : [ { "params" : [ ] } ] }, { "name" : "get", "description" : "Returns the message with the given sequence number (the number field of a message, 1 is the oldest). The number can change when messages are added or removed, so use a number from a recent messages, search or poll result. Raises \"No message found with number N\" when it is out of range.", "returns" : { "kind" : "shape", "ref" : "MailMessage" }, "overloads" : [ { "params" : [ { "kind" : "number", "description" : "Sequence number from the number field of a message", "name" : "number" } ] } ] }, { "name" : "search", "description" : "Returns the messages of the current folder that match all given criteria, newest first (see MailSearch for the keys). A plain string instead of a table searches the subject, sender, recipients, body and Message-ID for that text. Matching is done in the agent, case-insensitively, on text that contains the search term. Returns an empty list when nothing matches; it does not wait for new mail (use poll for that) and does not see mail that arrived after the folder was opened until you call refresh. Raises an error for a date in since or before that cannot be parsed.", "returns" : { "kind" : "list", "ref" : "MailMessage" }, "overloads" : [ { "params" : [ { "kind" : "shape", "ref" : "MailSearch", "description" : "Search criteria table, or a string to search in subject, sender, recipients, body and Message-ID", "name" : "criteria" } ] } ], "examples" : [ { "code" : "local invoices = mailbox.search({ subject = \"invoice\", hasAttachments = true, since = \"2025-01-01\", limit = 5 })\nfor _, message in ipairs(invoices) do\n print(message.number, message.subject, message.sent_at_iso)\nend\nlocal byText = mailbox.search(\"password reset\")" } ] }, { "name" : "poll", "description" : "Waits for mail: reopens the folder and searches it every interval until at least one message matches, then returns the matches (newest first). When the timeout passes without a match it returns an empty list and does not raise an error, so check the result. A timeout of 0 checks once. Defaults: 30 seconds timeout, 1000 ms interval.\n\nMessages that are already in the folder count too, so a poll for a subject that older mail also has returns immediately. Make the criteria specific (a unique subject or code, or since =