Module paste 

Clipboard-style range operations — cutPaste, copyPaste and pasteData — via spreadsheets.batchUpdate (issue #1839, ADR-0083 §4).

Gate composition, per PasteType. cut-paste always resolves both SheetsWrite and SheetsStructure, whatever --paste-type asks for: the source is always cleared in full — values, formats and merges — regardless of what is pasted, and clearing formats/merges is SheetsStructure’s territory exactly as clearing values is SheetsWrite’s. copy-paste and paste-data resolve their gate from --paste-type alone (PasteType::writes_values/ PasteType::writes_presentation): a value-only type needs SheetsWrite alone, a presentation-only type SheetsStructure alone, and PASTE_NORMAL needs both, going through [target_gate::resolve_all] uniformly like pivot.rs’s union gate — this module has one gate-handling code path, not three.

Curated PasteType: four of the API’s seven variants — PASTE_NORMAL, PASTE_VALUES, PASTE_FORMULA, PASTE_FORMAT. See crate::drive::sheets::types::PasteType’s doc comment for the deferred three. paste-data is delimiter-form only; the API’s html alternative is not modelled anywhere on the wire type, so it cannot be sent.

Defaults, fixed by ADR-0083 §4 so this module doesn’t pick its own: --paste-type defaults to normal on cut-paste/copy-paste (so a bare invocation under a sheets-write-only grant is refused, naming the missing sheets-structure operation rather than silently pasting less than the user copied); paste-data defaults to values, since its delimited-text input carries no formats, merges or validation for normal to add.

--dry-run reports counts and A1 locations, never cell values (ADR-0083 §6 — the posture every verb but merge-cells holds to). The written extent is computed from the request plus the workbook’s structure alone — [copy_paste_extent] for copy-paste (the larger of source and destination anchored at the destination’s top-left, per the API’s own spill/repeat rule), the source’s own dimensions for cut-paste (a move, never a spill or repeat), and a locally-split upper bound for paste-data (ADR-0083 §6 names this an upper bound, not an exact prediction: the API’s row-separator convention for pasteData is undocumented). A bounded values.get then reports the non-blank cells within that extent; cut-paste makes a second, independent values.get over the source to report what gets cleared, rather than one values.batchGet — simpler than matching two results by their echoed range field for a preview that already makes one spreadsheets.get call per attempt. A presentation-only --paste-type format reads no values at all, the same as format-cells’ preview.

Grid-edge behaviour is verified live (#1937): the API grows the grid when a written extent runs past the sheet’s current rowCount/columnCount, for all three verbs — copyPaste/ pasteData were measured first (1000x26 → 1001x27), and cutPaste confirmed identically (a 10-row sheet grew to 11 rows to fit a 3-row-tall block landing on rows 8-10). This module still never prepends a structural request to grow the grid first (that would smuggle SheetsStructure into a SheetsWrite-gated batch) — there is nothing to smuggle now that growth is the verified, API-driven outcome — and a preview whose extent exceeds the sheet’s known dimensions carries a caveat naming that growth rather than an uncertainty. The preview read is a separate question from the written extent and is clipped to the sheet’s current grid ([grid_range::clamp_to_sheet]): values.get refuses a range past the edge outright, so reading the unclipped extent would turn the very case the caveat exists to report into an opaque failure. (cutPaste’s destination coordinate is a separate matter from the block it anchors: measured live, the API refuses outright — a plain 400, surfaced here as an ordinary Failed, with no special-casing — when the coordinate itself lies past the last existing row/column; only a coordinate inside the grid whose block then spills past the edge triggers growth. This crate performs no extent check of its own on the destination coordinate, so that refusal is entirely the API’s.)

Destination must be fully bounded for every verb, the same restriction merge-cells/insert-range place on their own ranges: an open-ended destination (A:A) has no fixed size to anchor the extent computation against, and guessing would risk the “preview that lies” ADR-0083 §6 refuses to ship. cut-paste’s and paste-data’s destination must additionally be a single cell — the API’s own GridCoordinate/GridCoordinate shape for those two requests, unlike copy-paste’s GridRange.

Structs

PasteChange

The substance of a WouldChange/Changed outcome.

PasteOptions

Per-call options.

PasteOutcome

The full outcome of one attempt.

Enums

PasteResult

What happened (or, under --dry-run, would happen).

PasteVerb

Which clipboard-style operation to perform.

Functions

describe_lines

Renders one PasteOutcome as human-readable lines, for both --dry-run and a real run.

paste

Runs one clipboard-style mutation, logging every attempt that isn’t a dry run.