Google Docs API v1 bindings: read a document as plain text, paragraphs,
headings and tables (across every tab), create documents, fill
{{placeholder}} templates, and run batchUpdate with builders for
text, styles, bullets, tables, images and named ranges. Credentials
and scopes come from google-core.
Namespaces
::google::docs::documents- get, create,batch-update,read-text,append-text,insert-text,replace-text,fill-template::google::docs::requests- pure builders forbatchUpdaterequests::google::docs::content- pure readers over a fetched document: tabs, text, paragraphs, headings, tables, end index
Every function has an options arity taking an opts Map. Docs
parameters use the API's own names (includeTabsContent,
suggestionsViewMode, fields, writeControl); credential keys
(token, refresh-token, service-account, subject, scopes,
retry) are handled by google-core and override context for that
call.
Quick start
::docs ::google::docs::documents
doc ::docs/create-document("Weekly report")
::docs/append-text(doc.documentId, "Shipped the importer.\n")
::docs/read-text(doc.documentId)
Values
API_ROOT
API_ROOT: Str "https://docs.googleapis.com"
FILE_SCOPE
FILE_SCOPE: Str "https://www.googleapis.com/auth/drive.file"
READ_SCOPE
READ_SCOPE: Str "https://www.googleapis.com/auth/documents.readonly"
SCOPE
SCOPE: Str "https://www.googleapis.com/auth/documents"
Functions
api-root
fn (): Str
The API root, https://docs.googleapis.com unless the
google.docs.api-root context variable points at a proxy or emulator.
Example
::google::docs/api-root() // "https://docs.googleapis.com"
google.docs.api-root
append-text of ::google::docs::documents/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 of ::google::docs::documents/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..."}})
compact
fn (body: Map): Map
Drop null values from a request body (Docs bodies never carry JSON null for unset fields).
Example
::google::docs/compact({title: "Report", fields: null}) // {title: "Report"}
create-document of ::google::docs::documents/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
creds
fn (opts: Map): Map
The google-core part of opts (credentials, scopes, retry), passed
through to ::google::api.
Example
::google::docs/creds({token: "ya29.abc", fields: "title"}) // {token: "ya29.abc"}
encode-id
fn (id: Str): Str
URL-encode a document id for a path segment.
Example
::google::docs/encode-id("a b") // "a%20b"
fill-template of ::google::docs::documents/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 of ::google::docs::documents/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)
json
fn (scope: Str, method: Str, full-url: Str, body: Any, opts: Map): Any
::google::api/json with this package's conventions: credential opts
and a JSON (or empty) body.
Example
// Package internals: prefer the functions in ::google::docs::documents
::google::docs/json(::google::docs/READ_SCOPE, "GET", ::google::docs/url("/abc"), "", {})
query-params
fn (defaults: Map, opts: Map): Map
fn (defaults: Map, opts: Map, local-keys: Vec): Map
Build a call's query parameters: defaults, overridden by the Docs
parameters in opts (credential keys and the function's own
local-keys are removed), with nulls dropped. Pass a key as null in
opts to drop a default.
Example
::google::docs/query-params({fields: "title"}, {suggestionsViewMode: "PREVIEW_SUGGESTIONS_ACCEPTED"})
// {fields: "title", suggestionsViewMode: "PREVIEW_SUGGESTIONS_ACCEPTED"}
// Null in opts drops a default
::google::docs/query-params({fields: "title"}, {fields: null}) // {}
read-text of ::google::docs::documents/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 of ::google::docs::documents/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})
url
fn (path: Str): Str
fn (path: Str, params: Map): Str
A Docs v1 URL: /v1/documents + path, with params as a query string
when given.
Example
::google::docs/url("/abc:batchUpdate")
// "https://docs.googleapis.com/v1/documents/abc:batchUpdate"