Pure builders for documents.batchUpdate requests. Each returns one request Map; pass a Vec of them to ::google::docs::documents/batch-update, which applies them atomically in order.

Indexes count UTF-16 code units from 1 at the start of the body. Ranges are start inclusive to end exclusive. Every builder's opts takes tabId and segmentId (a header, footer or footnote) to address something other than the first tab's body.

::req ::google::docs::requests

::google::docs::documents/batch-update("1AbCdEf", [
  ::req/insert-text("Status\nAll green\n", 1),
  ::req/heading(1, 8, 1),
  ::req/bold(8, 17)
])

Values

BULLET_DISC

BULLET_DISC: Str "BULLET_DISC_CIRCLE_SQUARE"

NUMBERED

NUMBERED: Str "NUMBERED_DECIMAL_ALPHA_ROMAN"

Functions

align

fn (start: Int, end: Int, alignment: Str): Map
fn (start: Int, end: Int, alignment: Str, opts: Map): Map

Set paragraph alignment: START, CENTER, END or JUSTIFIED.

Example

::google::docs::requests/align(1, 8, "CENTER").updateParagraphStyle.paragraphStyle  // {alignment: "CENTER"}

append-image

fn (uri: Str): Map
fn (uri: Str, opts: Map): Map

insertInlineImage at the end of the body or segment.

Example

::google::docs::requests/append-image("https://hot.dev/logo.png").insertInlineImage.uri  // "https://hot.dev/logo.png"

append-page-break

fn (): Map
fn (opts: Map): Map

insertPageBreak at the end of the body.

Example

::google::docs::requests/append-page-break()  // {insertPageBreak: {endOfSegmentLocation: {}}}

append-table

fn (rows: Int, columns: Int): Map
fn (rows: Int, columns: Int, opts: Map): Map

insertTable at the end of the body or segment.

Example

::google::docs::requests/append-table(2, 3)
// {insertTable: {rows: 2, columns: 3, endOfSegmentLocation: {}}}

append-text

fn (text: Str): Map
fn (text: Str, opts: Map): Map

insertText at the end of the body or segment.

Example

::google::docs::requests/append-text("Hello\n")
// {insertText: {text: "Hello\n", endOfSegmentLocation: {}}}

bold

fn (start: Int, end: Int): Map
fn (start: Int, end: Int, opts: Map): Map

Make a range bold.

Example

::google::docs::requests/bold(1, 8).updateTextStyle.textStyle  // {bold: true}

bullets

fn (start: Int, end: Int): Map
fn (start: Int, end: Int, preset: Str): Map
fn (start: Int, end: Int, preset: Str, opts: Map): Map

createParagraphBullets on the paragraphs in a range. preset defaults to BULLET_DISC_CIRCLE_SQUARE; NUMBERED holds the usual numbered preset.

Example

::google::docs::requests/bullets(1, 20).createParagraphBullets.bulletPreset  // "BULLET_DISC_CIRCLE_SQUARE"
::google::docs::requests/bullets(1, 20, ::google::docs::requests/NUMBERED).createParagraphBullets.bulletPreset  // "NUMBERED_DECIMAL_ALPHA_ROMAN"
fn (): Map

createFooter on the default section. The reply's createFooter.footerId is the segmentId for adding text to it.

Example

::google::docs::requests/create-footer()  // {createFooter: {type: "DEFAULT"}}

create-header

fn (): Map

createHeader on the default section. The reply's createHeader.headerId is the segmentId for adding text to it.

Example

::google::docs::requests/create-header()  // {createHeader: {type: "DEFAULT"}}

create-named-range

fn (name: Str, start: Int, end: Int): Map
fn (name: Str, start: Int, end: Int, opts: Map): Map

createNamedRange: a label that tracks its text as the document changes.

Example

::google::docs::requests/create-named-range("summary", 1, 8)
// {createNamedRange: {name: "summary", range: {startIndex: 1, endIndex: 8}}}

delete-bullets

fn (start: Int, end: Int): Map
fn (start: Int, end: Int, opts: Map): Map

deleteParagraphBullets on the paragraphs in a range.

Example

::google::docs::requests/delete-bullets(1, 20)
// {deleteParagraphBullets: {range: {startIndex: 1, endIndex: 20}}}

delete-named-range

fn (name: Str): Map
fn (name: Str, opts: Map): Map

deleteNamedRange for every range with this name, in every tab unless opts.tabIds.

Example

::google::docs::requests/delete-named-range("summary")  // {deleteNamedRange: {name: "summary"}}

delete-range

fn (start: Int, end: Int): Map
fn (start: Int, end: Int, opts: Map): Map

