@rushstack/ts-command-line 4.9.1

package/dist/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.18.9"
+    }
+  ]
+}

package/lib/CommandLineHelper.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Helpers for working with the ts-command-line API.
+ *
+ * @public
+ */
+export declare class CommandLineHelper {
+    /**
+     * Returns true if the current command line action is tab-complete.
+     *
+     * @public
+     */
+    static isTabCompletionActionRequest(argv: string[]): boolean;
+}
+//# sourceMappingURL=CommandLineHelper.d.ts.map

package/lib/CommandLineHelper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandLineHelper.d.ts","sourceRoot":"","sources":["../src/CommandLineHelper.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,qBAAa,iBAAiB;IAC5B;;;;OAIG;WACW,4BAA4B,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO;CAGpE"}

package/lib/CommandLineHelper.js

@@ -0,0 +1,22 @@
+"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.CommandLineHelper = void 0;
+/**
+ * Helpers for working with the ts-command-line API.
+ *
+ * @public
+ */
+class CommandLineHelper {
+    /**
+     * Returns true if the current command line action is tab-complete.
+     *
+     * @public
+     */
+    static isTabCompletionActionRequest(argv) {
+        return argv && argv.length > 2 && argv[2] === "tab-complete" /* TabCompletionActionName */;
+    }
+}
+exports.CommandLineHelper = CommandLineHelper;
+//# sourceMappingURL=CommandLineHelper.js.map

package/lib/CommandLineHelper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandLineHelper.js","sourceRoot":"","sources":["../src/CommandLineHelper.ts"],"names":[],"mappings":";AAAA,4FAA4F;AAC5F,2DAA2D;;;AAI3D;;;;GAIG;AACH,MAAa,iBAAiB;IAC5B;;;;OAIG;IACI,MAAM,CAAC,4BAA4B,CAAC,IAAc;QACvD,OAAO,IAAI,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,iDAAiD,CAAC;IAC7F,CAAC;CACF;AATD,8CASC","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 { CommandLineConstants } from './Constants';\r\n\r\n/**\r\n * Helpers for working with the ts-command-line API.\r\n *\r\n * @public\r\n */\r\nexport class CommandLineHelper {\r\n  /**\r\n   * Returns true if the current command line action is tab-complete.\r\n   *\r\n   * @public\r\n   */\r\n  public static isTabCompletionActionRequest(argv: string[]): boolean {\r\n    return argv && argv.length > 2 && argv[2] === CommandLineConstants.TabCompletionActionName;\r\n  }\r\n}\r\n"]}

package/lib/Constants.d.ts

@@ -0,0 +1,12 @@
+/**
+ * String constants for command line processing.
+ *
+ * @public
+ */
+export declare const enum CommandLineConstants {
+    /**
+     * The name of the built-in action that serves suggestions for tab-completion
+     */
+    TabCompletionActionName = "tab-complete"
+}
+//# sourceMappingURL=Constants.d.ts.map

package/lib/Constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Constants.d.ts","sourceRoot":"","sources":["../src/Constants.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,0BAAkB,oBAAoB;IACpC;;OAEG;IACH,uBAAuB,iBAAiB;CACzC"}

package/lib/Constants.js

@@ -0,0 +1,5 @@
+"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 });
+//# sourceMappingURL=Constants.js.map

package/lib/Constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Constants.js","sourceRoot":"","sources":["../src/Constants.ts"],"names":[],"mappings":";AAAA,4FAA4F;AAC5F,2DAA2D","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\n/**\r\n * String constants for command line processing.\r\n *\r\n * @public\r\n */\r\nexport const enum CommandLineConstants {\r\n  /**\r\n   * The name of the built-in action that serves suggestions for tab-completion\r\n   */\r\n  TabCompletionActionName = 'tab-complete'\r\n}\r\n"]}

package/lib/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * An object-oriented command-line parser for TypeScript projects.
+ *
+ * @packageDocumentation
+ */
+export { CommandLineAction, ICommandLineActionOptions } from './providers/CommandLineAction';
+export { IBaseCommandLineDefinition, IBaseCommandLineDefinitionWithArgument, ICommandLineFlagDefinition, ICommandLineStringDefinition, ICommandLineStringListDefinition, ICommandLineIntegerDefinition, ICommandLineIntegerListDefinition, ICommandLineChoiceDefinition, ICommandLineChoiceListDefinition, ICommandLineRemainderDefinition } from './parameters/CommandLineDefinition';
+export { CommandLineParameterKind, CommandLineParameter, CommandLineParameterWithArgument } from './parameters/BaseClasses';
+export { CommandLineFlagParameter } from './parameters/CommandLineFlagParameter';
+export { CommandLineStringParameter } from './parameters/CommandLineStringParameter';
+export { CommandLineStringListParameter } from './parameters/CommandLineStringListParameter';
+export { CommandLineIntegerParameter } from './parameters/CommandLineIntegerParameter';
+export { CommandLineIntegerListParameter } from './parameters/CommandLineIntegerListParameter';
+export { CommandLineChoiceParameter } from './parameters/CommandLineChoiceParameter';
+export { CommandLineChoiceListParameter } from './parameters/CommandLineChoiceListParameter';
+export { CommandLineRemainder } from './parameters/CommandLineRemainder';
+export { CommandLineParameterProvider, ICommandLineParserData as _ICommandLineParserData } from './providers/CommandLineParameterProvider';
+export { ICommandLineParserOptions, CommandLineParser } from './providers/CommandLineParser';
+export { DynamicCommandLineAction } from './providers/DynamicCommandLineAction';
+export { DynamicCommandLineParser } from './providers/DynamicCommandLineParser';
+export { CommandLineConstants } from './Constants';
+export { CommandLineHelper } from './CommandLineHelper';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AAEH,OAAO,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAE7F,OAAO,EACL,0BAA0B,EAC1B,sCAAsC,EACtC,0BAA0B,EAC1B,4BAA4B,EAC5B,gCAAgC,EAChC,6BAA6B,EAC7B,iCAAiC,EACjC,4BAA4B,EAC5B,gCAAgC,EAChC,+BAA+B,EAChC,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EACL,wBAAwB,EACxB,oBAAoB,EACpB,gCAAgC,EACjC,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AACjF,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AACrF,OAAO,EAAE,8BAA8B,EAAE,MAAM,6CAA6C,CAAC;AAC7F,OAAO,EAAE,2BAA2B,EAAE,MAAM,0CAA0C,CAAC;AACvF,OAAO,EAAE,+BAA+B,EAAE,MAAM,8CAA8C,CAAC;AAC/F,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AACrF,OAAO,EAAE,8BAA8B,EAAE,MAAM,6CAA6C,CAAC;AAC7F,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAEzE,OAAO,EACL,4BAA4B,EAC5B,sBAAsB,IAAI,uBAAuB,EAClD,MAAM,0CAA0C,CAAC;AAElD,OAAO,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAE7F,OAAO,EAAE,wBAAwB,EAAE,MAAM,sCAAsC,CAAC;AAEhF,OAAO,EAAE,wBAAwB,EAAE,MAAM,sCAAsC,CAAC;AAEhF,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC"}

