Docs / Files, mail, documents

a9script authoring pack — files functions

The files functions, with their arguments and a line of real script each. Called by bare name; nothing is imported. A call marked pauses does real work outside the script: the run is saved, and continues on the next line with the result.

This is one part of the authoring pack — how a script is executed at all is the model part, and the other groups of functions are parts of their own. All of them are named at the end.

Generated — do not edit. Every block of script below is executed by the platform’s own test suite, and every error message is the one the platform produces today, so none of this can be what was true when someone last wrote it down.

writeBlob(contentBase64, mime?) — pauses

Stores bytes as a file and answers a handle for them. Keep the handle and pass it on — the bytes stay in storage instead of being carried through the script, which is what makes files of any size safe to work with.

• contentBase64 (string) — The contents as base64 text — base64Encode makes it from text. Text that is not base64 is refused rather than stored short, because a file that lost its tail looks fine until someone opens it.
• mime (string, optional) — What the file is, such as "application/pdf" or "text/csv". Stored with it and answered by readBlob.

Answers: The handle: sha256: and the fingerprint of the contents. It IS the contents, so storing the same bytes again answers the same handle and keeps one copy — including when another environment stores the same file, which still cannot read yours.

const handle = writeBlob(base64Encode("sku,qty\nA-1,2\n"), "text/csv");
log("stored as " + handle);

readBlob(blobId) — pauses

Reads a stored file back: its contents, the type it was stored with, and its size. Read a file only when the script itself has to look inside it — passing the handle on costs nothing whatever the file weighs.

• blobId (string) — The handle writeBlob answered. A file belongs to the environment that stored it: a handle from anywhere else is refused exactly as one that was never stored, and it never answers an empty file.

Answers: { contentBase64, mime, bytes } — the contents as base64 text, the type THIS environment stored it with (missing when it was stored without one), and the true size in bytes. A file too large to carry in a script is refused rather than truncated: keep passing the handle instead.

const handle = writeBlob(base64Encode("hello"), "text/plain");
const file = readBlob(handle);
log("the file holds " + file.bytes + " bytes");

readFile(path, options?) — pauses

Reads a file out of one of this environment’s file stores, by the path it was put there under. Use it for the things somebody uploaded — a logo, a template, a fixture — and for what an earlier run left behind.

• path (string) — Where the file sits in its store. It may contain slashes, so "assets/logo.png" is one path and not two.
• options (object, optional) — { store } — which file store to read from. Left out, it means the store this environment marks as its default; an environment that marks none says so rather than picking one.

Answers: { contentBase64, mime, bytes } — the contents as base64 text, the type it was stored with (missing when it was stored without one), and its true size. A file too large to carry in a script is refused rather than truncated, and a path this environment does not hold is refused exactly as one that never existed.

writeFile("greeting.txt", base64Encode("hello"));
const file = readFile("greeting.txt");
log("the file holds " + file.bytes + " bytes");

writeFile(path, contentBase64, options?) — pauses

Puts bytes into one of this environment’s file stores under a path, REPLACING whatever was there. What a run writes this way outlives it, which is what makes a file store the place for an artefact rather than a value.

• path (string) — Where to put it in the store. Writing the same path again replaces the file — an upload is not a create, so there is nothing to delete first.
• contentBase64 (string) — The contents as base64 text, exactly as writeBlob takes them. base64Encode makes it from text.
• options (object, optional) — { store, mime } — which file store to write to, and what the file is. Without a store it means this environment’s default one. A store that only takes uploads refuses a script’s write, and a store that is full refuses too unless its author asked it to make room.

Answers: { path, bytes } — where it landed and how big it is. Deliberately NOT a handle: a stored file is addressed by its path, and the handle-taking calls (sending, attaching) take one from writeBlob.

const stored = writeFile("reports/today.csv", base64Encode("sku,qty\nA-1,2\n"), { mime: "text/csv" });
log("wrote " + stored.bytes + " bytes to " + stored.path);

The rest of this pack

The page above is everything that is true only HERE. Ask for these parts by name for the rest:

• model — how a script is executed, the shape of its input, the rules enforced while it runs, and the mistakes that do not work here.
• functions-core — the core functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-encoding — the encoding functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-crypto — the crypto functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-text — the text functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-number — the numbers functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-structured — the structured data functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-document — the documents functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-markdown — the markdown functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-datetime — the date & time functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-email — the email functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-mapping — the mapping functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-dataset — the datasets functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-state — the state functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-pagination — the pagination functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-control — the run control functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• functions-functions — the config functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
• mistakes — the habits from general JS that do not work here — each with the exact error it produces and the shape to write instead.
• standard-library — every built-in the language itself provides — JSON, Math, Object, String, Array, Number, Map, Set, Date, RegExp and the bare globals — one line each, with an example and its answer.