deleteContentRange. A range cannot include a segment's final newline or split a table or surrogate pair.

Example

::google::docs::requests/delete-range(1, 8)
// {deleteContentRange: {range: {startIndex: 1, endIndex: 8}}}

delete-table-column

fn (table-start: Int, column: Int): Map
fn (table-start: Int, column: Int, opts: Map): Map

deleteTableColumn.

Example

::google::docs::requests/delete-table-column(2, 1).deleteTableColumn.tableCellLocation.columnIndex  // 1

delete-table-row

fn (table-start: Int, row: Int): Map
fn (table-start: Int, row: Int, opts: Map): Map

deleteTableRow.

Example

::google::docs::requests/delete-table-row(2, 1).deleteTableRow.tableCellLocation.rowIndex  // 1

end-of-segment

fn (): Map
fn (opts: Map): Map

An EndOfSegmentLocation: the end of the body, or of opts.segmentId, in the first tab or opts.tabId.

Example

::google::docs::requests/end-of-segment()  // {}
::google::docs::requests/end-of-segment({segmentId: "kix.header"})  // {segmentId: "kix.header"}

field-mask

fn (style: Map): Str

A style's top-level keys as a field mask, so only the fields you pass change.

Example

::google::docs::requests/field-mask({bold: true, italic: false})  // "bold,italic"

fill-template

fn (values: Map): Vec
fn (values: Map, opts: Map): Vec

One replaceAllText per entry of values, replacing {{key}} with the value as text. Null values are skipped.

Example

reqs ::google::docs::requests/fill-template({name: "Ada"})
reqs[0].replaceAllText.containsText.text  // "{{name}}"
reqs[0].replaceAllText.replaceText  // "Ada"

font-size

fn (start: Int, end: Int, size: Int | Dec): Map
fn (start: Int, end: Int, size: Int | Dec, opts: Map): Map

Set a range's font size in points.

Example

::google::docs::requests/font-size(1, 8, 14).updateTextStyle.textStyle
// {fontSize: {magnitude: 14, unit: "PT"}}

heading

fn (start: Int, end: Int, level: Int): Map
fn (start: Int, end: Int, level: Int, opts: Map): Map

Make the paragraphs in a range a heading of level 1 to 6; an Err for any other level.

Example

::google::docs::requests/heading(1, 8, 2).updateParagraphStyle.paragraphStyle
// {namedStyleType: "HEADING_2"}

hex-color

fn (hex: Str): Map

A Docs RgbColor from a hex string ("#1a73e8" or "1a73e8"); an Err for anything else.

Example

::google::docs::requests/hex-color("#ff0000")  // {red: 1.0, green: 0.0, blue: 0.0}

insert-image

fn (uri: Str, index: Int): Map
fn (uri: Str, index: Int, opts: Map): Map

insertInlineImage from a public URL (PNG, JPEG or GIF under 50 MB). opts.width and opts.height are in points.

Example

::google::docs::requests/insert-image("https://hot.dev/logo.png", 1, {width: 120})
// {insertInlineImage: {uri: "https://hot.dev/logo.png", location: {index: 1}, objectSize: {width: {magnitude: 120, unit: "PT"}}}}

insert-page-break

fn (index: Int): Map
fn (index: Int, opts: Map): Map

insertPageBreak at an index in the body.

Example

::google::docs::requests/insert-page-break(12)  // {insertPageBreak: {location: {index: 12}}}

insert-table

fn (rows: Int, columns: Int, index: Int): Map
fn (rows: Int, columns: Int, index: Int, opts: Map): Map

insertTable at an index. Docs adds a newline before the table, so its start index is add(index, 1).

Example

::google::docs::requests/insert-table(2, 3, 1)
// {insertTable: {rows: 2, columns: 3, location: {index: 1}}}

insert-table-column

fn (table-start: Int, column: Int, right: Bool): Map
fn (table-start: Int, column: Int, right: Bool, opts: Map): Map

insertTableColumn to the right of (or, with right false, to the left of) a column.

Example

::google::docs::requests/insert-table-column(2, 0, false).insertTableColumn.insertRight  // false

insert-table-row

fn (table-start: Int, row: Int, below: Bool): Map
fn (table-start: Int, row: Int, below: Bool, opts: Map): Map

insertTableRow below (or, with below false, above) a row.

Example

::google::docs::requests/insert-table-row(2, 0, true).insertTableRow.insertBelow  // true

insert-text

fn (text: Str, index: Int): Map
fn (text: Str, index: Int, opts: Map): Map

insertText at a UTF-16 index, which must fall inside an existing paragraph.

Example

::google::docs::requests/insert-text("Hello", 1)
// {insertText: {text: "Hello", location: {index: 1}}}