package/lib/index.js

@@ -0,0 +1,42 @@
+"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 });
+/**
+ * An object-oriented command-line parser for TypeScript projects.
+ *
+ * @packageDocumentation
+ */
+var CommandLineAction_1 = require("./providers/CommandLineAction");
+Object.defineProperty(exports, "CommandLineAction", { enumerable: true, get: function () { return CommandLineAction_1.CommandLineAction; } });
+var BaseClasses_1 = require("./parameters/BaseClasses");
+Object.defineProperty(exports, "CommandLineParameterKind", { enumerable: true, get: function () { return BaseClasses_1.CommandLineParameterKind; } });
+Object.defineProperty(exports, "CommandLineParameter", { enumerable: true, get: function () { return BaseClasses_1.CommandLineParameter; } });
+Object.defineProperty(exports, "CommandLineParameterWithArgument", { enumerable: true, get: function () { return BaseClasses_1.CommandLineParameterWithArgument; } });
+var CommandLineFlagParameter_1 = require("./parameters/CommandLineFlagParameter");
+Object.defineProperty(exports, "CommandLineFlagParameter", { enumerable: true, get: function () { return CommandLineFlagParameter_1.CommandLineFlagParameter; } });
+var CommandLineStringParameter_1 = require("./parameters/CommandLineStringParameter");
+Object.defineProperty(exports, "CommandLineStringParameter", { enumerable: true, get: function () { return CommandLineStringParameter_1.CommandLineStringParameter; } });
+var CommandLineStringListParameter_1 = require("./parameters/CommandLineStringListParameter");
+Object.defineProperty(exports, "CommandLineStringListParameter", { enumerable: true, get: function () { return CommandLineStringListParameter_1.CommandLineStringListParameter; } });
+var CommandLineIntegerParameter_1 = require("./parameters/CommandLineIntegerParameter");
+Object.defineProperty(exports, "CommandLineIntegerParameter", { enumerable: true, get: function () { return CommandLineIntegerParameter_1.CommandLineIntegerParameter; } });
+var CommandLineIntegerListParameter_1 = require("./parameters/CommandLineIntegerListParameter");
+Object.defineProperty(exports, "CommandLineIntegerListParameter", { enumerable: true, get: function () { return CommandLineIntegerListParameter_1.CommandLineIntegerListParameter; } });
+var CommandLineChoiceParameter_1 = require("./parameters/CommandLineChoiceParameter");
+Object.defineProperty(exports, "CommandLineChoiceParameter", { enumerable: true, get: function () { return CommandLineChoiceParameter_1.CommandLineChoiceParameter; } });
+var CommandLineChoiceListParameter_1 = require("./parameters/CommandLineChoiceListParameter");
+Object.defineProperty(exports, "CommandLineChoiceListParameter", { enumerable: true, get: function () { return CommandLineChoiceListParameter_1.CommandLineChoiceListParameter; } });
+var CommandLineRemainder_1 = require("./parameters/CommandLineRemainder");
+Object.defineProperty(exports, "CommandLineRemainder", { enumerable: true, get: function () { return CommandLineRemainder_1.CommandLineRemainder; } });
+var CommandLineParameterProvider_1 = require("./providers/CommandLineParameterProvider");
+Object.defineProperty(exports, "CommandLineParameterProvider", { enumerable: true, get: function () { return CommandLineParameterProvider_1.CommandLineParameterProvider; } });
+var CommandLineParser_1 = require("./providers/CommandLineParser");
+Object.defineProperty(exports, "CommandLineParser", { enumerable: true, get: function () { return CommandLineParser_1.CommandLineParser; } });
+var DynamicCommandLineAction_1 = require("./providers/DynamicCommandLineAction");
+Object.defineProperty(exports, "DynamicCommandLineAction", { enumerable: true, get: function () { return DynamicCommandLineAction_1.DynamicCommandLineAction; } });
+var DynamicCommandLineParser_1 = require("./providers/DynamicCommandLineParser");
+Object.defineProperty(exports, "DynamicCommandLineParser", { enumerable: true, get: function () { return DynamicCommandLineParser_1.DynamicCommandLineParser; } });
+var CommandLineHelper_1 = require("./CommandLineHelper");
+Object.defineProperty(exports, "CommandLineHelper", { enumerable: true, get: function () { return CommandLineHelper_1.CommandLineHelper; } });
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,4FAA4F;AAC5F,2DAA2D;;AAE3D;;;;GAIG;AAEH,mEAA6F;AAApF,sHAAA,iBAAiB,OAAA;AAe1B,wDAIkC;AAHhC,uHAAA,wBAAwB,OAAA;AACxB,mHAAA,oBAAoB,OAAA;AACpB,+HAAA,gCAAgC,OAAA;AAGlC,kFAAiF;AAAxE,oIAAA,wBAAwB,OAAA;AACjC,sFAAqF;AAA5E,wIAAA,0BAA0B,OAAA;AACnC,8FAA6F;AAApF,gJAAA,8BAA8B,OAAA;AACvC,wFAAuF;AAA9E,0IAAA,2BAA2B,OAAA;AACpC,gGAA+F;AAAtF,kJAAA,+BAA+B,OAAA;AACxC,sFAAqF;AAA5E,wIAAA,0BAA0B,OAAA;AACnC,8FAA6F;AAApF,gJAAA,8BAA8B,OAAA;AACvC,0EAAyE;AAAhE,4HAAA,oBAAoB,OAAA;AAE7B,yFAGkD;AAFhD,4IAAA,4BAA4B,OAAA;AAI9B,mEAA6F;AAAzD,sHAAA,iBAAiB,OAAA;AAErD,iFAAgF;AAAvE,oIAAA,wBAAwB,OAAA;AAEjC,iFAAgF;AAAvE,oIAAA,wBAAwB,OAAA;AAIjC,yDAAwD;AAA/C,sHAAA,iBAAiB,OAAA","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\n/**\r\n * An object-oriented command-line parser for TypeScript projects.\r\n *\r\n * @packageDocumentation\r\n */\r\n\r\nexport { CommandLineAction, ICommandLineActionOptions } from './providers/CommandLineAction';\r\n\r\nexport {\r\n  IBaseCommandLineDefinition,\r\n  IBaseCommandLineDefinitionWithArgument,\r\n  ICommandLineFlagDefinition,\r\n  ICommandLineStringDefinition,\r\n  ICommandLineStringListDefinition,\r\n  ICommandLineIntegerDefinition,\r\n  ICommandLineIntegerListDefinition,\r\n  ICommandLineChoiceDefinition,\r\n  ICommandLineChoiceListDefinition,\r\n  ICommandLineRemainderDefinition\r\n} from './parameters/CommandLineDefinition';\r\n\r\nexport {\r\n  CommandLineParameterKind,\r\n  CommandLineParameter,\r\n  CommandLineParameterWithArgument\r\n} from './parameters/BaseClasses';\r\n\r\nexport { CommandLineFlagParameter } from './parameters/CommandLineFlagParameter';\r\nexport { CommandLineStringParameter } from './parameters/CommandLineStringParameter';\r\nexport { CommandLineStringListParameter } from './parameters/CommandLineStringListParameter';\r\nexport { CommandLineIntegerParameter } from './parameters/CommandLineIntegerParameter';\r\nexport { CommandLineIntegerListParameter } from './parameters/CommandLineIntegerListParameter';\r\nexport { CommandLineChoiceParameter } from './parameters/CommandLineChoiceParameter';\r\nexport { CommandLineChoiceListParameter } from './parameters/CommandLineChoiceListParameter';\r\nexport { CommandLineRemainder } from './parameters/CommandLineRemainder';\r\n\r\nexport {\r\n  CommandLineParameterProvider,\r\n  ICommandLineParserData as _ICommandLineParserData\r\n} from './providers/CommandLineParameterProvider';\r\n\r\nexport { ICommandLineParserOptions, CommandLineParser } from './providers/CommandLineParser';\r\n\r\nexport { DynamicCommandLineAction } from './providers/DynamicCommandLineAction';\r\n\r\nexport { DynamicCommandLineParser } from './providers/DynamicCommandLineParser';\r\n\r\nexport { CommandLineConstants } from './Constants';\r\n\r\nexport { CommandLineHelper } from './CommandLineHelper';\r\n"]}

