From 7882463924a79a3a3b0808a76e2ce64e182a1410 Mon Sep 17 00:00:00 2001 From: Andreas Arvidsson Date: Sun, 30 Aug 2026 03:34:17 +0200 Subject: [PATCH] Move the paired delimiters reference to its own page --- .../app-web-docs/sidebarItemsGenerator.ts | 8 +- packages/app-web-docs/src/docs/user/README.md | 21 +--- .../actions/rewrapWithPairedDelimiter.mdx | 2 +- .../user/actions/wrapWithPairedDelimiter.mdx | 2 +- .../src/docs/user/paired-delimiters.md | 16 ++++ .../src/references/actionReferences.ts | 2 +- .../references/pairedDelimiterReferences.ts | 82 +++++++++++++++- packages/tool-meta-updater/src/metaUpdater.ts | 6 ++ .../src/updatePairedDelimitersMd.ts | 95 +++++++++++++++++++ 9 files changed, 210 insertions(+), 24 deletions(-) create mode 100644 packages/app-web-docs/src/docs/user/paired-delimiters.md create mode 100644 packages/tool-meta-updater/src/updatePairedDelimitersMd.ts diff --git a/packages/app-web-docs/sidebarItemsGenerator.ts b/packages/app-web-docs/sidebarItemsGenerator.ts index 3878d5c78b..8415146947 100644 --- a/packages/app-web-docs/sidebarItemsGenerator.ts +++ b/packages/app-web-docs/sidebarItemsGenerator.ts @@ -16,7 +16,13 @@ const items: (Group | string)[] = [ }, { label: "Reference", - items: ["Actions", "Modifiers", "Scopes", "Destinations"], + items: [ + "Actions", + "Modifiers", + "Scopes", + "Destinations", + "Paired delimiters", + ], }, "Supported languages", { diff --git a/packages/app-web-docs/src/docs/user/README.md b/packages/app-web-docs/src/docs/user/README.md index b84262e1b6..268ac482c9 100644 --- a/packages/app-web-docs/src/docs/user/README.md +++ b/packages/app-web-docs/src/docs/user/README.md @@ -446,7 +446,7 @@ Cursorless has support for expanding the selection to the nearest containing pai - `"take round"` expands selection to include containing parentheses `(` and `)` - `"take curly"` expands selection to include containing braces `{` and `}` -- `"take box"` expands selection to include containing brackets `[` and `]`. See [paired delimiters](#paired-delimiters) for other possible surrounding pairs. +- `"take box"` expands selection to include containing brackets `[` and `]`. See [paired delimiters](./paired-delimiters.md) for other possible surrounding pairs. - `"take inside round"` is the same as `"take round"`, but excludes the parentheses themselves - `"take bounds round"` selects only the parentheses - `"take pair"` expands to include the nearest containing pair of any kind @@ -454,7 +454,7 @@ Cursorless has support for expanding the selection to the nearest containing pai - `"take inside"` selects until the nearest containing paired delimiters of any kind, but doesn't include the delimiters themselves - `"take round air"` selects the parentheses containing the token with a hat over the `a`. -See [paired delimiters](#paired-delimiters) for a list of possible surrounding pairs. +See [paired delimiters](./paired-delimiters.md) for a list of possible surrounding pairs. ###### Ambiguous delimiters (`"`, `'`, `` ` ``, etc) @@ -538,20 +538,3 @@ Selects both the token containing letter 'a' with a blue hat AND the token conta Every Cursorless command combines an action with a target. The action determines what happens to the target. For example, `"chuck air"` removes the target, while `"take air"` selects it. See the [action reference](./actions/README.md) for the complete list of actions, syntax, behavior, and examples. - -## Paired delimiters - -| Default spoken form | Delimiter name | Symbol inserted before target | Symbol inserted after target | Is wrapper? | Is selectable? | -| ------------------- | --------------------- | ----------------------------- | ---------------------------- | ----------- | -------------- | -| `"curly"` | curly brackets | `{` | `}` | ✅ | ✅ | -| `"diamond"` | angle brackets | `<` | `>` | ✅ | ✅ | -| `"escaped quad"` | escaped double quotes | `\\"` | `\\"` | ✅ | ✅ | -| `"escaped round"` | escaped parentheses | `\\(` | `\\)` | ✅ | ✅ | -| `"escaped twin"` | escaped single quotes | `\\'` | `\\'` | ✅ | ✅ | -| `"pair"` | any | N/A | N/A | ❌ | ✅ | -| `"quad"` | double quotes | `"` | `"` | ✅ | ✅ | -| `"round"` | parentheses | `(` | `)` | ✅ | ✅ | -| `"skis"` | backtick quotes | `` ` `` | `` ` `` | ✅ | ✅ | -| `"box"` | square brackets | `[` | `]` | ✅ | ✅ | -| `"twin"` | single quotes | `'` | `'` | ✅ | ✅ | -| `"void"` | space | ` ` | ` ` | ✅ | ❌ | diff --git a/packages/app-web-docs/src/docs/user/actions/rewrapWithPairedDelimiter.mdx b/packages/app-web-docs/src/docs/user/actions/rewrapWithPairedDelimiter.mdx index 8e4df7cef0..05b4731282 100644 --- a/packages/app-web-docs/src/docs/user/actions/rewrapWithPairedDelimiter.mdx +++ b/packages/app-web-docs/src/docs/user/actions/rewrapWithPairedDelimiter.mdx @@ -4,7 +4,7 @@ sidebar_label: Repack # Repack (Rewrap with paired delimiter) -See [paired delimiters](../README.md#paired-delimiters) for the available pairs. +See [paired delimiters](../paired-delimiters.md) for the available pairs. Cursorless ID: `rewrapWithPairedDelimiter` diff --git a/packages/app-web-docs/src/docs/user/actions/wrapWithPairedDelimiter.mdx b/packages/app-web-docs/src/docs/user/actions/wrapWithPairedDelimiter.mdx index 5fd7637479..1fa985cd1d 100644 --- a/packages/app-web-docs/src/docs/user/actions/wrapWithPairedDelimiter.mdx +++ b/packages/app-web-docs/src/docs/user/actions/wrapWithPairedDelimiter.mdx @@ -4,7 +4,7 @@ sidebar_label: Wrap # Wrap (Wrap with paired delimiter/snippet) -See [paired delimiters](../README.md#paired-delimiters) for the available pairs. +See [paired delimiters](../paired-delimiters.md) for the available pairs. Cursorless ID: `wrapWithPairedDelimiter` diff --git a/packages/app-web-docs/src/docs/user/paired-delimiters.md b/packages/app-web-docs/src/docs/user/paired-delimiters.md new file mode 100644 index 0000000000..141507d33d --- /dev/null +++ b/packages/app-web-docs/src/docs/user/paired-delimiters.md @@ -0,0 +1,16 @@ +# Paired delimiters + +| Default spoken form | Delimiter name | Symbol inserted before target | Symbol inserted after target | Is wrapper? | Is selectable? | +| ------------------- | --------------------- | ----------------------------- | ---------------------------- | ----------- | -------------- | +| `"quad"` | double quotes | `"` | `"` | ✅ | ✅ | +| `"twin"` | single quotes | `'` | `'` | ✅ | ✅ | +| `"skis"` | backtick quotes | `` ` `` | `` ` `` | ✅ | ✅ | +| `"round"` | parentheses | `(` | `)` | ✅ | ✅ | +| `"curly"` | curly brackets | `{` | `}` | ✅ | ✅ | +| `"box"` | square brackets | `[` | `]` | ✅ | ✅ | +| `"diamond"` | angle brackets | `<` | `>` | ✅ | ✅ | +| `"escaped quad"` | escaped double quotes | `\\"` | `\\"` | ✅ | ✅ | +| `"escaped twin"` | escaped single quotes | `\\'` | `\\'` | ✅ | ✅ | +| `"escaped round"` | escaped parentheses | `\\(` | `\\)` | ✅ | ✅ | +| `"void"` | space | ` ` | ` ` | ✅ | ❌ | +| `"pair"` | any | N/A | N/A | ❌ | ✅ | diff --git a/packages/lib-common/src/references/actionReferences.ts b/packages/lib-common/src/references/actionReferences.ts index 88940efbc4..71cd05de7a 100644 --- a/packages/lib-common/src/references/actionReferences.ts +++ b/packages/lib-common/src/references/actionReferences.ts @@ -57,7 +57,7 @@ const SCOPE_INSERTION_DESCRIPTION = const REORDER_DESCRIPTION = "This action changes the order of multiple target contents. The targets can come from a list or range target, or from existing multiple selections."; const PAIRED_DELIMITER_DESCRIPTION = - "See [paired delimiters](../README.md#paired-delimiters) for the available pairs."; + "See [paired delimiters](../paired-delimiters.md) for the available pairs."; type TalonSideActionType = "applyFormatter" | "nextHomophone"; diff --git a/packages/lib-common/src/references/pairedDelimiterReferences.ts b/packages/lib-common/src/references/pairedDelimiterReferences.ts index 048709f552..82f6e1a2f0 100644 --- a/packages/lib-common/src/references/pairedDelimiterReferences.ts +++ b/packages/lib-common/src/references/pairedDelimiterReferences.ts @@ -1,67 +1,147 @@ import type { SpeakableSurroundingPairName } from "../types/SpokenFormType"; import type { SpokenFormReference } from "./ReferenceEntry"; +export interface PairedDelimiterReference extends SpokenFormReference { + name: string; + defaultSpokenForm: string; + delimiters: readonly [string, string] | null; + selectable: boolean; + referenceIndex: number | null; +} + export const pairedDelimiterReferences = { curlyBrackets: { + name: "curly brackets", defaultSpokenForm: "curly", + delimiters: ["{", "}"], + selectable: true, + referenceIndex: 4, }, angleBrackets: { + name: "angle brackets", defaultSpokenForm: "diamond", + delimiters: ["<", ">"], + selectable: true, + referenceIndex: 6, }, escapedDoubleQuotes: { + name: "escaped double quotes", defaultSpokenForm: "escaped quad", + delimiters: [String.raw`\"`, String.raw`\"`], + selectable: true, + referenceIndex: 7, }, escapedSingleQuotes: { + name: "escaped single quotes", defaultSpokenForm: "escaped twin", + delimiters: [String.raw`\'`, String.raw`\'`], + selectable: true, + referenceIndex: 8, }, escapedParentheses: { + name: "escaped parentheses", defaultSpokenForm: "escaped round", + delimiters: [String.raw`\(`, String.raw`\)`], + selectable: true, + referenceIndex: 9, }, escapedSquareBrackets: { + name: "escaped square brackets", defaultSpokenForm: "escaped box", + delimiters: [String.raw`\[`, String.raw`\]`], + selectable: true, + referenceIndex: null, }, doubleQuotes: { + name: "double quotes", defaultSpokenForm: "quad", + delimiters: ['"', '"'], + selectable: true, + referenceIndex: 0, }, parentheses: { + name: "parentheses", defaultSpokenForm: "round", + delimiters: ["(", ")"], + selectable: true, + referenceIndex: 3, }, backtickQuotes: { + name: "backtick quotes", defaultSpokenForm: "skis", + delimiters: ["`", "`"], + selectable: true, + referenceIndex: 2, }, squareBrackets: { + name: "square brackets", defaultSpokenForm: "box", + delimiters: ["[", "]"], + selectable: true, + referenceIndex: 5, }, singleQuotes: { + name: "single quotes", defaultSpokenForm: "twin", + delimiters: ["'", "'"], + selectable: true, + referenceIndex: 1, }, tripleDoubleQuotes: { + name: "triple double quotes", defaultSpokenForm: "triple quad", + delimiters: ['"""', '"""'], + selectable: true, + referenceIndex: null, disabledByDefault: true, private: true, }, tripleSingleQuotes: { + name: "triple single quotes", defaultSpokenForm: "triple twin", + delimiters: ["'''", "'''"], + selectable: true, + referenceIndex: null, disabledByDefault: true, private: true, }, tripleBacktickQuotes: { + name: "triple backtick quotes", defaultSpokenForm: "triple skis", + delimiters: ["```", "```"], + selectable: true, + referenceIndex: null, disabledByDefault: true, private: true, }, any: { + name: "any", defaultSpokenForm: "pair", + delimiters: null, + selectable: true, + referenceIndex: 11, }, string: { + name: "string", defaultSpokenForm: "string", + delimiters: null, + selectable: true, + referenceIndex: null, }, whitespace: { + name: "space", defaultSpokenForm: "void", + delimiters: [" ", " "], + selectable: false, + referenceIndex: 10, }, collectionBoundary: { + name: "collection boundary", defaultSpokenForm: "collection boundary", + delimiters: null, + selectable: true, + referenceIndex: null, disabledByDefault: true, private: true, }, -} satisfies Record; +} satisfies Record; diff --git a/packages/tool-meta-updater/src/metaUpdater.ts b/packages/tool-meta-updater/src/metaUpdater.ts index 953e34e80d..5fcccca59f 100644 --- a/packages/tool-meta-updater/src/metaUpdater.ts +++ b/packages/tool-meta-updater/src/metaUpdater.ts @@ -11,6 +11,7 @@ import { languageScopeSupport, modifierReferenceGroups, modifierReferences, + pairedDelimiterReferences, scopeReferenceGroups, scopeReferences, } from "@cursorless/lib-common"; @@ -18,6 +19,7 @@ import type { Context } from "./Context"; import { textFormat } from "./textFormat"; import { updateLanguageMdx } from "./updateLanguageMdx"; import { updatePackageJson } from "./updatePackageJson"; +import { updatePairedDelimitersMd } from "./updatePairedDelimitersMd"; import { updatePrivateScopeMdx } from "./updatePrivateScopeMdx"; import { updateReferenceMdx } from "./updateReferenceMdx"; import { updateReferenceReadmeMd } from "./updateReferenceReadmeMd"; @@ -56,6 +58,10 @@ export const updater = async (workspaceDir: string) => { updateLanguageMdx.bind(null, languageId), ]), ), + [`${userDir}/paired-delimiters.md`]: updatePairedDelimitersMd.bind( + null, + pairedDelimiterReferences, + ), [`${userDir}/actions/README.md`]: updateReferenceReadmeMd.bind( null, "Actions", diff --git a/packages/tool-meta-updater/src/updatePairedDelimitersMd.ts b/packages/tool-meta-updater/src/updatePairedDelimitersMd.ts new file mode 100644 index 0000000000..b1128b32f2 --- /dev/null +++ b/packages/tool-meta-updater/src/updatePairedDelimitersMd.ts @@ -0,0 +1,95 @@ +import type { FormatPluginFnOptions } from "@pnpm/meta-updater"; +import type { PairedDelimiterReference } from "@cursorless/lib-common"; +import { DISABLED_BY_DEFAULT } from "./util/constants"; + +const HEADERS = [ + "Default spoken form", + "Delimiter name", + "Symbol inserted before target", + "Symbol inserted after target", + "Is wrapper?", + "Is selectable?", +] as const; + +export function updatePairedDelimitersMd( + entries: Record, + actual: string | null, + options: FormatPluginFnOptions, +): string | null { + if (options.manifest.name !== "@cursorless/app-web-docs") { + return null; + } + + const rows = Object.values(entries) + .filter( + (entry): entry is PairedDelimiterReference & { referenceIndex: number } => + !entry.private && entry.referenceIndex != null, + ) + .toSorted((a, b) => a.referenceIndex - b.referenceIndex) + .map((entry) => { + const [before, after] = entry.delimiters ?? [null, null]; + const spokenForm = `${code(`"${entry.defaultSpokenForm}"`)}${entry.disabledByDefault ? ` (${DISABLED_BY_DEFAULT})` : ""}`; + + return [ + spokenForm, + entry.name, + before == null ? "N/A" : code(formatDelimiter(before)), + after == null ? "N/A" : code(formatDelimiter(after)), + booleanIcon(entry.delimiters != null), + booleanIcon(entry.selectable), + ]; + }); + + return ["# Paired delimiters", "", ...formatTable(HEADERS, rows), ""].join( + "\n", + ); +} + +function code(value: string): string { + if (value.includes("`")) { + return `\`\` ${value} \`\``; + } + + return `\`${value}\``; +} + +function formatDelimiter(value: string): string { + return value.replaceAll("\\", String.raw`\\`); +} + +function booleanIcon(value: boolean): string { + return value ? "✅" : "❌"; +} + +function formatTable( + headers: readonly string[], + rows: readonly string[][], +): string[] { + const columnWidths = headers.map((header, index) => + Math.max( + displayWidth(header), + ...rows.map((row) => displayWidth(row[index])), + ), + ); + const formatRow = (row: readonly string[]) => + `| ${row + .map( + (cell, index) => + `${cell}${" ".repeat(columnWidths[index] - displayWidth(cell))}`, + ) + .join(" | ")} |`; + + return [ + formatRow(headers), + formatRow(columnWidths.map((width) => "-".repeat(width))), + ...rows.map(formatRow), + ]; +} + +function displayWidth(value: string): number { + return [...value].reduce( + (width, character) => + width + (character === "✅" || character === "❌" ? 2 : 1), + 0, + ); +}