@rushstack/ts-command-line 5.2.0 → 5.3.1

package/lib-esm/providers/AliasCommandLineAction.js

@@ -0,0 +1,131 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import * as argparse from 'argparse';
+import { CommandLineAction } from './CommandLineAction';
+import { CommandLineParameterKind } from '../parameters/BaseClasses';
+/**
+ * Represents a sub-command that is part of the CommandLineParser command line.
+ * The sub-command is an alias for another existing action.
+ *
+ * The alias name should be comprised of lower case words separated by hyphens
+ * or colons. The name should include an English verb (e.g. "deploy"). Use a
+ * hyphen to separate words (e.g. "upload-docs").
+ *
+ * @public
+ */
+export class AliasCommandLineAction extends CommandLineAction {
+    constructor(options) {
+        const toolFilename = options.toolFilename;
+        const targetActionName = options.targetAction.actionName;
+        const defaultParametersString = (options.defaultParameters || []).join(' ');
+        const summary = `An alias for "${toolFilename} ${targetActionName}${defaultParametersString ? ` ${defaultParametersString}` : ''}".`;
+        super({
+            actionName: options.aliasName,
+            summary,
+            documentation: `${summary} For more information on the aliased command, use ` +
+                `"${toolFilename} ${targetActionName} --help".`
+        });
+        this._parameterKeyMap = new Map();
+        this.targetAction = options.targetAction;
+        this.defaultParameters = options.defaultParameters || [];
+    }
+    /** @internal */
+    _registerDefinedParameters(state) {
+        /* override */
+        // All parameters are going to be defined by the target action. Re-use the target action parameters
+        // for this action.
+        for (const parameter of this.targetAction.parameters) {
+            const { kind, longName, shortName } = parameter;
+            let aliasParameter;
+            const nameOptions = {
+                parameterLongName: longName,
+                parameterShortName: shortName
+            };
+            switch (kind) {
+                case CommandLineParameterKind.Choice:
+                    aliasParameter = this.defineChoiceParameter({
+                        ...nameOptions,
+                        ...parameter,
+                        alternatives: [...parameter.alternatives]
+                    });
+                    break;
+                case CommandLineParameterKind.ChoiceList:
+                    aliasParameter = this.defineChoiceListParameter({
+                        ...nameOptions,
+                        ...parameter,
+                        alternatives: [...parameter.alternatives]
+                    });
+                    break;
+                case CommandLineParameterKind.Flag:
+                    aliasParameter = this.defineFlagParameter({ ...nameOptions, ...parameter });
+                    break;
+                case CommandLineParameterKind.Integer:
+                    aliasParameter = this.defineIntegerParameter({ ...nameOptions, ...parameter });
+                    break;
+                case CommandLineParameterKind.IntegerList:
+                    aliasParameter = this.defineIntegerListParameter({ ...nameOptions, ...parameter });
+                    break;
+                case CommandLineParameterKind.String:
+                    aliasParameter = this.defineStringParameter({ ...nameOptions, ...parameter });
+                    break;
+                case CommandLineParameterKind.StringList:
+                    aliasParameter = this.defineStringListParameter({ ...nameOptions, ...parameter });
+                    break;
+                default:
+                    throw new Error(`Unsupported parameter kind: ${kind}`);
+            }
+            // We know the parserKey is defined because the underlying _defineParameter method sets it,
+            // and all parameters that we have access to have already been defined.
+            this._parameterKeyMap.set(aliasParameter._parserKey, parameter._parserKey);
+        }
+        // We also need to register the remainder parameter if the target action has one. The parser
+        // key for this parameter is constant.
+        if (this.targetAction.remainder) {
+            this.defineCommandLineRemainder(this.targetAction.remainder);
+            this._parameterKeyMap.set(argparse.Const.REMAINDER, argparse.Const.REMAINDER);
+        }
+        // Finally, register the parameters with the parser. We need to make sure that the target action
+        // is registered, since we need to re-use its parameters, and ambiguous parameters are discovered
+        // during registration. This will no-op if the target action is already registered.
+        this.targetAction._registerDefinedParameters(state);
+        super._registerDefinedParameters(state);
+        // We need to re-map the ambiguous parameters after they are defined by calling
+        // super._registerDefinedParameters()
+        for (const [ambiguousParameterName, parserKey] of this._ambiguousParameterParserKeysByName) {
+            const targetParserKey = this.targetAction._ambiguousParameterParserKeysByName.get(ambiguousParameterName);
+            // If we have a mapping for the specified key, then use it. Otherwise, use the key as-is.
+            if (targetParserKey) {
+                this._parameterKeyMap.set(parserKey, targetParserKey);
+            }
+        }
+    }
+    /**
+     * {@inheritdoc CommandLineParameterProvider._processParsedData}
+     * @internal
+     */
+    _processParsedData(parserOptions, data) {
+        // Re-map the parsed data to the target action's parameters and execute the target action processor.
+        const targetData = {
+            action: this.targetAction.actionName,
+            aliasAction: data.action,
+            aliasDocumentation: this.documentation
+        };
+        for (const [key, value] of Object.entries(data)) {
+            // If we have a mapping for the specified key, then use it. Otherwise, use the key as-is.
+            // Skip over the action key though, since we've already re-mapped it to "aliasAction"
+            if (key === 'action') {
+                continue;
+            }
+            const targetKey = this._parameterKeyMap.get(key);
+            targetData[targetKey !== null && targetKey !== void 0 ? targetKey : key] = value;
+        }
+        this.targetAction._processParsedData(parserOptions, targetData);
+    }
+    /**
+     * Executes the target action.
+     */
+    async onExecuteAsync() {
+        await this.targetAction._executeAsync();
+    }
+}
+//# sourceMappingURL=AliasCommandLineAction.js.map

