@rushstack/ts-command-line 4.9.1

package/lib/providers/CommandLineAction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandLineAction.d.ts","sourceRoot":"","sources":["../../src/providers/CommandLineAction.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,QAAQ,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,4BAA4B,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAEtG;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,8BAAsB,iBAAkB,SAAQ,4BAA4B;IAE1E,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAA8C;IAE9E,yDAAyD;IACzD,SAAgB,UAAU,EAAE,MAAM,CAAC;IAEnC,sDAAsD;IACtD,SAAgB,OAAO,EAAE,MAAM,CAAC;IAEhC,4DAA4D;IAC5D,SAAgB,aAAa,EAAE,MAAM,CAAC;IAEtC,OAAO,CAAC,eAAe,CAAsC;gBAE1C,OAAO,EAAE,yBAAyB;IAiBrD;;;OAGG;IACI,YAAY,CAAC,gBAAgB,EAAE,QAAQ,CAAC,SAAS,GAAG,IAAI;IAS/D;;;OAGG;IACI,kBAAkB,CAAC,IAAI,EAAE,sBAAsB,GAAG,IAAI;IAI7D;;;OAGG;IACI,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAIhC;;;OAGG;IACH,SAAS,CAAC,kBAAkB,IAAI,QAAQ,CAAC,cAAc;IAUvD;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,kBAAkB,IAAI,IAAI;IAE7C;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CAC9C"}

package/lib/providers/CommandLineAction.js

@@ -0,0 +1,73 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandLineAction = void 0;
+const CommandLineParameterProvider_1 = require("./CommandLineParameterProvider");
+/**
+ * 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
+ */
+class CommandLineAction extends CommandLineParameterProvider_1.CommandLineParameterProvider {
+    constructor(options) {
+        super();
+        if (!CommandLineAction._actionNameRegExp.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: this.summary,
+            description: this.documentation
+        });
+        this.onDefineParameters();
+    }
+    /**
+     * This is called internally by CommandLineParser.execute()
+     * @internal
+     */
+    _processParsedData(data) {
+        super._processParsedData(data);
+    }
+    /**
+     * Invoked by CommandLineParser.onExecute().
+     * @internal
+     */
+    _execute() {
+        return this.onExecute();
+    }
+    /**
+     * {@inheritDoc CommandLineParameterProvider._getArgumentParser}
+     * @internal
+     */
+    _getArgumentParser() {
+        // override
+        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;
+    }
+}
+exports.CommandLineAction = CommandLineAction;
+// Example: "do-something"
+CommandLineAction._actionNameRegExp = /^[a-z][a-z0-9]*([-:][a-z0-9]+)*$/;
+//# sourceMappingURL=CommandLineAction.js.map

