Docs / Files, mail, documents

a9script authoring pack — documents functions

The documents 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.

createPdf(document) — pauses

Draws a PDF and answers it as text you can file or send. You say what the document HOLDS — a list of blocks: headings, paragraphs, lists, tables, rules, gaps and page breaks — and how it is laid out is decided for you: text wraps, pages break where they must, and a table repeats its column names at the top of every page it runs onto. A document is set in the standard PDF fonts, which draw the Western alphabet; a character outside it — Greek, Cyrillic, Chinese, an emoji — is refused by name rather than drawn as something else.

• document (object) — { title, blocks }. blocks is the list, drawn in the order you write it, and every block names its kind: heading (with level 1, 2 or 3, and text), text (with text), list (with items, and ordered to number them), table (with headers and rows), divider, spacer (with height in points) and pageBreak. Wherever text is expected you may also pass a number or true/false, and nothing at all writes an empty line — but a shape is refused, because there is no reading of it a person would want. title is the name the document carries: a reader meets it in their PDF viewer’s title bar, never on the page, so a title to be SEEN is a heading block. Any other key, any unknown kind, and any row that does not fit its headers, is refused naming the block it is in.

Answers: The document as base64 text — the same shape writeBlob takes, so a report can be built and filed in two lines. Building the same document twice answers exactly the same text: nothing about the moment it was built goes into it, which is also why a date a reader needs belongs in a block they can see.

const invoice = createPdf({
  title: "Invoice 4711",
  blocks: [
    { kind: "heading", level: 1, text: "Invoice 4711" },
    { kind: "text", text: "Thank you for your order." },
    { kind: "table", headers: ["item", "amount"], rows: [["Widget", 12.5], ["Delivery", 4]] },
    { kind: "divider" },
    { kind: "text", text: "Total: 16.50" }
  ]
});
log("the invoice is " + invoice.length + " characters of base64");

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-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-blob — the files 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.