keyboard: Use parser for key sequences

.editorconfig

@@ -28,7 +28,7 @@ trim_trailing_whitespace = false
 [Makefile]
 indent_style = tab
 
-[**/vendor/**]
+[**/{vendor,generated}/**]
 charset = unset
 end_of_line = unset
 indent_size = unset

.eslintrc.json

@@ -78,5 +78,10 @@
       }
     }
   },
-  "ignorePatterns": ["**/vendor/**/*.ts", "**/vendor/**/*.js", "**/out/**"]
+  "ignorePatterns": [
+    "**/vendor/**/*.ts",
+    "**/vendor/**/*.js",
+    "**/out/**",
+    "**/generated/**"
+  ]
 }

.pre-commit-config.yaml

@@ -40,7 +40,7 @@ repos:
         # tests use strings with trailing white space to represent the final
         # document contents. For example
         # packages/cursorless-vscode-e2e/src/suite/fixtures/recorded/languages/ruby/changeCondition.yml
-        exclude: ^packages/cursorless-vscode-e2e/src/suite/fixtures/recorded/.*/[^/]*\.yml$
+        exclude: ^packages/cursorless-vscode-e2e/src/suite/fixtures/recorded/.*/[^/]*\.yml$|/generated/|^patches/
   - repo: local
     hooks:
       - id: eslint

.prettierignore

@@ -1,4 +1,5 @@
 **/vendor
+**/generated
 
 # We use our own format for our recorded yaml tests to keep them compact
 /packages/cursorless-vscode-e2e/src/suite/fixtures/recorded/**/*.yml

.vscode/tasks.json

@@ -26,6 +26,7 @@
       "type": "npm",
       "script": "esbuild",
       "path": "packages/cursorless-vscode",
+      "dependsOn": ["Generate grammar"],
       "presentation": {
         "reveal": "silent"
       },
@@ -61,6 +62,16 @@
       },
       "group": "build"
     },
