Allow spoken forms generator to use custom

Author: pokey

packages/common/src/index.ts

@@ -11,6 +11,7 @@ export { getKey, splitKey } from "./util/splitKey";
 export { hrtimeBigintToSeconds } from "./util/timeUtils";
 export * from "./util/walkSync";
 export * from "./util/walkAsync";
+export * from "./util/camelCaseToAllDown";
 export { Notifier } from "./util/Notifier";
 export type { Listener } from "./util/Notifier";
 export type { TokenHatSplittingMode } from "./ide/types/Configuration";
@@ -42,6 +43,7 @@ export * from "./types/TextEditorOptions";
 export * from "./types/TextLine";
 export * from "./types/Token";
 export * from "./types/HatTokenMap";
+export * from "./types/SpokenForm";
 export * from "./util/textFormatters";
 export * from "./types/snippet.types";
 export * from "./testUtil/fromPlainObject";

packages/common/src/types/SpokenForm.ts

@@ -0,0 +1,14 @@
+export interface SpokenFormSuccess {
+  type: "success";
+  preferred: string;
+  alternatives: string[];
+}
+
+export interface SpokenFormError {
+  type: "error";
+  reason: string;
+  requiresTalonUpdate: boolean;
+  isPrivate: boolean;
+}
+
+export type SpokenForm = SpokenFormSuccess | SpokenFormError;

packages/common/src/util/camelCaseToAllDown.ts

@@ -0,0 +1,7 @@
+export function camelCaseToAllDown(input: string): string {
+  return input
+    .replace(/([A-Z])/g, " $1")
+    .split(" ")
+    .map((word) => word.toLowerCase())
+    .join(" ");
+}

packages/cursorless-engine/src/DefaultSpokenFormMap.ts

