Rename file

Author: pokey

packages/cursorless-engine/src/SpokenFormMap.ts

@@ -0,0 +1,30 @@
+import { SpokenFormMapEntry, SpokenFormType } from "../SpokenFormMap";
+
+/**
+ * A component of a spoken form used internally during spoken form generation.
+ * This is a recursive type, so it can contain other spoken form components.
+ * During the final step of spoken form generation, it is flattened.
+ *
+ * FIXME: In the future, we want to replace `string` with something like
+ * `LiteralSpokenFormComponent` and `SpokenFormComponent[]` with something like
+ * `SequenceSpokenFormComponent`. We'd also like to avoid throwing
+ * `NoSpokenFormError` and instead return a `SpokenFormComponent` that
+ * represents an error. This would allow us to localize errors and still render
+ * the remainder of the spoken form component.
+ */
+export type SpokenFormComponent =
+  | CustomizableSpokenFormComponent
+  | string
+  | SpokenFormComponent[];
+
+/**
+ * A customizable spoken form component. This is a spoken form component that
+ * can be customized by the user. It is used internally during spoken form
+ * generation.
+ */
+export interface CustomizableSpokenFormComponent {
+  type: "customizable";
+  spokenForms: SpokenFormMapEntry;
+  spokenFormType: SpokenFormType;
+  id: string;
+}

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

@@ -19,18 +19,18 @@ import { getRangeConnective } from "./getRangeConnective";
 import { SpokenFormMap } from "../SpokenFormMap";
 import { PrimitiveTargetSpokenFormGenerator } from "./primitiveTargetToSpokenForm";
 import {
-  GeneratorSpokenFormMap,
-  SpokenFormComponent,
-  getGeneratorSpokenForms,
-} from "./GeneratorSpokenFormMap";
+  SpokenFormComponentMap,
+  getSpokenFormComponentMap,
+} from "./getSpokenFormComponentMap";
+import { SpokenFormComponent } from "./SpokenFormComponent";
 import { SpokenForm } from "@cursorless/common";
 
 export class SpokenFormGenerator {
   private primitiveGenerator: PrimitiveTargetSpokenFormGenerator;
-  private spokenFormMap: GeneratorSpokenFormMap;
+  private spokenFormMap: SpokenFormComponentMap;
 
   constructor(spokenFormMap: SpokenFormMap) {
-    this.spokenFormMap = getGeneratorSpokenForms(spokenFormMap);
+    this.spokenFormMap = getSpokenFormComponentMap(spokenFormMap);
 
     this.primitiveGenerator = new PrimitiveTargetSpokenFormGenerator(
       this.spokenFormMap,
@@ -40,25 +40,41 @@ export class SpokenFormGenerator {
   /**
    * Given a command, generates its spoken form.
    * @param command The command to generate a spoken form for
-   * @returns The spoken form of the command, or null if the command has no spoken
-   * form
+   * @returns The spoken form of the command
    */
-  command(command: CommandComplete): SpokenForm {
+  processCommand(command: CommandComplete): SpokenForm {
     return this.componentsToSpokenForm(() => this.handleAction(command.action));
   }
 
   /**
-   * Given a command, generates its spoken form.
-   * @param command The command to generate a spoken form for
-   * @returns The spoken form of the command, or null if the command has no spoken
-   * form
+   * Given a scope type, generates its spoken form.
+   * @param scopeType The scope type to generate a spoken form for
+   * @returns The spoken form of the scope type
    */
-  scopeType(scopeType: ScopeType): SpokenForm {
+  processScopeType(scopeType: ScopeType): SpokenForm {
     return this.componentsToSpokenForm(() => [
       this.primitiveGenerator.handleScopeType(scopeType),
     ]);
   }
 
+  /**
+   * Given a function that returns a spoken form component, generates a spoken
+   * form for that component by flattening the component and performing a
+   * cartesian product over any elements that have multiple ways to be spoken.
+   * Note that this spoken form object can correspond to multiple actual spoken
+   * forms, consisting of a preferred spoken form and a list of alternative
+   * spoken forms.
+   *
+   * Note that today, we arbitrarily choose the first spoken form as the
+   * preferred spoken form, and the rest as alternative spoken forms.
+   *
+   * If the function throws a {@link NoSpokenFormError}, returns an error spoken
+   * form object instead.
+   *
+   * @param getComponents A function that returns the components to generate a
+   * spoken form for
+   * @returns A spoken form for the given components
+   */
   private componentsToSpokenForm(
     getComponents: () => SpokenFormComponent,
   ): SpokenForm {
@@ -256,9 +272,11 @@ function constructSpokenForms(component: SpokenFormComponent): string[] {
     const componentInfo = `${camelCaseToAllDown(
       component.spokenFormType,
     )} with id ${component.id}`;
+
     const helpInfo = component.spokenForms.isSecret
       ? "this is a secret spoken form currently only for internal experimentation"
       : "please see https://www.cursorless.org/docs/user/customization/ for more information";
+
     throw new NoSpokenFormError(
       `${componentInfo}; ${helpInfo}`,
       component.spokenForms.requiresTalonUpdate,

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

@@ -0,0 +1,50 @@
+import {
+  PartialSpokenFormTypes,
+  SpokenFormMap,
+  SpokenFormMapKeyTypes,
+} from "../SpokenFormMap";
+import { CustomizableSpokenFormComponent } from "./SpokenFormComponent";
+
+/**
+ * A spoken form component map is a map of spoken form types to a map of IDs to
+ * spoken form components. It is used to generate spoken forms. It mirrors the
+ * structure of a {@link SpokenFormMap}, but instead of containing spoken form
+ * map entries, it contains spoken form components for use in spoken form
+ * generation.
+ */
+export type SpokenFormComponentMap = {
+  readonly [K in keyof SpokenFormMapKeyTypes]: K extends PartialSpokenFormTypes
+    ? Partial<Record<SpokenFormMapKeyTypes[K], CustomizableSpokenFormComponent>>
+    : Record<SpokenFormMapKeyTypes[K], CustomizableSpokenFormComponent>;
+};
+
+/**
+ * Converts a spoken form map to a spoken form component map for use in spoken
+ * form generation.
+ * @param spokenFormMap The spoken form map to convert to a spoken form
+ * component map
+ * @returns A spoken form component map that can be used to generate spoken
+ * forms
+ */
+export function getSpokenFormComponentMap(
+  spokenFormMap: SpokenFormMap,
+): SpokenFormComponentMap {
+  return Object.fromEntries(
+    Object.entries(spokenFormMap).map(([spokenFormType, map]) => [
+      spokenFormType,
+      Object.fromEntries(
+        Object.entries(map).map(([id, spokenForms]) => [
+          id,
+          {
+            type: "customizable",
+            spokenForms,
+            spokenFormType,
+            id,
+          },
+        ]),
+      ),
+    ]),
+    // FIXME: Don't cast here; need to make our own mapValues with stronger typing
+    // using tricks from our object.d.ts
+  ) as SpokenFormComponentMap;
+}