package/lib/providers/CommandLineAction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandLineAction.js","sourceRoot":"","sources":["../../src/providers/CommandLineAction.ts"],"names":[],"mappings":";AAAA,4FAA4F;AAC5F,2DAA2D;;;AAG3D,iFAAsG;AA0BtG;;;;;;;;;;;;GAYG;AACH,MAAsB,iBAAkB,SAAQ,2DAA4B;IAe1E,YAAmB,OAAkC;QACnD,KAAK,EAAE,CAAC;QAER,IAAI,CAAC,iBAAiB,CAAC,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE;YACjE,MAAM,IAAI,KAAK,CACb,wBAAwB,OAAO,CAAC,UAAU,KAAK;gBAC7C,2FAA2F,CAC9F,CAAC;SACH;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,IAAI,CAAC,OAAO;YAClB,WAAW,EAAE,IAAI,CAAC,aAAa;SAChC,CAAC,CAAC;QAEH,IAAI,CAAC,kBAAkB,EAAE,CAAC;IAC5B,CAAC;IAED;;;OAGG;IACI,kBAAkB,CAAC,IAA4B;QACpD,KAAK,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED;;;OAGG;IACI,QAAQ;QACb,OAAO,IAAI,CAAC,SAAS,EAAE,CAAC;IAC1B,CAAC;IAED;;;OAGG;IACO,kBAAkB;QAC1B,WAAW;QACX,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE;YACzB,qCAAqC;YACrC,MAAM,IAAI,KAAK,CAAC,kFAAkF,CAAC,CAAC;SACrG;QAED,OAAO,IAAI,CAAC,eAAe,CAAC;IAC9B,CAAC;;AAzEH,8CAoFC;AAnFC,0BAA0B;AACX,mCAAiB,GAAW,kCAAkC,CAAC","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\r\n// See LICENSE in the project root for license information.\r\n\r\nimport * as argparse from 'argparse';\r\nimport { CommandLineParameterProvider, ICommandLineParserData } from './CommandLineParameterProvider';\r\n\r\n/**\r\n * Options for the CommandLineAction constructor.\r\n * @public\r\n */\r\nexport interface ICommandLineActionOptions {\r\n  /**\r\n   * The name of the action.  For example, if the tool is called \"example\",\r\n   * then the \"build\" action might be invoked as: \"example build -q --some-other-option\"\r\n   */\r\n  actionName: string;\r\n\r\n  /**\r\n   * A quick summary that is shown on the main help page, which is displayed\r\n   * by the command \"example --help\"\r\n   */\r\n  summary: string;\r\n\r\n  /**\r\n   * A detailed description that is shown on the action help page, which is displayed\r\n   * by the command \"example build --help\", e.g. for actionName=\"build\".\r\n   */\r\n  documentation: string;\r\n}\r\n\r\n/**\r\n * Represents a sub-command that is part of the CommandLineParser command line.\r\n * Applications should create subclasses of CommandLineAction corresponding to\r\n * each action that they want to expose.\r\n *\r\n * The action name should be comprised of lower case words separated by hyphens\r\n * or colons. The name should include an English verb (e.g. \"deploy\"). Use a\r\n * hyphen to separate words (e.g. \"upload-docs\"). A group of related commands\r\n * can be prefixed with a colon (e.g. \"docs:generate\", \"docs:deploy\",\r\n * \"docs:serve\", etc).\r\n *\r\n * @public\r\n */\r\nexport abstract class CommandLineAction extends CommandLineParameterProvider {\r\n  // Example: \"do-something\"\r\n  private static _actionNameRegExp: RegExp = /^[a-z][a-z0-9]*([-:][a-z0-9]+)*$/;\r\n\r\n  /** {@inheritDoc ICommandLineActionOptions.actionName} */\r\n  public readonly actionName: string;\r\n\r\n  /** {@inheritDoc ICommandLineActionOptions.summary} */\r\n  public readonly summary: string;\r\n\r\n  /** {@inheritDoc ICommandLineActionOptions.documentation} */\r\n  public readonly documentation: string;\r\n\r\n  private _argumentParser: argparse.ArgumentParser | undefined;\r\n\r\n  public constructor(options: ICommandLineActionOptions) {\r\n    super();\r\n\r\n    if (!CommandLineAction._actionNameRegExp.test(options.actionName)) {\r\n      throw new Error(\r\n        `Invalid action name \"${options.actionName}\". ` +\r\n          `The name must be comprised of lower-case words optionally separated by hyphens or colons.`\r\n      );\r\n    }\r\n\r\n    this.actionName = options.actionName;\r\n    this.summary = options.summary;\r\n    this.documentation = options.documentation;\r\n\r\n    this._argumentParser = undefined;\r\n  }\r\n\r\n  /**\r\n   * This is called internally by CommandLineParser.addAction()\r\n   * @internal\r\n   */\r\n  public _buildParser(actionsSubParser: argparse.SubParser): void {\r\n    this._argumentParser = actionsSubParser.addParser(this.actionName, {\r\n      help: this.summary,\r\n      description: this.documentation\r\n    });\r\n\r\n    this.onDefineParameters();\r\n  }\r\n\r\n  /**\r\n   * This is called internally by CommandLineParser.execute()\r\n   * @internal\r\n   */\r\n  public _processParsedData(data: ICommandLineParserData): void {\r\n    super._processParsedData(data);\r\n  }\r\n\r\n  /**\r\n   * Invoked by CommandLineParser.onExecute().\r\n   * @internal\r\n   */\r\n  public _execute(): Promise<void> {\r\n    return this.onExecute();\r\n  }\r\n\r\n  /**\r\n   * {@inheritDoc CommandLineParameterProvider._getArgumentParser}\r\n   * @internal\r\n   */\r\n  protected _getArgumentParser(): argparse.ArgumentParser {\r\n    // override\r\n    if (!this._argumentParser) {\r\n      // We will improve this in the future\r\n      throw new Error('The CommandLineAction must be added to a CommandLineParser before it can be used');\r\n    }\r\n\r\n    return this._argumentParser;\r\n  }\r\n\r\n  /**\r\n   * {@inheritDoc CommandLineParameterProvider.onDefineParameters}\r\n   */\r\n  protected abstract onDefineParameters(): void;\r\n\r\n  /**\r\n   * Your subclass should implement this hook to perform the operation.\r\n   */\r\n  protected abstract onExecute(): Promise<void>;\r\n}\r\n"]}

