Documents: fetch, create, batchUpdate, and helpers for the common
edits (read as text, append, insert, find and replace, fill a
template).
Scopes. get-document and read-text use documents.readonly;
everything else documents. drive.file works for documents the app
created or the user opened with it. Copying a template, moving,
sharing, exporting (PDF, Markdown, Word) and deleting a document are
Drive calls (google-drive).
Values
READ_TEXT_KEYS
READ_TEXT_KEYS: Vec [
"tabId"
]
Functions
append-text
fn (document-id: Str, text: Str): Map
fn (document-id: Str, text: Str, opts: Map): Map
Add text at the end of the document's body (first tab unless
opts.tabId). End text with a newline to start a new paragraph after
it. Scope: documents (or drive.file).
Example
::google::docs::documents/append-text("1AbCdEf", "Shipped the importer.\n")
// In a second tab
::google::docs::documents/append-text("1AbCdEf", "Notes\n", {tabId: "t.1"})
batch-update
fn (document-id: Str, requests: Vec): Map
fn (document-id: Str, requests: Vec, opts: Map): Map
POST /{id}:batchUpdate - apply a Vec of requests atomically, in
order: if one is invalid, none apply. Returns {documentId, replies, writeControl}. Each request sees the indexes left by the one before
it, so when you have several insertions or deletions, apply the
highest index first. ::google::docs::requests builds requests; any
request as a plain Map works too. Scope: documents (or
drive.file).
Example
::req ::google::docs::requests
// Fails instead of applying if someone edited the document first
::google::docs::documents/batch-update("1AbCdEf", [
::req/insert-text("Status\n", 1),
::req/heading(1, 8, 1)
], {writeControl: {requiredRevisionId: "AOV_f4..."}})
batch-update-body
fn (requests: Vec, opts: Map): Map
The batchUpdate body (pure): {requests} plus writeControl from
opts when set ({requiredRevisionId} fails the write if the document
changed; {targetRevisionId} merges with changes since).
Example
::google::docs::documents/batch-update-body([{deleteHeader: {headerId: "h1"}}], {writeControl: {requiredRevisionId: "r1"}})
// {requests: [{deleteHeader: {headerId: "h1"}}], writeControl: {requiredRevisionId: "r1"}}
::google::docs::documents/batch-update-body([], {}) // {requests: []}
create-document
fn (title: Str): Map
fn (title: Str, opts: Map): Map
POST /v1/documents - create a blank document. Returns the resource
with documentId. Only title applies: add content with
append-text or batch-update. It lands in the authenticated user's
My Drive root (move it with google-drive's move-file); a service
account without domain-wide delegation owns it alone, so share it
before anyone else can open it. Scope: documents (or drive.file).
Example
doc ::google::docs::documents/create-document("Weekly report")
doc.documentId
fill-template
fn (document-id: Str, values: Map): Map
fn (document-id: Str, values: Map, opts: Map): Map
Replace each {{key}} in the document with its value from values
(values are converted with Str; null values are skipped). The usual
template flow is google-drive's copy-file, then this on the copy.
Scope: documents (or drive.file).
Example
copy ::google::drive::files/copy-file("1TemplateId", {name: "Welcome Ada"})
::google::docs::documents/fill-template(copy.id, {name: "Ada", plan: "Pro"})
get-document
fn (document-id: Str): Map
fn (document-id: Str, opts: Map): Map
GET /{id} - the document: documentId, title, revisionId, body
(the first tab only), namedStyles, headers, footers. Pass
{includeTabsContent: true} to get every tab under tabs instead,
and suggestionsViewMode (e.g. "PREVIEW_WITHOUT_SUGGESTIONS") to
choose how suggestions render. Scope: documents.readonly.
Example
doc ::google::docs::documents/get-document("1AbCdEf")
doc.title
// Every tab, with suggestions accepted
all-tabs ::google::docs::documents/get-document("1AbCdEf", {
includeTabsContent: true,
suggestionsViewMode: "PREVIEW_SUGGESTIONS_ACCEPTED"
})
length(all-tabs.tabs)
get-params
fn (opts: Map): Map
The query parameters get-document sends (pure): includeTabsContent,
suggestionsViewMode, commentsViewMode, fields; only the ones you
set.
Example
::google::docs::documents/get-params({includeTabsContent: true, fields: "title"}) // {includeTabsContent: true, fields: "title"}
insert-text
fn (document-id: Str, text: Str, index: Int): Map
fn (document-id: Str, text: Str, index: Int, opts: Map): Map
Insert text at a body index (first tab unless opts.tabId). An index
must fall inside an existing paragraph; the document starts at 1. Scope:
documents (or drive.file).
Example
// At the very start of the body
::google::docs::documents/insert-text("1AbCdEf", "Draft\n", 1)
read-text
fn (document-id: Str): Str
fn (document-id: Str, opts: Map): Str
The document as plain text, with every tab's body in tab order. Pass
{tabId: "t.abc"} for one tab; an Err when that tab does not exist.
Scope: documents.readonly.
Example
::google::docs::documents/read-text("1AbCdEf")
// One tab
::google::docs::documents/read-text("1AbCdEf", {tabId: "t.0"})
replace-text
fn (document-id: Str, search: Str, replacement: Str): Map
fn (document-id: Str, search: Str, replacement: Str, opts: Map): Map
Replace every occurrence of search with replacement in every tab.
Case-sensitive unless {matchCase: false}; {searchByRegex: true}
treats search as a regular expression; {tabIds: [...]} limits the
tabs. The reply's replaceAllText.occurrencesChanged is the count.
Scope: documents (or drive.file).
Example
reply ::google::docs::documents/replace-text("1AbCdEf", "2025", "2026")
reply.replies[0].replaceAllText.occurrencesChanged
// Case-insensitive
::google::docs::documents/replace-text("1AbCdEf", "acme", "Hot", {matchCase: false})