Cleanup KeywordPropertyDescription.

We now take the name from the associated property and close up weird
semantics with presentation types and flags by making the keyword
acceptor the top presentation schema.

We assume that the parser doesn't actually accept any associated
argument when a flag is used. But to be able to test that we need
to be able to run the commands in the unit tests.

This will require faking the command dispatcher or interface adaptor
and then as a pre-requisite probably putting all the dependencies
in some eays to use object that the client (user of the library)
will implement/extend some base thing that logs to console.

src/Command/KeywordParameterDescription.ts

@@ -13,10 +13,14 @@ import { Keyword } from "./Keyword";
 import { ParameterDescription } from "./ParameterDescription";
 import { ArgumentParseError, UnexpectedArgumentError } from "./ParseErrors";
 import { ParsedKeywords, StandardParsedKeywords } from "./ParsedKeywords";
-import { Presentation } from "./Presentation";
+import { Presentation, PresentationTypeWithoutWrap } from "./Presentation";
 import { RestDescription } from "./RestParameterDescription";
 import { PartialCommand } from "./Command";
 import {
+  PresentationSchema,
+  PresentationSchemaType,
+  SinglePresentationSchema,
+  TopPresentationSchema,
   checkPresentationSchema,
   printPresentationSchema,
 } from "./PresentationSchema";
@@ -35,6 +39,14 @@ export interface KeywordPropertyDescription<ObjectType = unknown>
   readonly isFlag: boolean;
 }
 
+export interface DescribeKeywordProperty<ObjectType = unknown> {
+  readonly acceptor?:
+    | PresentationSchema<ObjectType>
+    | PresentationTypeWithoutWrap<ObjectType>;
+  readonly isFlag?: boolean;
+  readonly description?: string;
+}
+
 /**
  * Describes which keyword arguments can be accepted by a command.
  */
@@ -164,15 +176,60 @@ export class KeywordParser<TKeywordsMeta extends KeywordsMeta = KeywordsMeta> {
 
 export type DescribeKeywordParametersOptions<
   TKeywordsMeta extends KeywordsMeta = KeywordsMeta,
-> = Omit<KeywordParametersDescription<TKeywordsMeta>, "getParser">;
+> = {
+  readonly keywordDescriptions: {
+    [I in keyof TKeywordsMeta]: DescribeKeywordProperty<TKeywordsMeta[I]>;
+  };
+  readonly allowOtherKeys?: boolean;
+};
+
+function describeKeywordProperty<ObjectType>(
+  name: string,
+  property: DescribeKeywordProperty<ObjectType>
+): KeywordPropertyDescription<ObjectType> {
+  if (property.acceptor === undefined) {
+    if (!property.isFlag) {
+      throw new TypeError(
+        "An acceptor is required if the property is not a flag."
+      );
+    }
+  }
+  const acceptor = ((acceptor) => {
+    if (acceptor === undefined) {
+      return TopPresentationSchema;
+    } else if ("schemaType" in acceptor) {
+      return acceptor;
+    } else {
+      return {
+        schemaType: PresentationSchemaType.Single,
+        presentationType: acceptor,
+      } as SinglePresentationSchema<ObjectType>;
+    }
+  })(property.acceptor);
+  return {
+    name,
+    isFlag: property.isFlag ?? false,
+    acceptor,
+    description: property.description,
+  };
+}
 
 export function describeKeywordParameters<
   TKeywordsMeta extends KeywordsMeta = KeywordsMeta,
 >(
   options: DescribeKeywordParametersOptions<TKeywordsMeta>
 ): KeywordParametersDescription<TKeywordsMeta> {
+  const keywordDescriptions: Record<string, KeywordPropertyDescription> = {};
+  for (const [name, property] of Object.entries(options.keywordDescriptions)) {
+    keywordDescriptions[name] = describeKeywordProperty(
+      name,
+      property as DescribeKeywordProperty
+    );
+  }
   return {
-    ...options,
+    keywordDescriptions:
+      keywordDescriptions as KeywordPropertyDescriptionsFromKeywordsMeta<TKeywordsMeta>,
+    allowOtherKeys: options.allowOtherKeys ?? false,
     getParser() {
       return new KeywordParser(this);
     },

src/Command/ParameterParsing.ts

@@ -180,7 +180,7 @@ export function describeCommandParameters<
     options.keywords === undefined
       ? describeKeywordParameters({
           keywordDescriptions:
-            {} as KeywordParametersDescription<TKeywordsMeta>["keywordDescriptions"],
+            {} as DescribeKeywordParametersOptions<TKeywordsMeta>["keywordDescriptions"],
           allowOtherKeys: false,
         })
       : describeKeywordParameters(options.keywords),

src/Command/describeCommand.test.ts

@@ -20,10 +20,12 @@ import {
   MatrixRoomIDPresentationType,
   MatrixRoomReferencePresentationSchema,
   MatrixUserIDPresentationType,
+  StringPresentationType,
 } from "../TextReader";
-import { StandardParsedKeywords } from "./ParsedKeywords";
+import { ParsedKeywords, StandardParsedKeywords } from "./ParsedKeywords";
 import { tuple } from "./ParameterParsing";
 import { PromptOptions } from "./PromptForAccept";
+import { describeKeywordParameters } from "./KeywordParameterDescription";
 
 it("Can define and execute commands.", async function () {
   type Context = {
@@ -90,3 +92,45 @@ it("Can define and execute commands.", async function () {
   );
   expect(isOk(banResult)).toBe(true);
 });
+
+// DescribeKeywordProperty optionally
+// accepts an acceptor only when the type is flag, and replaces that
+// with the TopPresentationSchema once its is turned into a KeywordPropertyDescription.
+it("Can define keyword arguments.", async function () {
+  // so it's at this point that i ralised that we have no ability to test the parseAndInvoke
+  // functionality in unit tests here without implementing a MatrixInterfaceAdaptor,
+  // or some other adaptor for unit testing.
+  // Making that fake probably requires splitting out the arguments to the interface adaptor
+  // or the command dispatcher too, so that there's something that has all those callbacks
+  // defined on them and they can be optionally implemented by the consumer.
+  // That will make it really easy for people to get started using the library without wondering
+  // what the hell these 200 dependencies are that they have to instantiate somehow.
+  const KeywordsCommandTest = describeCommand({
+    summary: "A command to test keyword arguments",
+    async executor(
+      _context: never,
+      _info: unknown,
+      keywords: ParsedKeywords
+    ): Promise<Result<unknown>> {},
+    parameters: [],
+    keywords: {
+      keywordDescriptions: {
+        "dry-run": {
+          isFlag: true,
+          description:
+            "Runs the kick command without actually removing any users.",
+        },
+        glob: {
+          isFlag: true,
+          description:
+            "Allows globs to be used to kick several users from rooms.",
+        },
+        room: {
+          acceptor: MatrixRoomReferencePresentationSchema,
+          description:
+            "Allows the command to be scoped to just one protected room.",
+        },
+      },
+    },
+  });
+});