package/lib/parameters/BaseClasses.d.ts

@@ -0,0 +1,100 @@
+import { IBaseCommandLineDefinition, IBaseCommandLineDefinitionWithArgument } from './CommandLineDefinition';
+/**
+ * Identifies the kind of a CommandLineParameter.
+ * @public
+ */
+export declare enum CommandLineParameterKind {
+    /** Indicates a CommandLineChoiceParameter */
+    Choice = 0,
+    /** Indicates a CommandLineFlagParameter */
+    Flag = 1,
+    /** Indicates a CommandLineIntegerParameter */
+    Integer = 2,
+    /** Indicates a CommandLineStringParameter */
+    String = 3,
+    /** Indicates a CommandLineStringListParameter */
+    StringList = 4,
+    /** Indicates a CommandLineChoiceListParameter */
+    ChoiceList = 5,
+    /** Indicates a CommandLineIntegerListParameter */
+    IntegerList = 6
+}
+/**
+ * The base class for the various command-line parameter types.
+ * @public
+ */
+export declare abstract class CommandLineParameter {
+    private static _longNameRegExp;
+    private static _shortNameRegExp;
+    private static _environmentVariableRegExp;
+    /**
+     * A unique internal key used to retrieve the value from the parser's dictionary.
+     * @internal
+     */
+    _parserKey: string | undefined;
+    /** {@inheritDoc IBaseCommandLineDefinition.parameterLongName} */
+    readonly longName: string;
+    /** {@inheritDoc IBaseCommandLineDefinition.parameterShortName} */
+    readonly shortName: string | undefined;
+    /** {@inheritDoc IBaseCommandLineDefinition.description} */
+    readonly description: string;
+    /** {@inheritDoc IBaseCommandLineDefinition.required} */
+    readonly required: boolean;
+    /** {@inheritDoc IBaseCommandLineDefinition.environmentVariable} */
+    readonly environmentVariable: string | undefined;
+    /** {@inheritDoc IBaseCommandLineDefinition.undocumentedSynonyms } */
+    readonly undocumentedSynonyms: string[] | undefined;
+    /** @internal */
+    constructor(definition: IBaseCommandLineDefinition);
+    /**
+     * Called internally by CommandLineParameterProvider._processParsedData()
+     * @internal
+     */
+    abstract _setValue(data: any): void;
+    /**
+     * Returns additional text used by the help formatter.
+     * @internal
+     */
+    _getSupplementaryNotes(supplementaryNotes: string[]): void;
+    /**
+     * Indicates the type of parameter.
+     */
+    abstract get kind(): CommandLineParameterKind;
+    /**
+     * Append the parsed values to the provided string array.
+     * @remarks
+     * Sometimes a command line parameter is not used directly, but instead gets passed through to another
+     * tool that will use it.  For example if our parameter comes in as "--max-count 3", then we might want to
+     * call `child_process.spawn()` and append ["--max-count", "3"] to the args array for that tool.
+     * appendToArgList() appends zero or more strings to the provided array, based on the input command-line
+     * that we parsed.
+     *
+     * If the parameter was omitted from our command-line and has no default value, then
+     * nothing will be appended.  If the short name was used, the long name will be appended instead.
+     * @param argList - the parsed strings will be appended to this string array
+     */
+    abstract appendToArgList(argList: string[]): void;
+    /**
+     * Internal usage only.  Used to report unexpected output from the argparse library.
+     */
+    protected reportInvalidData(data: any): never;
+    protected validateDefaultValue(hasDefaultValue: boolean): void;
+}
+/**
+ * The common base class for parameters types that receive an argument.
+ *
+ * @remarks
+ * An argument is an accompanying command-line token, such as "123" in the
+ * example "--max-count 123".
+ * @public
+ */
+export declare abstract class CommandLineParameterWithArgument extends CommandLineParameter {
+    private static _invalidArgumentNameRegExp;
+    /** {@inheritDoc IBaseCommandLineDefinitionWithArgument.argumentName} */
+    readonly argumentName: string;
+    /** {@inheritDoc IBaseCommandLineDefinitionWithArgument.completions} */
+    readonly completions: (() => Promise<string[]>) | undefined;
+    /** @internal */
+    constructor(definition: IBaseCommandLineDefinitionWithArgument);
+}
+//# sourceMappingURL=BaseClasses.d.ts.map