package/lib-esm/providers/AliasCommandLineAction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AliasCommandLineAction.js","sourceRoot":"","sources":["../../src/providers/AliasCommandLineAction.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport * as argparse from 'argparse';\n\nimport { CommandLineAction } from './CommandLineAction';\nimport {\n  CommandLineParameterKind,\n  type CommandLineParameterBase,\n  type CommandLineParameter\n} from '../parameters/BaseClasses';\nimport type { ICommandLineParserData, IRegisterDefinedParametersState } from './CommandLineParameterProvider';\nimport type { ICommandLineParserOptions } from './CommandLineParser';\n\n/**\n * Options for the AliasCommandLineAction constructor.\n * @public\n */\nexport interface IAliasCommandLineActionOptions {\n  /**\n   * The name of your tool when invoked from the command line. Used for generating help text.\n   */\n  toolFilename: string;\n\n  /**\n   * The name of the alias.  For example, if the tool is called \"example\",\n   * then the \"build\" alias might be invoked as: \"example build -q --some-other-option\"\n   */\n  aliasName: string;\n\n  /**\n   * A list of default parameters to pass to the target action.\n   */\n  defaultParameters?: string[];\n\n  /**\n   * The action that this alias invokes.\n   */\n  targetAction: CommandLineAction;\n}\n\n/**\n * Represents a sub-command that is part of the CommandLineParser command line.\n * The sub-command is an alias for another existing action.\n *\n * The alias name should be comprised of lower case words separated by hyphens\n * or colons. The name should include an English verb (e.g. \"deploy\"). Use a\n * hyphen to separate words (e.g. \"upload-docs\").\n *\n * @public\n */\nexport class AliasCommandLineAction extends CommandLineAction {\n  /**\n   * The action that this alias invokes.\n   */\n  public readonly targetAction: CommandLineAction;\n\n  /**\n   * A list of default arguments to pass to the target action.\n   */\n  public readonly defaultParameters: ReadonlyArray<string>;\n\n  private _parameterKeyMap: Map<string, string> = new Map();\n\n  public constructor(options: IAliasCommandLineActionOptions) {\n    const toolFilename: string = options.toolFilename;\n    const targetActionName: string = options.targetAction.actionName;\n    const defaultParametersString: string = (options.defaultParameters || []).join(' ');\n    const summary: string = `An alias for \"${toolFilename} ${targetActionName}${\n      defaultParametersString ? ` ${defaultParametersString}` : ''\n    }\".`;\n\n    super({\n      actionName: options.aliasName,\n      summary,\n      documentation:\n        `${summary} For more information on the aliased command, use ` +\n        `\"${toolFilename} ${targetActionName} --help\".`\n    });\n\n    this.targetAction = options.targetAction;\n    this.defaultParameters = options.defaultParameters || [];\n  }\n\n  /** @internal */\n  public _registerDefinedParameters(state: IRegisterDefinedParametersState): void {\n    /* override */\n    // All parameters are going to be defined by the target action. Re-use the target action parameters\n    // for this action.\n    for (const parameter of this.targetAction.parameters as CommandLineParameter[]) {\n      const { kind, longName, shortName } = parameter;\n      let aliasParameter: CommandLineParameterBase;\n      const nameOptions: { parameterLongName: string; parameterShortName: string | undefined } = {\n        parameterLongName: longName,\n        parameterShortName: shortName\n      };\n      switch (kind) {\n        case CommandLineParameterKind.Choice:\n          aliasParameter = this.defineChoiceParameter({\n            ...nameOptions,\n            ...parameter,\n            alternatives: [...parameter.alternatives]\n          });\n          break;\n        case CommandLineParameterKind.ChoiceList:\n          aliasParameter = this.defineChoiceListParameter({\n            ...nameOptions,\n            ...parameter,\n            alternatives: [...parameter.alternatives]\n          });\n          break;\n        case CommandLineParameterKind.Flag:\n          aliasParameter = this.defineFlagParameter({ ...nameOptions, ...parameter });\n          break;\n        case CommandLineParameterKind.Integer:\n          aliasParameter = this.defineIntegerParameter({ ...nameOptions, ...parameter });\n          break;\n        case CommandLineParameterKind.IntegerList:\n          aliasParameter = this.defineIntegerListParameter({ ...nameOptions, ...parameter });\n          break;\n        case CommandLineParameterKind.String:\n          aliasParameter = this.defineStringParameter({ ...nameOptions, ...parameter });\n          break;\n        case CommandLineParameterKind.StringList:\n          aliasParameter = this.defineStringListParameter({ ...nameOptions, ...parameter });\n          break;\n        default:\n          throw new Error(`Unsupported parameter kind: ${kind}`);\n      }\n\n      // We know the parserKey is defined because the underlying _defineParameter method sets it,\n      // and all parameters that we have access to have already been defined.\n      this._parameterKeyMap.set(aliasParameter._parserKey!, parameter._parserKey!);\n    }\n\n    // We also need to register the remainder parameter if the target action has one. The parser\n    // key for this parameter is constant.\n    if (this.targetAction.remainder) {\n      this.defineCommandLineRemainder(this.targetAction.remainder);\n      this._parameterKeyMap.set(argparse.Const.REMAINDER, argparse.Const.REMAINDER);\n    }\n\n    // Finally, register the parameters with the parser. We need to make sure that the target action\n    // is registered, since we need to re-use its parameters, and ambiguous parameters are discovered\n    // during registration. This will no-op if the target action is already registered.\n    this.targetAction._registerDefinedParameters(state);\n    super._registerDefinedParameters(state);\n\n    // We need to re-map the ambiguous parameters after they are defined by calling\n    // super._registerDefinedParameters()\n    for (const [ambiguousParameterName, parserKey] of this._ambiguousParameterParserKeysByName) {\n      const targetParserKey: string | undefined =\n        this.targetAction._ambiguousParameterParserKeysByName.get(ambiguousParameterName);\n\n      // If we have a mapping for the specified key, then use it. Otherwise, use the key as-is.\n      if (targetParserKey) {\n        this._parameterKeyMap.set(parserKey, targetParserKey);\n      }\n    }\n  }\n\n  /**\n   * {@inheritdoc CommandLineParameterProvider._processParsedData}\n   * @internal\n   */\n  public _processParsedData(parserOptions: ICommandLineParserOptions, data: ICommandLineParserData): void {\n    // Re-map the parsed data to the target action's parameters and execute the target action processor.\n    const targetData: ICommandLineParserData = {\n      action: this.targetAction.actionName,\n      aliasAction: data.action,\n      aliasDocumentation: this.documentation\n    };\n    for (const [key, value] of Object.entries(data)) {\n      // If we have a mapping for the specified key, then use it. Otherwise, use the key as-is.\n      // Skip over the action key though, since we've already re-mapped it to \"aliasAction\"\n      if (key === 'action') {\n        continue;\n      }\n      const targetKey: string | undefined = this._parameterKeyMap.get(key);\n      targetData[targetKey ?? key] = value;\n    }\n    this.targetAction._processParsedData(parserOptions, targetData);\n  }\n\n  /**\n   * Executes the target action.\n   */\n  protected override async onExecuteAsync(): Promise<void> {\n    await this.targetAction._executeAsync();\n  }\n}\n"]}

package/lib-esm/providers/CommandLineAction.js

@@ -0,0 +1,76 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import { CommandLineParameterProvider } from './CommandLineParameterProvider';
+import { CommandLineParserExitError } from './CommandLineParserExitError';
+import { escapeSprintf } from '../escapeSprintf';
+/**
+ * Example: "do-something"
+ */
+const ACTION_NAME_REGEXP = /^[a-z][a-z0-9]*([-:][a-z0-9]+)*$/;
+/**
+ * Represents a sub-command that is part of the CommandLineParser command line.
+ * Applications should create subclasses of CommandLineAction corresponding to
+ * each action that they want to expose.
+ *
+ * The action name should be comprised of lower case words separated by hyphens
+ * or colons. The name should include an English verb (e.g. "deploy"). Use a
+ * hyphen to separate words (e.g. "upload-docs"). A group of related commands
+ * can be prefixed with a colon (e.g. "docs:generate", "docs:deploy",
+ * "docs:serve", etc).
+ *
+ * @public
+ */
+export class CommandLineAction extends CommandLineParameterProvider {
+    constructor(options) {
+        super();
+        if (!ACTION_NAME_REGEXP.test(options.actionName)) {
+            throw new Error(`Invalid action name "${options.actionName}". ` +
+                `The name must be comprised of lower-case words optionally separated by hyphens or colons.`);
+        }
+        this.actionName = options.actionName;
+        this.summary = options.summary;
+        this.documentation = options.documentation;
+        this._argumentParser = undefined;
+    }
+    /**
+     * This is called internally by CommandLineParser.addAction()
+     * @internal
+     */
+    _buildParser(actionsSubParser) {
+        this._argumentParser = actionsSubParser.addParser(this.actionName, {
+            help: escapeSprintf(this.summary),
+            description: escapeSprintf(this.documentation)
+        });
+        // Monkey-patch the error handling for the action parser
+        this._argumentParser.exit = (status, message) => {
+            throw new CommandLineParserExitError(status, message);
+        };
+        const originalArgumentParserErrorFn = this._argumentParser.error.bind(this._argumentParser);
+        this._argumentParser.error = (err) => {
+            // Ensure the ParserExitError bubbles up to the top without any special processing
+            if (err instanceof CommandLineParserExitError) {
+                throw err;
+            }
+            originalArgumentParserErrorFn(err);
+        };
+    }
+    /**
+     * Invoked by CommandLineParser.onExecute().
+     * @internal
+     */
+    async _executeAsync() {
+        await this.onExecuteAsync();
+    }
+    /**
+     * {@inheritDoc CommandLineParameterProvider._getArgumentParser}
+     * @internal
+     */
+    _getArgumentParser() {
+        if (!this._argumentParser) {
+            // We will improve this in the future
+            throw new Error('The CommandLineAction must be added to a CommandLineParser before it can be used');
+        }
+        return this._argumentParser;
+    }
+}
+//# sourceMappingURL=CommandLineAction.js.map

package/lib-esm/providers/CommandLineAction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandLineAction.js","sourceRoot":"","sources":["../../src/providers/CommandLineAction.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAI3D,OAAO,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAC9E,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AA0BjD;;GAEG;AACH,MAAM,kBAAkB,GAAW,kCAAkC,CAAC;AAEtE;;;;;;;;;;;;GAYG;AACH,MAAM,OAAgB,iBAAkB,SAAQ,4BAA4B;IAY1E,YAAmB,OAAkC;QACnD,KAAK,EAAE,CAAC;QAER,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;YACjD,MAAM,IAAI,KAAK,CACb,wBAAwB,OAAO,CAAC,UAAU,KAAK;gBAC7C,2FAA2F,CAC9F,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;QAE3C,IAAI,CAAC,eAAe,GAAG,SAAS,CAAC;IACnC,CAAC;IAED;;;OAGG;IACI,YAAY,CAAC,gBAAoC;QACtD,IAAI,CAAC,eAAe,GAAG,gBAAgB,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,EAAE;YACjE,IAAI,EAAE,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC;YACjC,WAAW,EAAE,aAAa,CAAC,IAAI,CAAC,aAAa,CAAC;SAC/C,CAAC,CAAC;QAEH,wDAAwD;QACxD,IAAI,CAAC,eAAe,CAAC,IAAI,GAAG,CAAC,MAAc,EAAE,OAAe,EAAE,EAAE;YAC9D,MAAM,IAAI,0BAA0B,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACxD,CAAC,CAAC;QACF,MAAM,6BAA6B,GAAkC,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,IAAI,CAClG,IAAI,CAAC,eAAe,CACrB,CAAC;QACF,IAAI,CAAC,eAAe,CAAC,KAAK,GAAG,CAAC,GAAmB,EAAE,EAAE;YACnD,kFAAkF;YAClF,IAAI,GAAG,YAAY,0BAA0B,EAAE,CAAC;gBAC9C,MAAM,GAAG,CAAC;YACZ,CAAC;YACD,6BAA6B,CAAC,GAAG,CAAC,CAAC;QACrC,CAAC,CAAC;IACJ,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,aAAa;QACxB,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;IAC9B,CAAC;IAED;;;OAGG;IACa,kBAAkB;QAChC,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;YAC1B,qCAAqC;YACrC,MAAM,IAAI,KAAK,CAAC,kFAAkF,CAAC,CAAC;QACtG,CAAC;QAED,OAAO,IAAI,CAAC,eAAe,CAAC;IAC9B,CAAC;CAMF","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport type * as argparse from 'argparse';\n\nimport { CommandLineParameterProvider } from './CommandLineParameterProvider';\nimport { CommandLineParserExitError } from './CommandLineParserExitError';\nimport { escapeSprintf } from '../escapeSprintf';\n\n/**\n * Options for the CommandLineAction constructor.\n * @public\n */\nexport interface ICommandLineActionOptions {\n  /**\n   * The name of the action.  For example, if the tool is called \"example\",\n   * then the \"build\" action might be invoked as: \"example build -q --some-other-option\"\n   */\n  actionName: string;\n\n  /**\n   * A quick summary that is shown on the main help page, which is displayed\n   * by the command \"example --help\"\n   */\n  summary: string;\n\n  /**\n   * A detailed description that is shown on the action help page, which is displayed\n   * by the command \"example build --help\", e.g. for actionName=\"build\".\n   */\n  documentation: string;\n}\n\n/**\n * Example: \"do-something\"\n */\nconst ACTION_NAME_REGEXP: RegExp = /^[a-z][a-z0-9]*([-:][a-z0-9]+)*$/;\n\n/**\n * Represents a sub-command that is part of the CommandLineParser command line.\n * Applications should create subclasses of CommandLineAction corresponding to\n * each action that they want to expose.\n *\n * The action name should be comprised of lower case words separated by hyphens\n * or colons. The name should include an English verb (e.g. \"deploy\"). Use a\n * hyphen to separate words (e.g. \"upload-docs\"). A group of related commands\n * can be prefixed with a colon (e.g. \"docs:generate\", \"docs:deploy\",\n * \"docs:serve\", etc).\n *\n * @public\n */\nexport abstract class CommandLineAction extends CommandLineParameterProvider {\n  /** {@inheritDoc ICommandLineActionOptions.actionName} */\n  public readonly actionName: string;\n\n  /** {@inheritDoc ICommandLineActionOptions.summary} */\n  public readonly summary: string;\n\n  /** {@inheritDoc ICommandLineActionOptions.documentation} */\n  public readonly documentation: string;\n\n  private _argumentParser: argparse.ArgumentParser | undefined;\n\n  public constructor(options: ICommandLineActionOptions) {\n    super();\n\n    if (!ACTION_NAME_REGEXP.test(options.actionName)) {\n      throw new Error(\n        `Invalid action name \"${options.actionName}\". ` +\n          `The name must be comprised of lower-case words optionally separated by hyphens or colons.`\n      );\n    }\n\n    this.actionName = options.actionName;\n    this.summary = options.summary;\n    this.documentation = options.documentation;\n\n    this._argumentParser = undefined;\n  }\n\n  /**\n   * This is called internally by CommandLineParser.addAction()\n   * @internal\n   */\n  public _buildParser(actionsSubParser: argparse.SubParser): void {\n    this._argumentParser = actionsSubParser.addParser(this.actionName, {\n      help: escapeSprintf(this.summary),\n      description: escapeSprintf(this.documentation)\n    });\n\n    // Monkey-patch the error handling for the action parser\n    this._argumentParser.exit = (status: number, message: string) => {\n      throw new CommandLineParserExitError(status, message);\n    };\n    const originalArgumentParserErrorFn: (err: Error | string) => void = this._argumentParser.error.bind(\n      this._argumentParser\n    );\n    this._argumentParser.error = (err: Error | string) => {\n      // Ensure the ParserExitError bubbles up to the top without any special processing\n      if (err instanceof CommandLineParserExitError) {\n        throw err;\n      }\n      originalArgumentParserErrorFn(err);\n    };\n  }\n\n  /**\n   * Invoked by CommandLineParser.onExecute().\n   * @internal\n   */\n  public async _executeAsync(): Promise<void> {\n    await this.onExecuteAsync();\n  }\n\n  /**\n   * {@inheritDoc CommandLineParameterProvider._getArgumentParser}\n   * @internal\n   */\n  public override _getArgumentParser(): argparse.ArgumentParser {\n    if (!this._argumentParser) {\n      // We will improve this in the future\n      throw new Error('The CommandLineAction must be added to a CommandLineParser before it can be used');\n    }\n\n    return this._argumentParser;\n  }\n\n  /**\n   * Your subclass should implement this hook to perform the operation.\n   */\n  protected abstract onExecuteAsync(): Promise<void>;\n}\n"]}