package/lib/providers/CommandLineParameterProvider.d.ts

@@ -0,0 +1,202 @@
+import * as argparse from 'argparse';
+import { ICommandLineChoiceDefinition, ICommandLineChoiceListDefinition, ICommandLineIntegerDefinition, ICommandLineIntegerListDefinition, ICommandLineFlagDefinition, ICommandLineStringDefinition, ICommandLineStringListDefinition, ICommandLineRemainderDefinition } from '../parameters/CommandLineDefinition';
+import { CommandLineParameter } from '../parameters/BaseClasses';
+import { CommandLineChoiceParameter } from '../parameters/CommandLineChoiceParameter';
+import { CommandLineChoiceListParameter } from '../parameters/CommandLineChoiceListParameter';
+import { CommandLineIntegerParameter } from '../parameters/CommandLineIntegerParameter';
+import { CommandLineIntegerListParameter } from '../parameters/CommandLineIntegerListParameter';
+import { CommandLineFlagParameter } from '../parameters/CommandLineFlagParameter';
+import { CommandLineStringParameter } from '../parameters/CommandLineStringParameter';
+import { CommandLineStringListParameter } from '../parameters/CommandLineStringListParameter';
+import { CommandLineRemainder } from '../parameters/CommandLineRemainder';
+/**
+ * This is the argparse result data object
+ * @internal
+ */
+export interface ICommandLineParserData {
+    action: string;
+    [key: string]: any;
+}
+/**
+ * This is the common base class for CommandLineAction and CommandLineParser
+ * that provides functionality for defining command-line parameters.
+ *
+ * @public
+ */
+export declare abstract class CommandLineParameterProvider {
+    private static _keyCounter;
+    private _parameters;
+    private _parametersByLongName;
+    private _remainder;
+    /** @internal */
+    constructor();
+    /**
+     * Returns a collection of the parameters that were defined for this object.
+     */
+    get parameters(): ReadonlyArray<CommandLineParameter>;
+    /**
+     * If {@link CommandLineParameterProvider.defineCommandLineRemainder} was called,
+     * this object captures any remaining command line arguments after the recognized portion.
+     */
+    get remainder(): CommandLineRemainder | undefined;
+    /**
+     * Defines a command-line parameter whose value must be a string from a fixed set of
+     * allowable choices (similar to an enum).
+     *
+     * @remarks
+     * Example of a choice parameter:
+     * ```
+     * example-tool --log-level warn
+     * ```
+     */
+    defineChoiceParameter(definition: ICommandLineChoiceDefinition): CommandLineChoiceParameter;
+    /**
+     * Returns the CommandLineChoiceParameter with the specified long name.
+     * @remarks
+     * This method throws an exception if the parameter is not defined.
+     */
+    getChoiceParameter(parameterLongName: string): CommandLineChoiceParameter;
+    /**
+     * Defines a command-line parameter whose value must be a string from a fixed set of
+     * allowable choices (similar to an enum). The parameter can be specified multiple times to
+     * build a list.
+     *
+     * @remarks
+     * Example of a choice list parameter:
+     * ```
+     * example-tool --allow-color red --allow-color green
+     * ```
+     */
+    defineChoiceListParameter(definition: ICommandLineChoiceListDefinition): CommandLineChoiceListParameter;
+    /**
+     * Returns the CommandLineChoiceListParameter with the specified long name.
+     * @remarks
+     * This method throws an exception if the parameter is not defined.
+     */
+    getChoiceListParameter(parameterLongName: string): CommandLineChoiceListParameter;
+    /**
+     * Defines a command-line switch whose boolean value is true if the switch is provided,
+     * and false otherwise.
+     *
+     * @remarks
+     * Example usage of a flag parameter:
+     * ```
+     * example-tool --debug
+     * ```
+     */
+    defineFlagParameter(definition: ICommandLineFlagDefinition): CommandLineFlagParameter;
+    /**
+     * Returns the CommandLineFlagParameter with the specified long name.
+     * @remarks
+     * This method throws an exception if the parameter is not defined.
+     */
+    getFlagParameter(parameterLongName: string): CommandLineFlagParameter;
+    /**
+     * Defines a command-line parameter whose argument is an integer.
+     *
+     * @remarks
+     * Example usage of an integer parameter:
+     * ```
+     * example-tool --max-attempts 5
+     * ```
+     */
+    defineIntegerParameter(definition: ICommandLineIntegerDefinition): CommandLineIntegerParameter;
+    /**
+     * Returns the CommandLineIntegerParameter with the specified long name.
+     * @remarks
+     * This method throws an exception if the parameter is not defined.
+     */
+    getIntegerParameter(parameterLongName: string): CommandLineIntegerParameter;
+    /**
+     * Defines a command-line parameter whose argument is an integer. The parameter can be specified
+     * multiple times to build a list.
+     *
+     * @remarks
+     * Example usage of an integer list parameter:
+     * ```
+     * example-tool --avoid 4 --avoid 13
+     * ```
+     */
+    defineIntegerListParameter(definition: ICommandLineIntegerListDefinition): CommandLineIntegerListParameter;
+    /**
+     * Returns the CommandLineIntegerParameter with the specified long name.
+     * @remarks
+     * This method throws an exception if the parameter is not defined.
+     */
+    getIntegerListParameter(parameterLongName: string): CommandLineIntegerListParameter;
+    /**
+     * Defines a command-line parameter whose argument is a single text string.
+     *
+     * @remarks
+     * Example usage of a string parameter:
+     * ```
+     * example-tool --message "Hello, world!"
+     * ```
+     */
+    defineStringParameter(definition: ICommandLineStringDefinition): CommandLineStringParameter;
+    /**
+     * Returns the CommandLineStringParameter with the specified long name.
+     * @remarks
+     * This method throws an exception if the parameter is not defined.
+     */
+    getStringParameter(parameterLongName: string): CommandLineStringParameter;
+    /**
+     * Defines a command-line parameter whose argument is a single text string.  The parameter can be
+     * specified multiple times to build a list.
+     *
+     * @remarks
+     * Example usage of a string list parameter:
+     * ```
+     * example-tool --add file1.txt --add file2.txt --add file3.txt
+     * ```
+     */
+    defineStringListParameter(definition: ICommandLineStringListDefinition): CommandLineStringListParameter;
+    /**
+     * Defines a rule that captures any remaining command line arguments after the recognized portion.
+     *
+     * @remarks
+     * This feature is useful for commands that pass their arguments along to an external tool, relying on
+     * that tool to perform validation.  (It could also be used to parse parameters without any validation
+     * or documentation, but that is not recommended.)
+     *
+     * Example of capturing the remainder after an optional flag parameter.
+     * ```
+     * example-tool --my-flag this is the remainder
+     * ```
+     *
+     * In the "--help" documentation, the remainder rule will be represented as "...".
+     */
+    defineCommandLineRemainder(definition: ICommandLineRemainderDefinition): CommandLineRemainder;
+    /**
+     * Returns the CommandLineStringListParameter with the specified long name.
+     * @remarks
+     * This method throws an exception if the parameter is not defined.
+     */
+    getStringListParameter(parameterLongName: string): CommandLineStringListParameter;
+    /**
+     * Generates the command-line help text.
+     */
+    renderHelpText(): string;
+    /**
+     * Returns a object which maps the long name of each parameter in this.parameters
+     * to the stringified form of its value. This is useful for logging telemetry, but
+     * it is not the proper way of accessing parameters or their values.
+     */
+    getParameterStringMap(): Record<string, string>;
+    /**
+     * The child class should implement this hook to define its command-line parameters,
+     * e.g. by calling defineFlagParameter().
+     */
+    protected abstract onDefineParameters(): void;
+    /**
+     * Retrieves the argparse object.
+     * @internal
+     */
+    protected abstract _getArgumentParser(): argparse.ArgumentParser;
+    /** @internal */
+    protected _processParsedData(data: ICommandLineParserData): void;
+    private _generateKey;
+    private _getParameter;
+    private _defineParameter;
+}
+//# sourceMappingURL=CommandLineParameterProvider.d.ts.map

