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 for batchUpdate requests
  • ::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"
Context Vars: google.docs.api-root

append-text alias 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 alias 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 alias 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 alias 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 alias 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 alias 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 alias 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"