package/lib/parameters/BaseClasses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseClasses.d.ts","sourceRoot":"","sources":["../../src/parameters/BaseClasses.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,0BAA0B,EAAE,sCAAsC,EAAE,MAAM,yBAAyB,CAAC;AAE7G;;;GAGG;AACH,oBAAY,wBAAwB;IAClC,6CAA6C;IAC7C,MAAM,IAAA;IACN,2CAA2C;IAC3C,IAAI,IAAA;IACJ,8CAA8C;IAC9C,OAAO,IAAA;IACP,6CAA6C;IAC7C,MAAM,IAAA;IACN,iDAAiD;IACjD,UAAU,IAAA;IACV,iDAAiD;IACjD,UAAU,IAAA;IACV,kDAAkD;IAClD,WAAW,IAAA;CACZ;AAED;;;GAGG;AACH,8BAAsB,oBAAoB;IAExC,OAAO,CAAC,MAAM,CAAC,eAAe,CAA8B;IAG5D,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAyB;IAMxD,OAAO,CAAC,MAAM,CAAC,0BAA0B,CAAgC;IAEzE;;;OAGG;IACI,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAEtC,iEAAiE;IACjE,SAAgB,QAAQ,EAAE,MAAM,CAAC;IAEjC,kEAAkE;IAClE,SAAgB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAE9C,2DAA2D;IAC3D,SAAgB,WAAW,EAAE,MAAM,CAAC;IAEpC,wDAAwD;IACxD,SAAgB,QAAQ,EAAE,OAAO,CAAC;IAElC,mEAAmE;IACnE,SAAgB,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAC;IAExD,qEAAqE;IACrE,SAAgB,oBAAoB,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAE3D,gBAAgB;gBACG,UAAU,EAAE,0BAA0B;IA+DzD;;;OAGG;aACa,SAAS,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI;IAE1C;;;OAGG;IACI,sBAAsB,CAAC,kBAAkB,EAAE,MAAM,EAAE,GAAG,IAAI;IAWjE;;OAEG;IACH,aAAoB,IAAI,IAAI,wBAAwB,CAAC;IAErD;;;;;;;;;;;;OAYG;aACa,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI;IAExD;;OAEG;IAEH,SAAS,CAAC,iBAAiB,CAAC,IAAI,EAAE,GAAG,GAAG,KAAK;IAI7C,SAAS,CAAC,oBAAoB,CAAC,eAAe,EAAE,OAAO,GAAG,IAAI;CAY/D;AAED;;;;;;;GAOG;AACH,8BAAsB,gCAAiC,SAAQ,oBAAoB;IAEjF,OAAO,CAAC,MAAM,CAAC,0BAA0B,CAAwB;IAEjE,wEAAwE;IACxE,SAAgB,YAAY,EAAE,MAAM,CAAC;IAErC,uEAAuE;IACvE,SAAgB,WAAW,EAAE,CAAC,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,SAAS,CAAC;IAEnE,gBAAgB;gBACG,UAAU,EAAE,sCAAsC;CAyBtE"}

package/lib/parameters/BaseClasses.js

