Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion packages/app-web-docs/sidebarItemsGenerator.ts
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,13 @@ const items: (Group | string)[] = [
},
{
label: "Reference",
items: ["Actions", "Modifiers", "Scopes", "Destinations"],
items: [
"Actions",
"Modifiers",
"Scopes",
"Destinations",
"Paired delimiters",
],
},
"Supported languages",
{
Expand Down
21 changes: 2 additions & 19 deletions packages/app-web-docs/src/docs/user/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -446,15 +446,15 @@ 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
- `"take bounds"` selects the nearest containing paired delimiters themselves of any kind
- `"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)

Expand Down Expand Up @@ -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 | ` ` | ` ` | ✅ | ❌ |
Original file line number Diff line number Diff line change
Expand Up @@ -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`

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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`

Expand Down
16 changes: 16 additions & 0 deletions packages/app-web-docs/src/docs/user/paired-delimiters.md
Original file line number Diff line number Diff line change
@@ -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 | ❌ | ✅ |
2 changes: 1 addition & 1 deletion packages/lib-common/src/references/actionReferences.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";

Expand Down
Original file line number Diff line number Diff line change
@@ -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<SpeakableSurroundingPairName, SpokenFormReference>;
} satisfies Record<SpeakableSurroundingPairName, PairedDelimiterReference>;
6 changes: 6 additions & 0 deletions packages/tool-meta-updater/src/metaUpdater.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,15 @@ import {
languageScopeSupport,
modifierReferenceGroups,
modifierReferences,
pairedDelimiterReferences,
scopeReferenceGroups,
scopeReferences,
} from "@cursorless/lib-common";
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";
Expand Down Expand Up @@ -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",
Expand Down
95 changes: 95 additions & 0 deletions packages/tool-meta-updater/src/updatePairedDelimitersMd.ts
Original file line number Diff line number Diff line change
@@ -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<string, PairedDelimiterReference>,
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,
);
}
Loading