+    {
+      "label": "Generate grammar",
+      "type": "npm",
+      "script": "generate-grammar",
+      "path": "packages/cursorless-vscode",
+      "presentation": {
+        "reveal": "silent"
+      },
+      "group": "build"
+    },
     {
       "label": "Ensure test subset file exists",
       "type": "npm",

package.json

@@ -44,7 +44,9 @@
   },
   "pnpm": {
     "patchedDependencies": {
-      "@docusaurus/[email protected]": "patches/@[email protected]"
+      "@docusaurus/[email protected]": "patches/@[email protected]",
+      "@types/[email protected]": "patches/@[email protected]",
+      "[email protected]": "patches/[email protected]"
     },
     "peerDependencyRules": {
       "ignoreMissing": [

packages/cursorless-vscode/package.json

@@ -1091,7 +1091,7 @@
   "funding": "https://github.com/sponsors/pokey",
   "scripts": {
     "build": "pnpm run esbuild:prod && pnpm -F cheatsheet-local build:prod && pnpm run populate-dist",
-    "build:dev": "pnpm run esbuild && pnpm -F cheatsheet-local build && pnpm run populate-dist",
+    "build:dev": "pnpm generate-grammar && pnpm run esbuild && pnpm -F cheatsheet-local build && pnpm run populate-dist",
     "esbuild:base": "esbuild ./src/extension.ts --conditions=cursorless:bundler --bundle --outfile=dist/extension.cjs --external:vscode --format=cjs --platform=node",
     "install-local": "bash ./scripts/install-local.sh",
     "install-from-pr": "bash ./scripts/install-from-pr.sh",
@@ -1104,6 +1104,11 @@
     "preprocess-svg-hats": "my-ts-node src/scripts/preprocessSvgHats.ts",
     "hat-adjustment-add": "my-ts-node src/scripts/hatAdjustments/add.ts",
     "hat-adjustment-average": "my-ts-node src/scripts/hatAdjustments/average.ts",
+    "generate-grammar:base": "nearleyc src/keyboard/grammar/grammar.ne",
+    "ensure-grammar-up-to-date": "pnpm -s generate-grammar:base | diff -u src/keyboard/grammar/generated/grammar.ts -",
+    "generate-grammar": "pnpm generate-grammar:base -o src/keyboard/grammar/generated/grammar.ts",
+    "generate-railroad": "nearley-railroad src/keyboard/grammar/grammar.ne -o out/railroad.html",
+    "test": "pnpm ensure-grammar-up-to-date",
     "compile": "tsc --build",
     "watch": "tsc --build --watch",
     "clean": "rm -rf ./out tsconfig.tsbuildinfo ./dist ./build"
@@ -1115,6 +1120,7 @@
     "@types/js-yaml": "^4.0.2",
     "@types/lodash": "4.14.181",
     "@types/mocha": "^10.0.3",
+    "@types/nearley": "2.11.5",
     "@types/node": "^18.18.2",
     "@types/semver": "^7.3.9",
     "@types/sinon": "^10.0.2",
@@ -1127,6 +1133,7 @@
     "fs-extra": "11.1.0",
     "glob": "^7.1.7",
     "mocha": "^10.2.0",
+    "nearley": "2.20.1",
     "sinon": "^11.1.1"
   },
   "dependencies": {

packages/cursorless-vscode/src/keyboard/KeyboardActionType.ts

@@ -0,0 +1,36 @@
+import { ActionType, actionNames } from "@cursorless/common";
+
+const extraKeyboardActionNames = ["wrap"] as const;
+const excludedKeyboardActionNames = [
+  "wrapWithPairedDelimiter",
+  "wrapWithSnippet",
+] as const;
+const complexKeyboardActionTypes = ["wrap"] as const;
+
+type ExtraKeyboardActionType = (typeof extraKeyboardActionNames)[number];
+type ExcludedKeyboardActionType = (typeof excludedKeyboardActionNames)[number];
+type ComplexKeyboardActionType = (typeof complexKeyboardActionTypes)[number];
+export type SimpleKeyboardActionType = Exclude<
+  KeyboardActionType,
+  ComplexKeyboardActionType
+>;
+export type KeyboardActionType =
+  | Exclude<ActionType, ExcludedKeyboardActionType>
+  | ExtraKeyboardActionType;
+
+const keyboardActionNames: KeyboardActionType[] = [
+  ...actionNames.filter(
+    (
+      actionName,
+    ): actionName is Exclude<KeyboardActionType, ExtraKeyboardActionType> =>
+      !excludedKeyboardActionNames.includes(actionName as any),
+  ),
+  ...extraKeyboardActionNames,
+];
+
+export const simpleKeyboardActionNames = keyboardActionNames.filter(
+  (actionName): actionName is SimpleKeyboardActionType =>
+    !complexKeyboardActionTypes.includes(
+      actionName as ComplexKeyboardActionType,
+    ),
+);

packages/cursorless-vscode/src/keyboard/KeyboardCommandHandler.ts

@@ -0,0 +1,112 @@
+import { ScopeType } from "@cursorless/common";
+import * as vscode from "vscode";
+import { HatColor, HatShape } from "../ide/vscode/hatStyles.types";
+import { SimpleKeyboardActionType } from "./KeyboardActionType";
+import KeyboardCommandsTargeted from "./KeyboardCommandsTargeted";
+import { ModalVscodeCommandDescriptor } from "./TokenTypes";
+
+/**
+ * This class defines the keyboard commands available to our modal keyboard
+ * mode.
+ *
+ * Each method in this class corresponds to a top-level rule in the grammar. The
+ * method name is the name of the rule, and the method's argument is the rule's
+ * `arg` output.
+ *
+ * We try to keep all logic out of the grammar and use this class instead
+ * because:
+ *
+ * 1. The grammar has no type information, autocomplete, or autoformatting
+ * 2. If the grammar is defined by just a list of keys, as it is today, we can
+ *    actually detect partial arguments as they're being constructed and display
+ *    them to the user
+ *
+ * Thus, we use this class as a simple layer where we have strong types and can
+ * do some simple logic.
+ */
+export class KeyboardCommandHandler {
+  constructor(private targeted: KeyboardCommandsTargeted) {}
+
+  targetDecoratedMarkReplace({ decoratedMark }: DecoratedMarkArg) {
+    this.targeted.targetDecoratedMark(decoratedMark);
+  }
+
+  targetDecoratedMarkExtend({ decoratedMark }: DecoratedMarkArg) {
+    this.targeted.targetDecoratedMark({
+      ...decoratedMark,
+      mode: "extend",
+    });
+  }
+
+  async vscodeCommand({
+    command: commandInfo,
+  }: {
+    command: ModalVscodeCommandDescriptor;
+  }) {
+    const {
+      commandId,
+      args,
+      executeAtTarget,
+      keepChangedSelection,
+      exitCursorlessMode,
+    } =
+      typeof commandInfo === "string" || commandInfo instanceof String
+        ? ({ commandId: commandInfo } as Exclude<
+            ModalVscodeCommandDescriptor,
+            string
+          >)
+        : commandInfo;
+    if (executeAtTarget) {
+      await this.targeted.performVscodeCommandOnTarget(commandId, {
+        args,
+        keepChangedSelection,
+        exitCursorlessMode,
+      });
+      return;
+    }
+    await vscode.commands.executeCommand(commandId, ...(args ?? []));
+  }
+
+  performSimpleActionOnTarget({
+    actionName,
+  }: {
+    actionName: SimpleKeyboardActionType;
+  }) {
+    this.targeted.performActionOnTarget(actionName);
+  }
+
+  targetScopeType(arg: { scopeType: ScopeType }) {
+    this.targeted.targetScopeType(arg);
+  }
+
+  targetRelativeExclusiveScope({
+    offset,
+    length,
+    scopeType,
+  }: TargetRelativeExclusiveScopeArg) {
+    this.targeted.targetModifier({
+      type: "relativeScope",
+      offset: offset?.number ?? 1,
+      direction: offset?.direction ?? "forward",
+      length: length ?? 1,
+      scopeType,
+    });
+  }
+}
+
+interface DecoratedMarkArg {
+  decoratedMark: {
+    color?: HatColor;
+    shape?: HatShape;
+  };
+}
+interface TargetRelativeExclusiveScopeArg {
+  offset: Offset;
+  length: number | null;
+  scopeType: ScopeType;
+}
+
+interface Offset {
+  direction: "forward" | "backward" | null;
+  number: number | null;
+}

packages/cursorless-vscode/src/keyboard/KeyboardCommandTypeHelpers.ts

@@ -0,0 +1,40 @@
+import { KeyboardCommandHandler } from "./KeyboardCommandHandler";
+
+/**
+ * Maps from the name of a method in KeyboardCommandHandler to the type of its
+ * argument.
+ */
+export type KeyboardCommandArgTypes = {
+  [K in keyof KeyboardCommandHandler]: KeyboardCommandHandler[K] extends (
+    arg: infer T,
+  ) => void
+    ? T
+    : never;
+};
+
+export type KeyboardCommandTypeMap = {
+  [K in keyof KeyboardCommandHandler]: {
+    type: K;
+    arg: KeyboardCommandArgTypes[K];
+  };
+};
+
+export type KeyboardCommand<T extends keyof KeyboardCommandHandler> = {
+  type: T;
+  arg: KeyboardCommandArgTypes[T];
+};
+
+// Ensure that all methods in KeyboardCommandHandler take an object as their
+// first argument, and return void or Promise<void>. Note that the first check
+// may look backwards, because the arg type is contravariant, so the 'extends'
+// needs to be flipped.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+function assertExtends<A extends B, B>() {}
+assertExtends<
+  Record<keyof KeyboardCommandArgTypes, (arg?: object) => never>,
+  Pick<KeyboardCommandHandler, keyof KeyboardCommandArgTypes>
+>;
+assertExtends<
+  Pick<KeyboardCommandHandler, keyof KeyboardCommandArgTypes>,
+  Record<keyof KeyboardCommandArgTypes, (arg: never) => void | Promise<void>>
+>;