@@ -0,0 +1,148 @@
+"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.CommandLineParameterWithArgument = exports.CommandLineParameter = exports.CommandLineParameterKind = void 0;
+/**
+ * Identifies the kind of a CommandLineParameter.
+ * @public
+ */
+var CommandLineParameterKind;
+(function (CommandLineParameterKind) {
+    /** Indicates a CommandLineChoiceParameter */
+    CommandLineParameterKind[CommandLineParameterKind["Choice"] = 0] = "Choice";
+    /** Indicates a CommandLineFlagParameter */
+    CommandLineParameterKind[CommandLineParameterKind["Flag"] = 1] = "Flag";
+    /** Indicates a CommandLineIntegerParameter */
+    CommandLineParameterKind[CommandLineParameterKind["Integer"] = 2] = "Integer";
+    /** Indicates a CommandLineStringParameter */
+    CommandLineParameterKind[CommandLineParameterKind["String"] = 3] = "String";
+    /** Indicates a CommandLineStringListParameter */
+    CommandLineParameterKind[CommandLineParameterKind["StringList"] = 4] = "StringList";
+    /** Indicates a CommandLineChoiceListParameter */
+    CommandLineParameterKind[CommandLineParameterKind["ChoiceList"] = 5] = "ChoiceList";
+    /** Indicates a CommandLineIntegerListParameter */
+    CommandLineParameterKind[CommandLineParameterKind["IntegerList"] = 6] = "IntegerList";
+})(CommandLineParameterKind = exports.CommandLineParameterKind || (exports.CommandLineParameterKind = {}));
+/**
+ * The base class for the various command-line parameter types.
+ * @public
+ */
+class CommandLineParameter {
+    /** @internal */
+    constructor(definition) {
+        this.longName = definition.parameterLongName;
+        this.shortName = definition.parameterShortName;
+        this.description = definition.description;
+        this.required = !!definition.required;
+        this.environmentVariable = definition.environmentVariable;
+        this.undocumentedSynonyms = definition.undocumentedSynonyms;
+        if (!CommandLineParameter._longNameRegExp.test(this.longName)) {
+            throw new Error(`Invalid name: "${this.longName}". The parameter long name must be` +
+                ` lower-case and use dash delimiters (e.g. "--do-a-thing")`);
+        }
+        if (this.shortName) {
+            if (!CommandLineParameter._shortNameRegExp.test(this.shortName)) {
+                throw new Error(`Invalid name: "${this.shortName}". The parameter short name must be` +
+                    ` a dash followed by a single upper-case or lower-case letter (e.g. "-a")`);
+            }
+        }
+        if (this.environmentVariable) {
+            if (this.required) {
+                // TODO: This constraint is imposed only because argparse enforces "required" parameters, but
+                // it does not know about ts-command-line environment variable mappings.  We should fix this.
+                throw new Error(`An "environmentVariable" cannot be specified for "${this.longName}"` +
+                    ` because it is a required parameter`);
+            }
+            if (!CommandLineParameter._environmentVariableRegExp.test(this.environmentVariable)) {
+                throw new Error(`Invalid environment variable name: "${this.environmentVariable}". The name must` +
+                    ` consist only of upper-case letters, numbers, and underscores. It may not start with a number.`);
+            }
+        }
+        if (this.undocumentedSynonyms && this.undocumentedSynonyms.length > 0) {
+            if (this.required) {
+                throw new Error('Undocumented synonyms are not allowed on required parameters.');
+            }
+            for (const undocumentedSynonym of this.undocumentedSynonyms) {
+                if (this.longName === undocumentedSynonym) {
+                    throw new Error(`Invalid name: "${undocumentedSynonym}". Undocumented Synonyms must not be the same` +
+                        ` as the the long name.`);
+                }
+                else if (!CommandLineParameter._longNameRegExp.test(undocumentedSynonym)) {
+                    throw new Error(`Invalid name: "${undocumentedSynonym}". All undocumented Synonyms name must be` +
+                        ` lower-case and use dash delimiters (e.g. "--do-a-thing")`);
+                }
+            }
+        }
+    }
+    /**
+     * Returns additional text used by the help formatter.
+     * @internal
+     */
+    _getSupplementaryNotes(supplementaryNotes) {
+        // virtual
+        if (this.environmentVariable !== undefined) {
+            supplementaryNotes.push('This parameter may alternatively be specified via the ' +
+                this.environmentVariable +
+                ' environment variable.');
+        }
+    }
+    /**
+     * Internal usage only.  Used to report unexpected output from the argparse library.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    reportInvalidData(data) {
+        throw new Error(`Unexpected data object for parameter "${this.longName}": ` + JSON.stringify(data));
+    }
+    validateDefaultValue(hasDefaultValue) {
+        if (this.required && hasDefaultValue) {
+            // If a parameter is "required", then the user understands that they always need to
+            // specify a value for this parameter (either via the command line or via an environment variable).
+            // It would be confusing to allow a default value that sometimes allows the "required" parameter
+            // to be omitted.  If you sometimes don't have a suitable default value, then the better approach
+            // is to throw a custom error explaining why the parameter is required in that case.
+            throw new Error(`A default value cannot be specified for "${this.longName}" because it is a "required" parameter`);
+        }
+    }
+}
+exports.CommandLineParameter = CommandLineParameter;
+// Example: "--do-something"
+CommandLineParameter._longNameRegExp = /^-(-[a-z0-9]+)+$/;
+// Example: "-d"
+CommandLineParameter._shortNameRegExp = /^-[a-zA-Z]$/;
+// "Environment variable names used by the utilities in the Shell and Utilities volume of
+// IEEE Std 1003.1-2001 consist solely of uppercase letters, digits, and the '_' (underscore)
+// from the characters defined in Portable Character Set and do not begin with a digit."
+// Example: "THE_SETTING"
+CommandLineParameter._environmentVariableRegExp = /^[A-Z_][A-Z0-9_]*$/;
+/**
+ * The common base class for parameters types that receive an argument.
+ *
+ * @remarks
+ * An argument is an accompanying command-line token, such as "123" in the
+ * example "--max-count 123".
+ * @public
+ */
+class CommandLineParameterWithArgument extends CommandLineParameter {
+    /** @internal */
+    constructor(definition) {
+        super(definition);
+        if (definition.argumentName === '') {
+            throw new Error('The argument name cannot be an empty string. (For the default name, specify undefined.)');
+        }
+        if (definition.argumentName.toUpperCase() !== definition.argumentName) {
+            throw new Error(`Invalid name: "${definition.argumentName}". The argument name must be all upper case.`);
+        }
+        const match = definition.argumentName.match(CommandLineParameterWithArgument._invalidArgumentNameRegExp);
+        if (match) {
+            throw new Error(`The argument name "${definition.argumentName}" contains an invalid character "${match[0]}".` +
+                ` Only upper-case letters, numbers, and underscores are allowed.`);
+        }
+        this.argumentName = definition.argumentName;
+        this.completions = definition.completions;
+    }
+}
+exports.CommandLineParameterWithArgument = CommandLineParameterWithArgument;
+// Matches the first character that *isn't* part of a valid upper-case argument name such as "URL_2"
+CommandLineParameterWithArgument._invalidArgumentNameRegExp = /[^A-Z_0-9]/;
+//# sourceMappingURL=BaseClasses.js.map

package/lib/parameters/BaseClasses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseClasses.js","sourceRoot":"","sources":["../../src/parameters/BaseClasses.ts"],"names":[],"mappings":"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","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 { IBaseCommandLineDefinition, IBaseCommandLineDefinitionWithArgument } from './CommandLineDefinition';\r\n\r\n/**\r\n * Identifies the kind of a CommandLineParameter.\r\n * @public\r\n */\r\nexport enum CommandLineParameterKind {\r\n  /** Indicates a CommandLineChoiceParameter */\r\n  Choice,\r\n  /** Indicates a CommandLineFlagParameter */\r\n  Flag,\r\n  /** Indicates a CommandLineIntegerParameter */\r\n  Integer,\r\n  /** Indicates a CommandLineStringParameter */\r\n  String,\r\n  /** Indicates a CommandLineStringListParameter */\r\n  StringList,\r\n  /** Indicates a CommandLineChoiceListParameter */\r\n  ChoiceList,\r\n  /** Indicates a CommandLineIntegerListParameter */\r\n  IntegerList\r\n}\r\n\r\n/**\r\n * The base class for the various command-line parameter types.\r\n * @public\r\n */\r\nexport abstract class CommandLineParameter {\r\n  // Example: \"--do-something\"\r\n  private static _longNameRegExp: RegExp = /^-(-[a-z0-9]+)+$/;\r\n\r\n  // Example: \"-d\"\r\n  private static _shortNameRegExp: RegExp = /^-[a-zA-Z]$/;\r\n\r\n  // \"Environment variable names used by the utilities in the Shell and Utilities volume of\r\n  // IEEE Std 1003.1-2001 consist solely of uppercase letters, digits, and the '_' (underscore)\r\n  // from the characters defined in Portable Character Set and do not begin with a digit.\"\r\n  // Example: \"THE_SETTING\"\r\n  private static _environmentVariableRegExp: RegExp = /^[A-Z_][A-Z0-9_]*$/;\r\n\r\n  /**\r\n   * A unique internal key used to retrieve the value from the parser's dictionary.\r\n   * @internal\r\n   */\r\n  public _parserKey: string | undefined;\r\n\r\n  /** {@inheritDoc IBaseCommandLineDefinition.parameterLongName} */\r\n  public readonly longName: string;\r\n\r\n  /** {@inheritDoc IBaseCommandLineDefinition.parameterShortName} */\r\n  public readonly shortName: string | undefined;\r\n\r\n  /** {@inheritDoc IBaseCommandLineDefinition.description} */\r\n  public readonly description: string;\r\n\r\n  /** {@inheritDoc IBaseCommandLineDefinition.required} */\r\n  public readonly required: boolean;\r\n\r\n  /** {@inheritDoc IBaseCommandLineDefinition.environmentVariable} */\r\n  public readonly environmentVariable: string | undefined;\r\n\r\n  /** {@inheritDoc IBaseCommandLineDefinition.undocumentedSynonyms } */\r\n  public readonly undocumentedSynonyms: string[] | undefined;\r\n\r\n  /** @internal */\r\n  public constructor(definition: IBaseCommandLineDefinition) {\r\n    this.longName = definition.parameterLongName;\r\n    this.shortName = definition.parameterShortName;\r\n    this.description = definition.description;\r\n    this.required = !!definition.required;\r\n    this.environmentVariable = definition.environmentVariable;\r\n    this.undocumentedSynonyms = definition.undocumentedSynonyms;\r\n\r\n    if (!CommandLineParameter._longNameRegExp.test(this.longName)) {\r\n      throw new Error(\r\n        `Invalid name: \"${this.longName}\". The parameter long name must be` +\r\n          ` lower-case and use dash delimiters (e.g. \"--do-a-thing\")`\r\n      );\r\n    }\r\n\r\n    if (this.shortName) {\r\n      if (!CommandLineParameter._shortNameRegExp.test(this.shortName)) {\r\n        throw new Error(\r\n          `Invalid name: \"${this.shortName}\". The parameter short name must be` +\r\n            ` a dash followed by a single upper-case or lower-case letter (e.g. \"-a\")`\r\n        );\r\n      }\r\n    }\r\n\r\n    if (this.environmentVariable) {\r\n      if (this.required) {\r\n        // TODO: This constraint is imposed only because argparse enforces \"required\" parameters, but\r\n        // it does not know about ts-command-line environment variable mappings.  We should fix this.\r\n        throw new Error(\r\n          `An \"environmentVariable\" cannot be specified for \"${this.longName}\"` +\r\n            ` because it is a required parameter`\r\n        );\r\n      }\r\n\r\n      if (!CommandLineParameter._environmentVariableRegExp.test(this.environmentVariable)) {\r\n        throw new Error(\r\n          `Invalid environment variable name: \"${this.environmentVariable}\". The name must` +\r\n            ` consist only of upper-case letters, numbers, and underscores. It may not start with a number.`\r\n        );\r\n      }\r\n    }\r\n\r\n    if (this.undocumentedSynonyms && this.undocumentedSynonyms.length > 0) {\r\n      if (this.required) {\r\n        throw new Error('Undocumented synonyms are not allowed on required parameters.');\r\n      }\r\n\r\n      for (const undocumentedSynonym of this.undocumentedSynonyms) {\r\n        if (this.longName === undocumentedSynonym) {\r\n          throw new Error(\r\n            `Invalid name: \"${undocumentedSynonym}\". Undocumented Synonyms must not be the same` +\r\n              ` as the the long name.`\r\n          );\r\n        } else if (!CommandLineParameter._longNameRegExp.test(undocumentedSynonym)) {\r\n          throw new Error(\r\n            `Invalid name: \"${undocumentedSynonym}\". All undocumented Synonyms name must be` +\r\n              ` lower-case and use dash delimiters (e.g. \"--do-a-thing\")`\r\n          );\r\n        }\r\n      }\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Called internally by CommandLineParameterProvider._processParsedData()\r\n   * @internal\r\n   */\r\n  public abstract _setValue(data: any): void; // eslint-disable-line @typescript-eslint/no-explicit-any\r\n\r\n  /**\r\n   * Returns additional text used by the help formatter.\r\n   * @internal\r\n   */\r\n  public _getSupplementaryNotes(supplementaryNotes: string[]): void {\r\n    // virtual\r\n    if (this.environmentVariable !== undefined) {\r\n      supplementaryNotes.push(\r\n        'This parameter may alternatively be specified via the ' +\r\n          this.environmentVariable +\r\n          ' environment variable.'\r\n      );\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Indicates the type of parameter.\r\n   */\r\n  public abstract get kind(): CommandLineParameterKind;\r\n\r\n  /**\r\n   * Append the parsed values to the provided string array.\r\n   * @remarks\r\n   * Sometimes a command line parameter is not used directly, but instead gets passed through to another\r\n   * tool that will use it.  For example if our parameter comes in as \"--max-count 3\", then we might want to\r\n   * call `child_process.spawn()` and append [\"--max-count\", \"3\"] to the args array for that tool.\r\n   * appendToArgList() appends zero or more strings to the provided array, based on the input command-line\r\n   * that we parsed.\r\n   *\r\n   * If the parameter was omitted from our command-line and has no default value, then\r\n   * nothing will be appended.  If the short name was used, the long name will be appended instead.\r\n   * @param argList - the parsed strings will be appended to this string array\r\n   */\r\n  public abstract appendToArgList(argList: string[]): void;\r\n\r\n  /**\r\n   * Internal usage only.  Used to report unexpected output from the argparse library.\r\n   */\r\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\r\n  protected reportInvalidData(data: any): never {\r\n    throw new Error(`Unexpected data object for parameter \"${this.longName}\": ` + JSON.stringify(data));\r\n  }\r\n\r\n  protected validateDefaultValue(hasDefaultValue: boolean): void {\r\n    if (this.required && hasDefaultValue) {\r\n      // If a parameter is \"required\", then the user understands that they always need to\r\n      // specify a value for this parameter (either via the command line or via an environment variable).\r\n      // It would be confusing to allow a default value that sometimes allows the \"required\" parameter\r\n      // to be omitted.  If you sometimes don't have a suitable default value, then the better approach\r\n      // is to throw a custom error explaining why the parameter is required in that case.\r\n      throw new Error(\r\n        `A default value cannot be specified for \"${this.longName}\" because it is a \"required\" parameter`\r\n      );\r\n    }\r\n  }\r\n}\r\n\r\n/**\r\n * The common base class for parameters types that receive an argument.\r\n *\r\n * @remarks\r\n * An argument is an accompanying command-line token, such as \"123\" in the\r\n * example \"--max-count 123\".\r\n * @public\r\n */\r\nexport abstract class CommandLineParameterWithArgument extends CommandLineParameter {\r\n  // Matches the first character that *isn't* part of a valid upper-case argument name such as \"URL_2\"\r\n  private static _invalidArgumentNameRegExp: RegExp = /[^A-Z_0-9]/;\r\n\r\n  /** {@inheritDoc IBaseCommandLineDefinitionWithArgument.argumentName} */\r\n  public readonly argumentName: string;\r\n\r\n  /** {@inheritDoc IBaseCommandLineDefinitionWithArgument.completions} */\r\n  public readonly completions: (() => Promise<string[]>) | undefined;\r\n\r\n  /** @internal */\r\n  public constructor(definition: IBaseCommandLineDefinitionWithArgument) {\r\n    super(definition);\r\n\r\n    if (definition.argumentName === '') {\r\n      throw new Error(\r\n        'The argument name cannot be an empty string. (For the default name, specify undefined.)'\r\n      );\r\n    }\r\n    if (definition.argumentName.toUpperCase() !== definition.argumentName) {\r\n      throw new Error(\r\n        `Invalid name: \"${definition.argumentName}\". The argument name must be all upper case.`\r\n      );\r\n    }\r\n    const match: RegExpMatchArray | null = definition.argumentName.match(\r\n      CommandLineParameterWithArgument._invalidArgumentNameRegExp\r\n    );\r\n    if (match) {\r\n      throw new Error(\r\n        `The argument name \"${definition.argumentName}\" contains an invalid character \"${match[0]}\".` +\r\n          ` Only upper-case letters, numbers, and underscores are allowed.`\r\n      );\r\n    }\r\n    this.argumentName = definition.argumentName;\r\n    this.completions = definition.completions;\r\n  }\r\n}\r\n"]}

package/lib/parameters/CommandLineChoiceListParameter.d.ts

@@ -0,0 +1,33 @@
+import { ICommandLineChoiceListDefinition } from './CommandLineDefinition';
+import { CommandLineParameter, CommandLineParameterKind } from './BaseClasses';
+/**
+ * The data type returned by {@link CommandLineParameterProvider.defineChoiceListParameter}.
+ * @public
+ */
+export declare class CommandLineChoiceListParameter extends CommandLineParameter {
+    /** {@inheritDoc ICommandLineChoiceListDefinition.alternatives} */
+    readonly alternatives: ReadonlyArray<string>;
+    private _values;
+    /** {@inheritDoc ICommandLineChoiceListDefinition.completions} */
+    readonly completions: (() => Promise<string[]>) | undefined;
+    /** @internal */
+    constructor(definition: ICommandLineChoiceListDefinition);
+    /** {@inheritDoc CommandLineParameter.kind} */
+    get kind(): CommandLineParameterKind;
+    /**
+     * {@inheritDoc CommandLineParameter._setValue}
+     * @internal
+     */
+    _setValue(data: any): void;
+    /**
+     * Returns the string arguments for a choice list parameter that was parsed from the command line.
+     *
+     * @remarks
+     * The array will be empty if the command-line has not been parsed yet,
+     * or if the parameter was omitted and has no default value.
+     */
+    get values(): ReadonlyArray<string>;
+    /** {@inheritDoc CommandLineParameter.appendToArgList} @override */
+    appendToArgList(argList: string[]): void;
+}
+//# sourceMappingURL=CommandLineChoiceListParameter.d.ts.map

package/lib/parameters/CommandLineChoiceListParameter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandLineChoiceListParameter.d.ts","sourceRoot":"","sources":["../../src/parameters/CommandLineChoiceListParameter.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,gCAAgC,EAAE,MAAM,yBAAyB,CAAC;AAC3E,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAG/E;;;GAGG;AACH,qBAAa,8BAA+B,SAAQ,oBAAoB;IACtE,kEAAkE;IAClE,SAAgB,YAAY,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAEpD,OAAO,CAAC,OAAO,CAAgB;IAE/B,iEAAiE;IACjE,SAAgB,WAAW,EAAE,CAAC,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,SAAS,CAAC;IAEnE,gBAAgB;gBACG,UAAU,EAAE,gCAAgC;IAa/D,8CAA8C;IAC9C,IAAW,IAAI,IAAI,wBAAwB,CAE1C;IAED;;;OAGG;IAEI,SAAS,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI;IAqCjC;;;;;;OAMG;IACH,IAAW,MAAM,IAAI,aAAa,CAAC,MAAM,CAAC,CAEzC;IAED,mEAAmE;IAC5D,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI;CAQhD"}

package/lib/parameters/CommandLineChoiceListParameter.js

@@ -0,0 +1,84 @@
+"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.CommandLineChoiceListParameter = void 0;
+const BaseClasses_1 = require("./BaseClasses");
+const EnvironmentVariableParser_1 = require("./EnvironmentVariableParser");
+/**
+ * The data type returned by {@link CommandLineParameterProvider.defineChoiceListParameter}.
+ * @public
+ */
+class CommandLineChoiceListParameter extends BaseClasses_1.CommandLineParameter {
+    /** @internal */
+    constructor(definition) {
+        super(definition);
+        this._values = [];
+        if (definition.alternatives.length < 1) {
+            throw new Error(`When defining a choice list parameter, the alternatives list must contain at least one value.`);
+        }
+        this.alternatives = definition.alternatives;
+        this.completions = definition.completions;
+    }
+    /** {@inheritDoc CommandLineParameter.kind} */
+    get kind() {
+        return BaseClasses_1.CommandLineParameterKind.ChoiceList;
+    }
+    /**
+     * {@inheritDoc CommandLineParameter._setValue}
+     * @internal
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    _setValue(data) {
+        // If argparse passed us a value, confirm it is valid
+        if (data !== null && data !== undefined) {
+            if (!Array.isArray(data)) {
+                this.reportInvalidData(data);
+            }
+            for (const arrayItem of data) {
+                if (typeof arrayItem !== 'string') {
+                    this.reportInvalidData(data);
+                }
+            }
+            this._values = data;
+            return;
+        }
+        if (this.environmentVariable !== undefined) {
+            const values = EnvironmentVariableParser_1.EnvironmentVariableParser.parseAsList(this.environmentVariable);
+            if (values) {
+                for (const value of values) {
+                    if (this.alternatives.indexOf(value) < 0) {
+                        const choices = '"' + this.alternatives.join('", "') + '"';
+                        throw new Error(`Invalid value "${value}" for the environment variable` +
+                            ` ${this.environmentVariable}.  Valid choices are: ${choices}`);
+                    }
+                }
+                this._values = values;
+                return;
+            }
+        }
+        // (No default value for choice lists)
+        this._values = [];
+    }
+    /**
+     * Returns the string arguments for a choice list parameter that was parsed from the command line.
+     *
+     * @remarks
+     * The array will be empty if the command-line has not been parsed yet,
+     * or if the parameter was omitted and has no default value.
+     */
+    get values() {
+        return this._values;
+    }
+    /** {@inheritDoc CommandLineParameter.appendToArgList} @override */
+    appendToArgList(argList) {
+        if (this.values.length > 0) {
+            for (const value of this.values) {
+                argList.push(this.longName);
+                argList.push(value);
+            }
+        }
+    }
+}
+exports.CommandLineChoiceListParameter = CommandLineChoiceListParameter;
+//# sourceMappingURL=CommandLineChoiceListParameter.js.map

package/lib/parameters/CommandLineChoiceListParameter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandLineChoiceListParameter.js","sourceRoot":"","sources":["../../src/parameters/CommandLineChoiceListParameter.ts"],"names":[],"mappings":";AAAA,4FAA4F;AAC5F,2DAA2D;;;AAG3D,+CAA+E;AAC/E,2EAAwE;AAExE;;;GAGG;AACH,MAAa,8BAA+B,SAAQ,kCAAoB;IAStE,gBAAgB;IAChB,YAAmB,UAA4C;QAC7D,KAAK,CAAC,UAAU,CAAC,CAAC;QAPZ,YAAO,GAAa,EAAE,CAAC;QAS7B,IAAI,UAAU,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE;YACtC,MAAM,IAAI,KAAK,CACb,+FAA+F,CAChG,CAAC;SACH;QAED,IAAI,CAAC,YAAY,GAAG,UAAU,CAAC,YAAY,CAAC;QAC5C,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC,WAAW,CAAC;IAC5C,CAAC;IAED,8CAA8C;IAC9C,IAAW,IAAI;QACb,OAAO,sCAAwB,CAAC,UAAU,CAAC;IAC7C,CAAC;IAED;;;OAGG;IACH,8DAA8D;IACvD,SAAS,CAAC,IAAS;QACxB,qDAAqD;QACrD,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,EAAE;YACvC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE;gBACxB,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;aAC9B;YACD,KAAK,MAAM,SAAS,IAAI,IAAI,EAAE;gBAC5B,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE;oBACjC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;iBAC9B;aACF;YACD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;YACpB,OAAO;SACR;QAED,IAAI,IAAI,CAAC,mBAAmB,KAAK,SAAS,EAAE;YAC1C,MAAM,MAAM,GAAyB,qDAAyB,CAAC,WAAW,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;YACrG,IAAI,MAAM,EAAE;gBACV,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE;oBAC1B,IAAI,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE;wBACxC,MAAM,OAAO,GAAW,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC;wBACnE,MAAM,IAAI,KAAK,CACb,kBAAkB,KAAK,gCAAgC;4BACrD,IAAI,IAAI,CAAC,mBAAmB,yBAAyB,OAAO,EAAE,CACjE,CAAC;qBACH;iBACF;gBACD,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;gBACtB,OAAO;aACR;SACF;QAED,sCAAsC;QAEtC,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;IACpB,CAAC;IAED;;;;;;OAMG;IACH,IAAW,MAAM;QACf,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,mEAAmE;IAC5D,eAAe,CAAC,OAAiB;QACtC,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE;YAC1B,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE;gBAC/B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBAC5B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;aACrB;SACF;IACH,CAAC;CACF;AA1FD,wEA0FC","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 { ICommandLineChoiceListDefinition } from './CommandLineDefinition';\r\nimport { CommandLineParameter, CommandLineParameterKind } from './BaseClasses';\r\nimport { EnvironmentVariableParser } from './EnvironmentVariableParser';\r\n\r\n/**\r\n * The data type returned by {@link CommandLineParameterProvider.defineChoiceListParameter}.\r\n * @public\r\n */\r\nexport class CommandLineChoiceListParameter extends CommandLineParameter {\r\n  /** {@inheritDoc ICommandLineChoiceListDefinition.alternatives} */\r\n  public readonly alternatives: ReadonlyArray<string>;\r\n\r\n  private _values: string[] = [];\r\n\r\n  /** {@inheritDoc ICommandLineChoiceListDefinition.completions} */\r\n  public readonly completions: (() => Promise<string[]>) | undefined;\r\n\r\n  /** @internal */\r\n  public constructor(definition: ICommandLineChoiceListDefinition) {\r\n    super(definition);\r\n\r\n    if (definition.alternatives.length < 1) {\r\n      throw new Error(\r\n        `When defining a choice list parameter, the alternatives list must contain at least one value.`\r\n      );\r\n    }\r\n\r\n    this.alternatives = definition.alternatives;\r\n    this.completions = definition.completions;\r\n  }\r\n\r\n  /** {@inheritDoc CommandLineParameter.kind} */\r\n  public get kind(): CommandLineParameterKind {\r\n    return CommandLineParameterKind.ChoiceList;\r\n  }\r\n\r\n  /**\r\n   * {@inheritDoc CommandLineParameter._setValue}\r\n   * @internal\r\n   */\r\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\r\n  public _setValue(data: any): void {\r\n    // If argparse passed us a value, confirm it is valid\r\n    if (data !== null && data !== undefined) {\r\n      if (!Array.isArray(data)) {\r\n        this.reportInvalidData(data);\r\n      }\r\n      for (const arrayItem of data) {\r\n        if (typeof arrayItem !== 'string') {\r\n          this.reportInvalidData(data);\r\n        }\r\n      }\r\n      this._values = data;\r\n      return;\r\n    }\r\n\r\n    if (this.environmentVariable !== undefined) {\r\n      const values: string[] | undefined = EnvironmentVariableParser.parseAsList(this.environmentVariable);\r\n      if (values) {\r\n        for (const value of values) {\r\n          if (this.alternatives.indexOf(value) < 0) {\r\n            const choices: string = '\"' + this.alternatives.join('\", \"') + '\"';\r\n            throw new Error(\r\n              `Invalid value \"${value}\" for the environment variable` +\r\n                ` ${this.environmentVariable}.  Valid choices are: ${choices}`\r\n            );\r\n          }\r\n        }\r\n        this._values = values;\r\n        return;\r\n      }\r\n    }\r\n\r\n    // (No default value for choice lists)\r\n\r\n    this._values = [];\r\n  }\r\n\r\n  /**\r\n   * Returns the string arguments for a choice list parameter that was parsed from the command line.\r\n   *\r\n   * @remarks\r\n   * The array will be empty if the command-line has not been parsed yet,\r\n   * or if the parameter was omitted and has no default value.\r\n   */\r\n  public get values(): ReadonlyArray<string> {\r\n    return this._values;\r\n  }\r\n\r\n  /** {@inheritDoc CommandLineParameter.appendToArgList} @override */\r\n  public appendToArgList(argList: string[]): void {\r\n    if (this.values.length > 0) {\r\n      for (const value of this.values) {\r\n        argList.push(this.longName);\r\n        argList.push(value);\r\n      }\r\n    }\r\n  }\r\n}\r\n"]}