@@ -0,0 +1,195 @@
+import { mapValues } from "lodash";
+import {
+  SpokenFormMap,
+  SpokenFormMapEntry,
+  SpokenFormMapKeyTypes,
+} from "./SpokenFormMap";
+
+type DefaultSpokenFormMapDefinition = {
+  readonly [K in keyof SpokenFormMapKeyTypes]: Readonly<
+    Record<SpokenFormMapKeyTypes[K], string | DefaultSpokenFormMapEntry>
+  >;
+};
+
+const defaultSpokenFormMapCore: DefaultSpokenFormMapDefinition = {
+  pairedDelimiter: {
+    curlyBrackets: "curly",
+    angleBrackets: "diamond",
+    escapedDoubleQuotes: "escaped quad",
+    escapedSingleQuotes: "escaped twin",
+    escapedParentheses: "escaped round",
+    escapedSquareBrackets: "escaped box",
+    doubleQuotes: "quad",
+    parentheses: "round",
+    backtickQuotes: "skis",
+    squareBrackets: "box",
+    singleQuotes: "twin",
+    any: "pair",
+    string: "string",
+    whitespace: "void",
+  },
+
+  simpleScopeTypeType: {
+    argumentOrParameter: "arg",
+    attribute: "attribute",
+    functionCall: "call",
+    functionCallee: "callee",
+    className: "class name",
+    class: "class",
+    comment: "comment",
+    functionName: "funk name",
+    namedFunction: "funk",
+    ifStatement: "if state",
+    instance: "instance",
+    collectionItem: "item",
+    collectionKey: "key",
+    anonymousFunction: "lambda",
+    list: "list",
+    map: "map",
+    name: "name",
+    regularExpression: "regex",
+    section: "section",
+    sectionLevelOne: isDisabledByDefault("one section"),
+    sectionLevelTwo: isDisabledByDefault("two section"),
+    sectionLevelThree: isDisabledByDefault("three section"),
+    sectionLevelFour: isDisabledByDefault("four section"),
+    sectionLevelFive: isDisabledByDefault("five section"),
+    sectionLevelSix: isDisabledByDefault("six section"),
+    selector: "selector",
+    statement: "state",
+    branch: "branch",
+    type: "type",
+    value: "value",
+    condition: "condition",
+    unit: "unit",
+    //  XML, JSX
+    xmlElement: "element",
+    xmlBothTags: "tags",
+    xmlStartTag: "start tag",
+    xmlEndTag: "end tag",
+    // LaTeX
+    part: "part",
+    chapter: "chapter",
+    subSection: "subsection",
+    subSubSection: "subsubsection",
+    namedParagraph: "paragraph",
+    subParagraph: "subparagraph",
+    environment: "environment",
+    // Talon
+    command: "command",
+    // Text-based scope types
+    character: "char",
+    word: "word",
+    token: "token",
+    identifier: "identifier",
+    line: "line",
+    sentence: "sentence",
+    paragraph: "block",
+    document: "file",
+    nonWhitespaceSequence: "paint",
+    boundedNonWhitespaceSequence: "short paint",
+    url: "link",
+    notebookCell: "cell",
+
+    ["private.fieldAccess"]: isPrivate("access"),
+    string: isPrivate("parse tree string"),
+    switchStatementSubject: isPrivate("subject"),
+  },
+
+  surroundingPairForceDirection: {
+    left: "left",
+    right: "right",
+  },
+
+  simpleModifier: {
+    excludeInterior: "bounds",
+    toRawSelection: "just",
+    leading: "leading",
+    trailing: "trailing",
+    keepContentFilter: "content",
+    keepEmptyFilter: "empty",
+    inferPreviousMark: "its",
+    startOf: "start of",
+    endOf: "end of",
+    interiorOnly: "inside",
+    extendThroughStartOf: "head",
+    extendThroughEndOf: "tail",
+    everyScope: "every",
+  },
+
+  modifierExtra: {
+    first: "first",
+    last: "last",
+    previous: "previous",
+    next: "next",
+    forward: "forward",
+    backward: "backward",
+  },
+
+  customRegex: {},
+};
+
+function disabledByDefault(
+  ...spokenForms: string[]
+): DefaultSpokenFormMapEntry {
+  return {
+    defaultSpokenForms: spokenForms,
+    isDisabledByDefault: true,
+    isPrivate: false,
+  };
+}
+
+function secret(...spokenForms: string[]): DefaultSpokenFormMapEntry {
+  return {
+    defaultSpokenForms: spokenForms,
+    isDisabledByDefault: true,
+    isPrivate: true,
+  };
+}
+
+export interface DefaultSpokenFormMapEntry {
+  defaultSpokenForms: string[];
+  isDisabledByDefault: boolean;
+  isSecret: boolean;
+}
+
+export type DefaultSpokenFormMap = {
+  readonly [K in keyof SpokenFormMapKeyTypes]: Readonly<
+    Record<SpokenFormMapKeyTypes[K], DefaultSpokenFormMapEntry>
+  >;
+};
+
+// FIXME: Don't cast here; need to make our own mapValues with stronger typing
+// using tricks from our object.d.ts
+export const defaultSpokenFormInfo = mapValues(
+  defaultSpokenFormMapCore,
+  (entry) =>
+    mapValues(entry, (subEntry) =>
+      typeof subEntry === "string"
+        ? {
+            defaultSpokenForms: [subEntry],
+            isDisabledByDefault: false,
+            isPrivate: false,
+          }
+        : subEntry,
+    ),
+) as DefaultSpokenFormMap;
+
+// FIXME: Don't cast here; need to make our own mapValues with stronger typing
+// using tricks from our object.d.ts
+export const defaultSpokenFormMap = mapValues(defaultSpokenFormInfo, (entry) =>
+  mapValues(
+    entry,
+    ({
+      defaultSpokenForms,
+      isDisabledByDefault,
+      isSecret,
+    }): SpokenFormMapEntry => ({
+      spokenForms: isDisabledByDefault ? [] : defaultSpokenForms,
+      isCustom: false,
+      defaultSpokenForms,
+      requiresTalonUpdate: false,
+      isSecret,
+    }),
+  ),
+) as SpokenFormMap;

packages/cursorless-engine/src/SpokenFormMap.ts

