Docs / Language & functions

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.

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);