italic

fn (start: Int, end: Int): Map
fn (start: Int, end: Int, opts: Map): Map

Make a range italic.

Example

::google::docs::requests/italic(1, 8).updateTextStyle.textStyle  // {italic: true}
fn (start: Int, end: Int, url: Str): Map
fn (start: Int, end: Int, url: Str, opts: Map): Map

Link a range to url.

Example

::google::docs::requests/link(1, 8, "https://hot.dev").updateTextStyle.textStyle
// {link: {url: "https://hot.dev"}}

location

fn (index: Int): Map
fn (index: Int, opts: Map): Map

A Location at a UTF-16 index.

Example

::google::docs::requests/location(5)  // {index: 5}
::google::docs::requests/location(5, {tabId: "t.1"})  // {index: 5, tabId: "t.1"}

named-style

fn (start: Int, end: Int, name: Str): Map
fn (start: Int, end: Int, name: Str, opts: Map): Map

Apply a named style: NORMAL_TEXT, TITLE, SUBTITLE or HEADING_1 to HEADING_6.

Example

::google::docs::requests/named-style(1, 8, "TITLE").updateParagraphStyle.paragraphStyle
// {namedStyleType: "TITLE"}

optional-color

fn (color: Map): Map

An OptionalColor wrapping an RgbColor, for foregroundColor and backgroundColor.

Example

::google::docs::requests/optional-color(::google::docs::requests/rgb(255, 0, 0))
// {color: {rgbColor: {red: 1.0, green: 0.0, blue: 0.0}}}

paragraph-style

fn (start: Int, end: Int, style: Map): Map
fn (start: Int, end: Int, style: Map, opts: Map): Map

updateParagraphStyle with any ParagraphStyle (namedStyleType, alignment, lineSpacing, spaceAbove, indentStart, ...) on every paragraph the range touches. The field mask is the keys you pass.

Example

::google::docs::requests/paragraph-style(1, 8, {alignment: "CENTER"}).updateParagraphStyle.fields  // "alignment"

points

fn (value: Int | Dec): Map

A Dimension in points.

Example

::google::docs::requests/points(12)  // {magnitude: 12, unit: "PT"}

replace-all-text

fn (search: Str, replacement: Str): Map
fn (search: Str, replacement: Str, opts: Map): Map

replaceAllText: every occurrence, in every tab unless opts.tabIds. Case-sensitive unless opts.matchCase is false; opts.searchByRegex treats search as a regular expression.

Example

req ::google::docs::requests/replace-all-text("2025", "2026", {matchCase: false})
req.replaceAllText.containsText  // {text: "2025", matchCase: false}

replace-named-range

fn (name: Str, text: Str): Map
fn (name: Str, text: Str, opts: Map): Map

replaceNamedRangeContent: replace the text of the named range, in every tab unless opts.tabIds.

Example

::google::docs::requests/replace-named-range("summary", "All green")
// {replaceNamedRangeContent: {namedRangeName: "summary", text: "All green"}}

rgb

fn (red: Int, green: Int, blue: Int): Map

A Docs RgbColor from 0-255 channels.

Example

::google::docs::requests/rgb(255, 0, 0)  // {red: 1.0, green: 0.0, blue: 0.0}

table-cell

fn (table-start: Int, row: Int, column: Int): Map
fn (table-start: Int, row: Int, column: Int, opts: Map): Map

A TableCellLocation: 0-based row and column of the table starting at table-start (see ::google::docs::content/tables).

Example

::google::docs::requests/table-cell(2, 0, 1)
// {tableStartLocation: {index: 2}, rowIndex: 0, columnIndex: 1}

text-color

fn (start: Int, end: Int, color: Map): Map
fn (start: Int, end: Int, color: Map, opts: Map): Map

Set a range's text color from an RgbColor (rgb or hex-color).

Example

::google::docs::requests/text-color(1, 8, ::google::docs::requests/hex-color("#ff0000")).updateTextStyle.fields  // "foregroundColor"

text-range

fn (start: Int, end: Int): Map
fn (start: Int, end: Int, opts: Map): Map

A Range: start inclusive to end exclusive.

Example

::google::docs::requests/text-range(1, 8)  // {startIndex: 1, endIndex: 8}

text-style

fn (start: Int, end: Int, style: Map): Map
fn (start: Int, end: Int, style: Map, opts: Map): Map

updateTextStyle with any TextStyle (bold, italic, underline, strikethrough, fontSize, foregroundColor, backgroundColor, link, weightedFontFamily, ...). The field mask is the keys you pass.

Example

::google::docs::requests/text-style(1, 8, {bold: true, underline: true}).updateTextStyle.fields  // "bold,underline"