@@ -0,0 +1,108 @@
+import {
+  ModifierType,
+  SimpleScopeTypeType,
+  SurroundingPairName,
+} from "@cursorless/common";
+
+export type SpeakableSurroundingPairName =
+  | Exclude<SurroundingPairName, "collectionBoundary">
+  | "whitespace";
+
+export type SimpleModifierType = Exclude<
+  ModifierType,
+  | "containingScope"
+  | "ordinalScope"
+  | "relativeScope"
+  | "modifyIfUntyped"
+  | "cascading"
+  | "range"
+>;
+
+export type ModifierExtra =
+  | "first"
+  | "last"
+  | "previous"
+  | "next"
+  | "forward"
+  | "backward";
+
+/**
+ * This interface is the source of truth for the types used in our spoken form
+ * map. The keys of this interface are the types of spoken forms that we
+ * support, eg `simpleScopeTypeType`, `simpleModifier`, etc. The type of each
+ * key is a disjunction of all identifiers that are allowed for the given type of
+ * spoken form.
+ */
+export interface SpokenFormMapKeyTypes {
+  pairedDelimiter: SpeakableSurroundingPairName;
+  simpleScopeTypeType: SimpleScopeTypeType;
+  surroundingPairForceDirection: "left" | "right";
+
+  /**
+   * These modifier types are spoken by directly saying the spoken form for the
+   * modifier type, unlike the more complex spoken forms such as
+   * `relativeScope`, which can use various different custom spoken forms such
+   * as `next`, `previous`, etc.
+   */
+  simpleModifier: SimpleModifierType;
+
+  /**
+   * These are customizable spoken forms used in speaking modifiers, but that
+   * don't directly correspond to a modifier type. For example, `next` is a
+   * customizable spoken form that can be used when speaking `relativeScope`
+   * modifiers, but `next` itself isn't a modifier type.
+   */
+  modifierExtra: ModifierExtra;
+  customRegex: string;
+}
+
+export type SpokenFormType = keyof SpokenFormMapKeyTypes;
+
+export interface SpokenFormMapEntry {
+  /**
+   * The spoken forms for this entry. These could either be a user's custom
+   * spoken forms, if we have access to them, or the default spoken forms, if we
+   * don't, or if we're testing.
+   */
+  spokenForms: string[];
+
+  /**
+   * If `true`, indicates that the user is not using the default spoken forms
+   * for this entry.
+   */
+  isCustom: boolean;
+
+  /**
+   * The default spoken forms for this entry.
+   */
+  defaultSpokenForms: string[];
+
+  /**
+   * If `true`, indicates that the entry wasn't found in the user's Talon spoken
+   * forms json, and so they need to update their cursorless-talon to get the
+   * given entity.
+   */
+  requiresTalonUpdate: boolean;
+
+  /**
+   * If `true`, indicates that the entry is only for internal experimentation,
+   * and should not be exposed to users except within a targeted working group.
+   */
+  isPrivate: boolean;
+}
+
+/**
+ * A spoken form map contains information about the spoken forms for all our
+ * speakable entities, including scope types, paired delimiters, etc. It can
+ * either contain the user's custom spoken forms, or the default spoken forms,
+ * if we don't have access to the user's custom spoken forms, or if we're
+ * testing.
+ *
+ * Each key of this map is a type of spoken form, eg `simpleScopeTypeType`, and
+ * the value is a map of identifiers to {@link SpokenFormMapEntry}s.
+ */
+export type SpokenFormMap = {
+  readonly [K in keyof SpokenFormMapKeyTypes]: Readonly<
+    Record<SpokenFormMapKeyTypes[K], SpokenFormMapEntry>
+  >;
+};

packages/cursorless-engine/src/generateSpokenForm/GeneratorSpokenFormMap.ts

@@ -0,0 +1,48 @@
+import {
+  SpokenFormMap,
+  SpokenFormMapEntry,
+  SpokenFormMapKeyTypes,
+  SpokenFormType,
+} from "../SpokenFormMap";
+
+export type GeneratorSpokenFormMap = {
+  readonly [K in keyof SpokenFormMapKeyTypes]: Record<
+    SpokenFormMapKeyTypes[K],
+    SingleTermSpokenForm
+  >;
+};
+
+export interface SingleTermSpokenForm {
+  type: "singleTerm";
+  spokenForms: SpokenFormMapEntry;
+  spokenFormType: SpokenFormType;
+  id: string;
+}
+
+export type SpokenFormComponent =
+  | SingleTermSpokenForm
+  | string
+  | SpokenFormComponent[];
+
+export function getGeneratorSpokenForms(
+  spokenFormMap: SpokenFormMap,
+): GeneratorSpokenFormMap {
+  // FIXME: Don't cast here; need to make our own mapValues with stronger typing
+  // using tricks from our object.d.ts
+  return Object.fromEntries(
+    Object.entries(spokenFormMap).map(([spokenFormType, map]) => [
+      spokenFormType,
+      Object.fromEntries(
+        Object.entries(map).map(([id, spokenForms]) => [
+          id,
+          {
+            type: "singleTerm",
+            spokenForms,
+            spokenFormType,
+            id,
+          },
+        ]),
+      ),
+    ]),
+  ) as GeneratorSpokenFormMap;
+}