package/lib/providers/CommandLineParameterProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandLineParameterProvider.d.ts","sourceRoot":"","sources":["../../src/providers/CommandLineParameterProvider.ts"],"names":[],"mappings":"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"}

package/lib/providers/CommandLineParameterProvider.js

@@ -0,0 +1,374 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandLineParameterProvider = void 0;
+const argparse = __importStar(require("argparse"));
+const BaseClasses_1 = require("../parameters/BaseClasses");
+const CommandLineChoiceParameter_1 = require("../parameters/CommandLineChoiceParameter");
+const CommandLineChoiceListParameter_1 = require("../parameters/CommandLineChoiceListParameter");
+const CommandLineIntegerParameter_1 = require("../parameters/CommandLineIntegerParameter");
+const CommandLineIntegerListParameter_1 = require("../parameters/CommandLineIntegerListParameter");
+const CommandLineFlagParameter_1 = require("../parameters/CommandLineFlagParameter");
+const CommandLineStringParameter_1 = require("../parameters/CommandLineStringParameter");
+const CommandLineStringListParameter_1 = require("../parameters/CommandLineStringListParameter");
+const CommandLineRemainder_1 = require("../parameters/CommandLineRemainder");
+/**
+ * This is the common base class for CommandLineAction and CommandLineParser
+ * that provides functionality for defining command-line parameters.
+ *
+ * @public
+ */
+class CommandLineParameterProvider {
+    /** @internal */
+    // Third party code should not inherit subclasses or call this constructor
+    constructor() {
+        this._parameters = [];
+        this._parametersByLongName = new Map();
+    }
+    /**
+     * Returns a collection of the parameters that were defined for this object.
+     */
+    get parameters() {
+        return this._parameters;
+    }
+    /**
+     * If {@link CommandLineParameterProvider.defineCommandLineRemainder} was called,
+     * this object captures any remaining command line arguments after the recognized portion.
+     */
+    get remainder() {
+        return this._remainder;
+    }
+    /**
+     * Defines a command-line parameter whose value must be a string from a fixed set of
+     * allowable choices (similar to an enum).
+     *
+     * @remarks
+     * Example of a choice parameter:
+     * ```
+     * example-tool --log-level warn
+     * ```
+     */
+    defineChoiceParameter(definition) {
+        const parameter = new CommandLineChoiceParameter_1.CommandLineChoiceParameter(definition);
+        this._defineParameter(parameter);
+        return parameter;
+    }
+    /**
+     * Returns the CommandLineChoiceParameter with the specified long name.
+     * @remarks
+     * This method throws an exception if the parameter is not defined.
+     */
+    getChoiceParameter(parameterLongName) {
+        return this._getParameter(parameterLongName, BaseClasses_1.CommandLineParameterKind.Choice);
+    }
+    /**
+     * Defines a command-line parameter whose value must be a string from a fixed set of
+     * allowable choices (similar to an enum). The parameter can be specified multiple times to
+     * build a list.
+     *
+     * @remarks
+     * Example of a choice list parameter:
+     * ```
+     * example-tool --allow-color red --allow-color green
+     * ```
+     */
+    defineChoiceListParameter(definition) {
+        const parameter = new CommandLineChoiceListParameter_1.CommandLineChoiceListParameter(definition);
+        this._defineParameter(parameter);
+        return parameter;
+    }
+    /**
+     * Returns the CommandLineChoiceListParameter with the specified long name.
+     * @remarks
+     * This method throws an exception if the parameter is not defined.
+     */
+    getChoiceListParameter(parameterLongName) {
+        return this._getParameter(parameterLongName, BaseClasses_1.CommandLineParameterKind.ChoiceList);
+    }
+    /**
+     * Defines a command-line switch whose boolean value is true if the switch is provided,
+     * and false otherwise.
+     *
+     * @remarks
+     * Example usage of a flag parameter:
+     * ```
+     * example-tool --debug
+     * ```
+     */
+    defineFlagParameter(definition) {
+        const parameter = new CommandLineFlagParameter_1.CommandLineFlagParameter(definition);
+        this._defineParameter(parameter);
+        return parameter;
+    }
+    /**
+     * Returns the CommandLineFlagParameter with the specified long name.
+     * @remarks
+     * This method throws an exception if the parameter is not defined.
+     */
+    getFlagParameter(parameterLongName) {
+        return this._getParameter(parameterLongName, BaseClasses_1.CommandLineParameterKind.Flag);
+    }
+    /**
+     * Defines a command-line parameter whose argument is an integer.
+     *
+     * @remarks
+     * Example usage of an integer parameter:
+     * ```
+     * example-tool --max-attempts 5
+     * ```
+     */
+    defineIntegerParameter(definition) {
+        const parameter = new CommandLineIntegerParameter_1.CommandLineIntegerParameter(definition);
+        this._defineParameter(parameter);
+        return parameter;
+    }
+    /**
+     * Returns the CommandLineIntegerParameter with the specified long name.
+     * @remarks
+     * This method throws an exception if the parameter is not defined.
+     */
+    getIntegerParameter(parameterLongName) {
+        return this._getParameter(parameterLongName, BaseClasses_1.CommandLineParameterKind.Integer);
+    }
+    /**
+     * Defines a command-line parameter whose argument is an integer. The parameter can be specified
+     * multiple times to build a list.
+     *
+     * @remarks
+     * Example usage of an integer list parameter:
+     * ```
+     * example-tool --avoid 4 --avoid 13
+     * ```
+     */
+    defineIntegerListParameter(definition) {
+        const parameter = new CommandLineIntegerListParameter_1.CommandLineIntegerListParameter(definition);
+        this._defineParameter(parameter);
+        return parameter;
+    }
+    /**
+     * Returns the CommandLineIntegerParameter with the specified long name.
+     * @remarks
+     * This method throws an exception if the parameter is not defined.
+     */
+    getIntegerListParameter(parameterLongName) {
+        return this._getParameter(parameterLongName, BaseClasses_1.CommandLineParameterKind.IntegerList);
+    }
+    /**
+     * Defines a command-line parameter whose argument is a single text string.
+     *
+     * @remarks
+     * Example usage of a string parameter:
+     * ```
+     * example-tool --message "Hello, world!"
+     * ```
+     */
+    defineStringParameter(definition) {
+        const parameter = new CommandLineStringParameter_1.CommandLineStringParameter(definition);
+        this._defineParameter(parameter);
+        return parameter;
+    }
+    /**
+     * Returns the CommandLineStringParameter with the specified long name.
+     * @remarks
+     * This method throws an exception if the parameter is not defined.
+     */
+    getStringParameter(parameterLongName) {
+        return this._getParameter(parameterLongName, BaseClasses_1.CommandLineParameterKind.String);
+    }
+    /**
+     * Defines a command-line parameter whose argument is a single text string.  The parameter can be
+     * specified multiple times to build a list.
+     *
+     * @remarks
+     * Example usage of a string list parameter:
+     * ```
+     * example-tool --add file1.txt --add file2.txt --add file3.txt
+     * ```
+     */
+    defineStringListParameter(definition) {
+        const parameter = new CommandLineStringListParameter_1.CommandLineStringListParameter(definition);
+        this._defineParameter(parameter);
+        return parameter;
+    }
+    /**
+     * Defines a rule that captures any remaining command line arguments after the recognized portion.
+     *
+     * @remarks
+     * This feature is useful for commands that pass their arguments along to an external tool, relying on
+     * that tool to perform validation.  (It could also be used to parse parameters without any validation
+     * or documentation, but that is not recommended.)
+     *
+     * Example of capturing the remainder after an optional flag parameter.
+     * ```
+     * example-tool --my-flag this is the remainder
+     * ```
+     *
+     * In the "--help" documentation, the remainder rule will be represented as "...".
+     */
+    defineCommandLineRemainder(definition) {
+        if (this._remainder) {
+            throw new Error('defineRemainingArguments() has already been called for this provider');
+        }
+        this._remainder = new CommandLineRemainder_1.CommandLineRemainder(definition);
+        const argparseOptions = {
+            help: this._remainder.description,
+            nargs: argparse.Const.REMAINDER,
+            metavar: '"..."'
+        };
+        this._getArgumentParser().addArgument(argparse.Const.REMAINDER, argparseOptions);
+        return this._remainder;
+    }
+    /**
+     * Returns the CommandLineStringListParameter with the specified long name.
+     * @remarks
+     * This method throws an exception if the parameter is not defined.
+     */
+    getStringListParameter(parameterLongName) {
+        return this._getParameter(parameterLongName, BaseClasses_1.CommandLineParameterKind.StringList);
+    }
+    /**
+     * Generates the command-line help text.
+     */
+    renderHelpText() {
+        return this._getArgumentParser().formatHelp();
+    }
+    /**
+     * Returns a object which maps the long name of each parameter in this.parameters
+     * to the stringified form of its value. This is useful for logging telemetry, but
+     * it is not the proper way of accessing parameters or their values.
+     */
+    getParameterStringMap() {
+        const parameterMap = {};
+        for (const parameter of this.parameters) {
+            switch (parameter.kind) {
+                case BaseClasses_1.CommandLineParameterKind.Flag:
+                case BaseClasses_1.CommandLineParameterKind.Choice:
+                case BaseClasses_1.CommandLineParameterKind.String:
+                case BaseClasses_1.CommandLineParameterKind.Integer:
+                    parameterMap[parameter.longName] = JSON.stringify(parameter.value);
+                    break;
+                case BaseClasses_1.CommandLineParameterKind.StringList:
+                case BaseClasses_1.CommandLineParameterKind.IntegerList:
+                case BaseClasses_1.CommandLineParameterKind.ChoiceList:
+                    const arrayValue = parameter.values;
+                    parameterMap[parameter.longName] = arrayValue ? arrayValue.join(',') : '';
+                    break;
+            }
+        }
+        return parameterMap;
+    }
+    /** @internal */
+    _processParsedData(data) {
+        // Fill in the values for the parameters
+        for (const parameter of this._parameters) {
+            const value = data[parameter._parserKey]; // eslint-disable-line @typescript-eslint/no-explicit-any
+            parameter._setValue(value);
+        }
+        if (this.remainder) {
+            this.remainder._setValue(data[argparse.Const.REMAINDER]);
+        }
+    }
+    _generateKey() {
+        return 'key_' + (CommandLineParameterProvider._keyCounter++).toString();
+    }
+    _getParameter(parameterLongName, expectedKind) {
+        const parameter = this._parametersByLongName.get(parameterLongName);
+        if (!parameter) {
+            throw new Error(`The parameter "${parameterLongName}" is not defined`);
+        }
+        if (parameter.kind !== expectedKind) {
+            throw new Error(`The parameter "${parameterLongName}" is of type "${BaseClasses_1.CommandLineParameterKind[parameter.kind]}"` +
+                ` whereas the caller was expecting "${BaseClasses_1.CommandLineParameterKind[expectedKind]}".`);
+        }
+        return parameter;
+    }
+    _defineParameter(parameter) {
+        if (this._remainder) {
+            throw new Error('defineCommandLineRemainder() was already called for this provider;' +
+                ' no further parameters can be defined');
+        }
+        const names = [];
+        if (parameter.shortName) {
+            names.push(parameter.shortName);
+        }
+        names.push(parameter.longName);
+        parameter._parserKey = this._generateKey();
+        let finalDescription = parameter.description;
+        const supplementaryNotes = [];
+        parameter._getSupplementaryNotes(supplementaryNotes);
+        if (supplementaryNotes.length > 0) {
+            // If they left the period off the end of their sentence, then add one.
+            if (finalDescription.match(/[a-z0-9]"?\s*$/i)) {
+                finalDescription = finalDescription.trimRight() + '.';
+            }
+            // Append the supplementary text
+            finalDescription += ' ' + supplementaryNotes.join(' ');
+        }
+        // NOTE: Our "environmentVariable" feature takes precedence over argparse's "defaultValue",
+        // so we have to reimplement that feature.
+        const argparseOptions = {
+            help: finalDescription,
+            dest: parameter._parserKey,
+            metavar: parameter.argumentName || undefined,
+            required: parameter.required
+        };
+        switch (parameter.kind) {
+            case BaseClasses_1.CommandLineParameterKind.Choice: {
+                const choiceParameter = parameter;
+                argparseOptions.choices = choiceParameter.alternatives;
+                break;
+            }
+            case BaseClasses_1.CommandLineParameterKind.ChoiceList: {
+                const choiceParameter = parameter;
+                argparseOptions.choices = choiceParameter.alternatives;
+                argparseOptions.action = 'append';
+                break;
+            }
+            case BaseClasses_1.CommandLineParameterKind.Flag:
+                argparseOptions.action = 'storeTrue';
+                break;
+            case BaseClasses_1.CommandLineParameterKind.Integer:
+                argparseOptions.type = 'int';
+                break;
+            case BaseClasses_1.CommandLineParameterKind.IntegerList:
+                argparseOptions.type = 'int';
+                argparseOptions.action = 'append';
+                break;
+            case BaseClasses_1.CommandLineParameterKind.String:
+                break;
+            case BaseClasses_1.CommandLineParameterKind.StringList:
+                argparseOptions.action = 'append';
+                break;
+        }
+        const argumentParser = this._getArgumentParser();
+        argumentParser.addArgument(names, Object.assign({}, argparseOptions));
+        if (parameter.undocumentedSynonyms && parameter.undocumentedSynonyms.length > 0) {
+            argumentParser.addArgument(parameter.undocumentedSynonyms, Object.assign(Object.assign({}, argparseOptions), { help: argparse.Const.SUPPRESS }));
+        }
+        this._parameters.push(parameter);
+        this._parametersByLongName.set(parameter.longName, parameter);
+    }
+}
+exports.CommandLineParameterProvider = CommandLineParameterProvider;
+CommandLineParameterProvider._keyCounter = 0;
+//# sourceMappingURL=CommandLineParameterProvider.js.map