@rushstack/ts-command-line 4.10.10 → 4.12.0

package/dist/ts-command-line.d.ts

@@ -200,12 +200,22 @@ export declare class CommandLineIntegerParameter extends CommandLineParameterWit
 export declare abstract class CommandLineParameter {
     private static _longNameRegExp;
     private static _shortNameRegExp;
+    private static _scopeRegExp;
     private static _environmentVariableRegExp;
     /* Excluded from this release type: _parserKey */
     /** {@inheritDoc IBaseCommandLineDefinition.parameterLongName} */
     readonly longName: string;
+    /**
+     * If a parameterScope is provided, returns the scope-prefixed long name of the flag,
+     * including double dashes, eg. "--scope:do-something". Otherwise undefined.
+     */
+    readonly scopedLongName: string | undefined;
     /** {@inheritDoc IBaseCommandLineDefinition.parameterShortName} */
     readonly shortName: string | undefined;
+    /** {@inheritDoc IBaseCommandLineDefinition.parameterGroup} */
+    readonly parameterGroup: string | typeof SCOPING_PARAMETER_GROUP | undefined;
+    /** {@inheritDoc IBaseCommandLineDefinition.parameterScope} */
+    readonly parameterScope: string | undefined;
     /** {@inheritDoc IBaseCommandLineDefinition.description} */
     readonly description: string;
     /** {@inheritDoc IBaseCommandLineDefinition.required} */
@@ -270,9 +280,14 @@ export declare enum CommandLineParameterKind {
  * @public
  */
 export declare abstract class CommandLineParameterProvider {
+    private static readonly _scopeGroupName;
+    private static readonly _longNameGroupName;
+    private static readonly _possiblyScopedLongNameRegex;
     private static _keyCounter;
     private _parameters;
     private _parametersByLongName;
+    private _parameterGroupsByName;
+    private _parametersRegistered;
     private _parametersProcessed;
     private _remainder;
     /* Excluded from this release type: __constructor */
@@ -305,7 +320,7 @@ export declare abstract class CommandLineParameterProvider {
      * @remarks
      * This method throws an exception if the parameter is not defined.
      */
-    getChoiceParameter(parameterLongName: string): CommandLineChoiceParameter;
+    getChoiceParameter(parameterLongName: string, parameterScope?: 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
@@ -323,7 +338,7 @@ export declare abstract class CommandLineParameterProvider {
      * @remarks
      * This method throws an exception if the parameter is not defined.
      */
-    getChoiceListParameter(parameterLongName: string): CommandLineChoiceListParameter;
+    getChoiceListParameter(parameterLongName: string, parameterScope?: string): CommandLineChoiceListParameter;
     /**
      * Defines a command-line switch whose boolean value is true if the switch is provided,
      * and false otherwise.
@@ -340,7 +355,7 @@ export declare abstract class CommandLineParameterProvider {
      * @remarks
      * This method throws an exception if the parameter is not defined.
      */
-    getFlagParameter(parameterLongName: string): CommandLineFlagParameter;
+    getFlagParameter(parameterLongName: string, parameterScope?: string): CommandLineFlagParameter;
     /**
      * Defines a command-line parameter whose argument is an integer.
      *
@@ -356,7 +371,7 @@ export declare abstract class CommandLineParameterProvider {
      * @remarks
      * This method throws an exception if the parameter is not defined.
      */
-    getIntegerParameter(parameterLongName: string): CommandLineIntegerParameter;
+    getIntegerParameter(parameterLongName: string, parameterScope?: string): CommandLineIntegerParameter;
     /**
      * Defines a command-line parameter whose argument is an integer. The parameter can be specified
      * multiple times to build a list.
@@ -373,7 +388,7 @@ export declare abstract class CommandLineParameterProvider {
      * @remarks
      * This method throws an exception if the parameter is not defined.
      */
-    getIntegerListParameter(parameterLongName: string): CommandLineIntegerListParameter;
+    getIntegerListParameter(parameterLongName: string, parameterScope?: string): CommandLineIntegerListParameter;
     /**
      * Defines a command-line parameter whose argument is a single text string.
      *
@@ -389,7 +404,7 @@ export declare abstract class CommandLineParameterProvider {
      * @remarks
      * This method throws an exception if the parameter is not defined.
      */
-    getStringParameter(parameterLongName: string): CommandLineStringParameter;
+    getStringParameter(parameterLongName: string, parameterScope?: 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.
@@ -422,17 +437,26 @@ export declare abstract class CommandLineParameterProvider {
      * @remarks
      * This method throws an exception if the parameter is not defined.
      */
-    getStringListParameter(parameterLongName: string): CommandLineStringListParameter;
+    getStringListParameter(parameterLongName: string, parameterScope?: string): CommandLineStringListParameter;
     /**
      * Generates the command-line help text.
      */
     renderHelpText(): string;
+    /**
+     * Generates the command-line usage text.
+     */
+    renderUsageText(): 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>;
+    /**
+     * Returns an object with the parsed scope (if present) and the long name of the parameter.
+     */
+    parseScopedLongName(scopedLongName: string): IScopedLongNameParseResult;
+    /* Excluded from this release type: _registerDefinedParameters */
     /**
      * The child class should implement this hook to define its command-line parameters,
      * e.g. by calling defineFlagParameter().
@@ -440,9 +464,10 @@ export declare abstract class CommandLineParameterProvider {
     protected abstract onDefineParameters(): void;
     /* Excluded from this release type: _getArgumentParser */
     /* Excluded from this release type: _processParsedData */
+    /* Excluded from this release type: _defineParameter */
+    /* Excluded from this release type: _registerParameter */
     private _generateKey;
     private _getParameter;
-    private _defineParameter;
 }
 
 /**
@@ -528,6 +553,7 @@ export declare abstract class CommandLineParser extends CommandLineParameterProv
      * simply cause the promise to reject.  It is the caller's responsibility to trap
      */
     executeWithoutErrorHandling(args?: string[]): Promise<void>;
+    /* Excluded from this release type: _registerDefinedParameters */
     private _validateDefinitions;
     /* Excluded from this release type: _getArgumentParser */
     /**
@@ -635,6 +661,17 @@ export declare interface IBaseCommandLineDefinition {
      * An optional short name for the flag including the dash, e.g. "-d"
      */
     parameterShortName?: string;
+    /**
+     * An optional parameter group name, shown when invoking the tool with "--help"
+     */
+    parameterGroup?: string | typeof SCOPING_PARAMETER_GROUP;
+    /**
+     * An optional parameter scope name, used to add a scope-prefixed parameter synonym,
+     * e.g. "--scope:do-something". Scopes provide additional flexibility for parameters
+     * in conflict resolution since when a scope is specified, parameters that have
+     * conflicting long names will be defined using only the scope-prefixed name.
+     */
+    parameterScope?: string;
     /**
      * Documentation for the parameter that will be shown when invoking the tool with "--help"
      */
@@ -832,6 +869,11 @@ export declare interface ICommandLineParserOptions {
      * General documentation that is included in the "--help" main page
      */
     toolDescription: string;
+    /**
+     * An optional string to append at the end of the "--help" main page. If not provided, an epilog
+     * will be automatically generated based on the toolFilename.
+     */
+    toolEpilog?: string;
     /**
      * Set to true to auto-define a tab completion action. False by default.
      */
@@ -880,4 +922,91 @@ export declare interface ICommandLineStringDefinition extends IBaseCommandLineDe
 export declare interface ICommandLineStringListDefinition extends IBaseCommandLineDefinitionWithArgument {
 }
 
+/**
+ * The result containing the parsed paramter long name and scope. Returned when calling
+ * {@link CommandLineParameterProvider.parseScopedLongName}.
+ *
+ * @public
+ */
+export declare interface IScopedLongNameParseResult {
+    /**
+     * The long name parsed from the scoped long name, e.g. "--my-scope:my-parameter" -\> "--my-parameter"
+     */
+    longName: string;
+    /**
+     * The scope parsed from the scoped long name or undefined if no scope was found,
+     * e.g. "--my-scope:my-parameter" -\> "my-scope"
+     */
+    scope: string | undefined;
+}
+
+/**
+ * Represents a sub-command that is part of the CommandLineParser command-line.
+ * Applications should create subclasses of ScopedCommandLineAction 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).
+ *
+ * Scoped commands allow for different parameters to be specified for different
+ * provided scoping values. For example, the "scoped-action --scope A" command
+ * may allow for different scoped arguments to be specified than the "scoped-action
+ * --scope B" command.
+ *
+ * Scoped arguments are specified after the "--" pseudo-argument. For example,
+ * "scoped-action --scope A -- --scopedFoo --scopedBar".
+ *
+ * @public
+ */
+export declare abstract class ScopedCommandLineAction extends CommandLineAction {
+    private _options;
+    private _scopingParameters;
+    private _unscopedParserOptions;
+    private _scopedCommandLineParser;
+    /**
+     * The required group name to apply to all scoping parameters. At least one parameter
+     * must be defined with this group name.
+     */
+    static readonly ScopingParameterGroup: typeof SCOPING_PARAMETER_GROUP;
+    constructor(options: ICommandLineActionOptions);
+    /**
+     * {@inheritDoc CommandLineParameterProvider.parameters}
+     */
+    get parameters(): ReadonlyArray<CommandLineParameter>;
+    /* Excluded from this release type: _processParsedData */
+    /* Excluded from this release type: _execute */
+    /**
+     * {@inheritdoc CommandLineParameterProvider.onDefineParameters}
+     */
+    protected onDefineParameters(): void;
+    /* Excluded from this release type: _getScopedCommandLineParser */
+    /* Excluded from this release type: _defineParameter */
+    /**
+     * The child class should implement this hook to define its unscoped command-line parameters,
+     * e.g. by calling defineFlagParameter(). At least one scoping parameter must be defined.
+     * Scoping parameters are defined by setting the parameterGroupName to
+     * ScopedCommandLineAction.ScopingParameterGroupName.
+     */
+    protected abstract onDefineUnscopedParameters(): void;
+    /**
+     * The child class should implement this hook to define its scoped command-line
+     * parameters, e.g. by calling scopedParameterProvider.defineFlagParameter(). These
+     * parameters will only be available if the action is invoked with a scope.
+     *
+     * @remarks
+     * onDefineScopedParameters is called after the unscoped parameters have been parsed.
+     * The values they provide can be used to vary the defined scope parameters.
+     */
+    protected abstract onDefineScopedParameters(scopedParameterProvider: CommandLineParameterProvider): void;
+    /**
+     * {@inheritDoc CommandLineAction.onExecute}
+     */
+    protected abstract onExecute(): Promise<void>;
+}
+
+declare const SCOPING_PARAMETER_GROUP: unique symbol;
+
 export { }

package/dist/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.21.2"
+      "packageVersion": "7.25.0"
     }
   ]
 }

package/lib/Constants.d.ts

@@ -9,4 +9,5 @@ export declare const enum CommandLineConstants {
      */
     TabCompletionActionName = "tab-complete"
 }
+export declare const SCOPING_PARAMETER_GROUP: unique symbol;
 //# sourceMappingURL=Constants.d.ts.map

package/lib/Constants.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"Constants.d.ts","sourceRoot":"","sources":["../src/Constants.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,0BAAkB,oBAAoB;IACpC;;OAEG;IACH,uBAAuB,iBAAiB;CACzC;AAED,eAAO,MAAM,uBAAuB,EAAE,OAAO,MAA0B,CAAC"}

package/lib/Constants.js

@@ -2,4 +2,6 @@
 // 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.SCOPING_PARAMETER_GROUP = void 0;
+exports.SCOPING_PARAMETER_GROUP = Symbol('scoping');
 //# sourceMappingURL=Constants.js.map

package/lib/Constants.js.map

@@ -1 +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.\n// See LICENSE in the project root for license information.\n\n/**\n * String constants for command line processing.\n *\n * @public\n */\nexport const enum CommandLineConstants {\n  /**\n   * The name of the built-in action that serves suggestions for tab-completion\n   */\n  TabCompletionActionName = 'tab-complete'\n}\n"]}
+{"version":3,"file":"Constants.js","sourceRoot":"","sources":["../src/Constants.ts"],"names":[],"mappings":";AAAA,4FAA4F;AAC5F,2DAA2D;;;AAc9C,QAAA,uBAAuB,GAAkB,MAAM,CAAC,SAAS,CAAC,CAAC","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\n/**\n * String constants for command line processing.\n *\n * @public\n */\nexport const enum CommandLineConstants {\n  /**\n   * The name of the built-in action that serves suggestions for tab-completion\n   */\n  TabCompletionActionName = 'tab-complete'\n}\n\nexport const SCOPING_PARAMETER_GROUP: unique symbol = Symbol('scoping');\n"]}

package/lib/index.d.ts

@@ -4,6 +4,8 @@
  * @packageDocumentation
  */
 export { CommandLineAction, ICommandLineActionOptions } from './providers/CommandLineAction';
+export { DynamicCommandLineAction } from './providers/DynamicCommandLineAction';
+export { ScopedCommandLineAction } from './providers/ScopedCommandLineAction';
 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';
@@ -14,9 +16,8 @@ export { CommandLineIntegerListParameter } from './parameters/CommandLineInteger
 export { CommandLineChoiceParameter } from './parameters/CommandLineChoiceParameter';
 export { CommandLineChoiceListParameter } from './parameters/CommandLineChoiceListParameter';
 export { CommandLineRemainder } from './parameters/CommandLineRemainder';
-export { CommandLineParameterProvider, ICommandLineParserData as _ICommandLineParserData } from './providers/CommandLineParameterProvider';
+export { CommandLineParameterProvider, IScopedLongNameParseResult, 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';

package/lib/index.d.ts.map

@@ -1 +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"}
+{"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;AAC7F,OAAO,EAAE,wBAAwB,EAAE,MAAM,sCAAsC,CAAC;AAChF,OAAO,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AAE9E,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,0BAA0B,EAC1B,sBAAsB,IAAI,uBAAuB,EAClD,MAAM,0CAA0C,CAAC;AAElD,OAAO,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAC7F,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

@@ -2,7 +2,7 @@
 // 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 = exports.DynamicCommandLineParser = exports.DynamicCommandLineAction = exports.CommandLineParser = exports.CommandLineParameterProvider = exports.CommandLineRemainder = exports.CommandLineChoiceListParameter = exports.CommandLineChoiceParameter = exports.CommandLineIntegerListParameter = exports.CommandLineIntegerParameter = exports.CommandLineStringListParameter = exports.CommandLineStringParameter = exports.CommandLineFlagParameter = exports.CommandLineParameterWithArgument = exports.CommandLineParameter = exports.CommandLineParameterKind = exports.CommandLineAction = void 0;
+exports.CommandLineHelper = exports.DynamicCommandLineParser = exports.CommandLineParser = exports.CommandLineParameterProvider = exports.CommandLineRemainder = exports.CommandLineChoiceListParameter = exports.CommandLineChoiceParameter = exports.CommandLineIntegerListParameter = exports.CommandLineIntegerParameter = exports.CommandLineStringListParameter = exports.CommandLineStringParameter = exports.CommandLineFlagParameter = exports.CommandLineParameterWithArgument = exports.CommandLineParameter = exports.CommandLineParameterKind = exports.ScopedCommandLineAction = exports.DynamicCommandLineAction = exports.CommandLineAction = void 0;
 /**
  * An object-oriented command-line parser for TypeScript projects.
  *
@@ -10,6 +10,10 @@ exports.CommandLineHelper = exports.DynamicCommandLineParser = exports.DynamicCo
  */
 var CommandLineAction_1 = require("./providers/CommandLineAction");
 Object.defineProperty(exports, "CommandLineAction", { enumerable: true, get: function () { return CommandLineAction_1.CommandLineAction; } });
+var DynamicCommandLineAction_1 = require("./providers/DynamicCommandLineAction");
+Object.defineProperty(exports, "DynamicCommandLineAction", { enumerable: true, get: function () { return DynamicCommandLineAction_1.DynamicCommandLineAction; } });
+var ScopedCommandLineAction_1 = require("./providers/ScopedCommandLineAction");
+Object.defineProperty(exports, "ScopedCommandLineAction", { enumerable: true, get: function () { return ScopedCommandLineAction_1.ScopedCommandLineAction; } });
 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; } });
@@ -34,8 +38,6 @@ var CommandLineParameterProvider_1 = require("./providers/CommandLineParameterPr
 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");

package/lib/index.js.map

@@ -1 +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.\n// See LICENSE in the project root for license information.\n\n/**\n * An object-oriented command-line parser for TypeScript projects.\n *\n * @packageDocumentation\n */\n\nexport { CommandLineAction, ICommandLineActionOptions } from './providers/CommandLineAction';\n\nexport {\n  IBaseCommandLineDefinition,\n  IBaseCommandLineDefinitionWithArgument,\n  ICommandLineFlagDefinition,\n  ICommandLineStringDefinition,\n  ICommandLineStringListDefinition,\n  ICommandLineIntegerDefinition,\n  ICommandLineIntegerListDefinition,\n  ICommandLineChoiceDefinition,\n  ICommandLineChoiceListDefinition,\n  ICommandLineRemainderDefinition\n} from './parameters/CommandLineDefinition';\n\nexport {\n  CommandLineParameterKind,\n  CommandLineParameter,\n  CommandLineParameterWithArgument\n} from './parameters/BaseClasses';\n\nexport { CommandLineFlagParameter } from './parameters/CommandLineFlagParameter';\nexport { CommandLineStringParameter } from './parameters/CommandLineStringParameter';\nexport { CommandLineStringListParameter } from './parameters/CommandLineStringListParameter';\nexport { CommandLineIntegerParameter } from './parameters/CommandLineIntegerParameter';\nexport { CommandLineIntegerListParameter } from './parameters/CommandLineIntegerListParameter';\nexport { CommandLineChoiceParameter } from './parameters/CommandLineChoiceParameter';\nexport { CommandLineChoiceListParameter } from './parameters/CommandLineChoiceListParameter';\nexport { CommandLineRemainder } from './parameters/CommandLineRemainder';\n\nexport {\n  CommandLineParameterProvider,\n  ICommandLineParserData as _ICommandLineParserData\n} from './providers/CommandLineParameterProvider';\n\nexport { ICommandLineParserOptions, CommandLineParser } from './providers/CommandLineParser';\n\nexport { DynamicCommandLineAction } from './providers/DynamicCommandLineAction';\n\nexport { DynamicCommandLineParser } from './providers/DynamicCommandLineParser';\n\nexport { CommandLineConstants } from './Constants';\n\nexport { CommandLineHelper } from './CommandLineHelper';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,4FAA4F;AAC5F,2DAA2D;;;AAE3D;;;;GAIG;AAEH,mEAA6F;AAApF,sHAAA,iBAAiB,OAAA;AAC1B,iFAAgF;AAAvE,oIAAA,wBAAwB,OAAA;AACjC,+EAA8E;AAArE,kIAAA,uBAAuB,OAAA;AAehC,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,yFAIkD;AAHhD,4IAAA,4BAA4B,OAAA;AAK9B,mEAA6F;AAAzD,sHAAA,iBAAiB,OAAA;AACrD,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.\n// See LICENSE in the project root for license information.\n\n/**\n * An object-oriented command-line parser for TypeScript projects.\n *\n * @packageDocumentation\n */\n\nexport { CommandLineAction, ICommandLineActionOptions } from './providers/CommandLineAction';\nexport { DynamicCommandLineAction } from './providers/DynamicCommandLineAction';\nexport { ScopedCommandLineAction } from './providers/ScopedCommandLineAction';\n\nexport {\n  IBaseCommandLineDefinition,\n  IBaseCommandLineDefinitionWithArgument,\n  ICommandLineFlagDefinition,\n  ICommandLineStringDefinition,\n  ICommandLineStringListDefinition,\n  ICommandLineIntegerDefinition,\n  ICommandLineIntegerListDefinition,\n  ICommandLineChoiceDefinition,\n  ICommandLineChoiceListDefinition,\n  ICommandLineRemainderDefinition\n} from './parameters/CommandLineDefinition';\n\nexport {\n  CommandLineParameterKind,\n  CommandLineParameter,\n  CommandLineParameterWithArgument\n} from './parameters/BaseClasses';\n\nexport { CommandLineFlagParameter } from './parameters/CommandLineFlagParameter';\nexport { CommandLineStringParameter } from './parameters/CommandLineStringParameter';\nexport { CommandLineStringListParameter } from './parameters/CommandLineStringListParameter';\nexport { CommandLineIntegerParameter } from './parameters/CommandLineIntegerParameter';\nexport { CommandLineIntegerListParameter } from './parameters/CommandLineIntegerListParameter';\nexport { CommandLineChoiceParameter } from './parameters/CommandLineChoiceParameter';\nexport { CommandLineChoiceListParameter } from './parameters/CommandLineChoiceListParameter';\nexport { CommandLineRemainder } from './parameters/CommandLineRemainder';\n\nexport {\n  CommandLineParameterProvider,\n  IScopedLongNameParseResult,\n  ICommandLineParserData as _ICommandLineParserData\n} from './providers/CommandLineParameterProvider';\n\nexport { ICommandLineParserOptions, CommandLineParser } from './providers/CommandLineParser';\nexport { DynamicCommandLineParser } from './providers/DynamicCommandLineParser';\n\nexport { CommandLineConstants } from './Constants';\n\nexport { CommandLineHelper } from './CommandLineHelper';\n"]}

package/lib/parameters/BaseClasses.d.ts

@@ -1,3 +1,4 @@
+import type { SCOPING_PARAMETER_GROUP } from '../Constants';
 import { IBaseCommandLineDefinition, IBaseCommandLineDefinitionWithArgument } from './CommandLineDefinition';
 /**
  * Identifies the kind of a CommandLineParameter.
@@ -26,6 +27,7 @@ export declare enum CommandLineParameterKind {
 export declare abstract class CommandLineParameter {
     private static _longNameRegExp;
     private static _shortNameRegExp;
+    private static _scopeRegExp;
     private static _environmentVariableRegExp;
     /**
      * A unique internal key used to retrieve the value from the parser's dictionary.
@@ -34,8 +36,17 @@ export declare abstract class CommandLineParameter {
     _parserKey: string | undefined;
     /** {@inheritDoc IBaseCommandLineDefinition.parameterLongName} */
     readonly longName: string;
+    /**
+     * If a parameterScope is provided, returns the scope-prefixed long name of the flag,
+     * including double dashes, eg. "--scope:do-something". Otherwise undefined.
+     */
+    readonly scopedLongName: string | undefined;
     /** {@inheritDoc IBaseCommandLineDefinition.parameterShortName} */
     readonly shortName: string | undefined;
+    /** {@inheritDoc IBaseCommandLineDefinition.parameterGroup} */
+    readonly parameterGroup: string | typeof SCOPING_PARAMETER_GROUP | undefined;
+    /** {@inheritDoc IBaseCommandLineDefinition.parameterScope} */
+    readonly parameterScope: string | undefined;
     /** {@inheritDoc IBaseCommandLineDefinition.description} */
     readonly description: string;
     /** {@inheritDoc IBaseCommandLineDefinition.required} */

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

@@ -1 +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"}
+{"version":3,"file":"BaseClasses.d.ts","sourceRoot":"","sources":["../../src/parameters/BaseClasses.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAC5D,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;IAGxC,OAAO,CAAC,MAAM,CAAC,eAAe,CAA8B;IAI5D,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAyB;IAIxD,OAAO,CAAC,MAAM,CAAC,YAAY,CAAsC;IAMjE,OAAO,CAAC,MAAM,CAAC,0BAA0B,CAAgC;IAEzE;;;OAGG;IACI,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAEtC,iEAAiE;IACjE,SAAgB,QAAQ,EAAE,MAAM,CAAC;IAEjC;;;OAGG;IACH,SAAgB,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IAEnD,kEAAkE;IAClE,SAAgB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAE9C,8DAA8D;IAC9D,SAAgB,cAAc,EAAE,MAAM,GAAG,OAAO,uBAAuB,GAAG,SAAS,CAAC;IAEpF,8DAA8D;IAC9D,SAAgB,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IAEnD,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;IAyEzD;;;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

@@ -33,6 +33,8 @@ class CommandLineParameter {
     constructor(definition) {
         this.longName = definition.parameterLongName;
         this.shortName = definition.parameterShortName;
+        this.parameterGroup = definition.parameterGroup;
+        this.parameterScope = definition.parameterScope;
         this.description = definition.description;
         this.required = !!definition.required;
         this.environmentVariable = definition.environmentVariable;
@@ -47,6 +49,15 @@ class CommandLineParameter {
                     ` a dash followed by a single upper-case or lower-case letter (e.g. "-a")`);
             }
         }
+        if (this.parameterScope) {
+            if (!CommandLineParameter._scopeRegExp.test(this.parameterScope)) {
+                throw new Error(`Invalid scope: "${this.parameterScope}". The parameter scope name must be` +
+                    ` lower-case and use dash delimiters (e.g. "my-scope")`);
+            }
+            // Parameter long name is guranteed to start with '--' since this is validated above
+            const unprefixedLongName = this.longName.slice(2);
+            this.scopedLongName = `--${this.parameterScope}:${unprefixedLongName}`;
+        }
         if (this.environmentVariable) {
             if (this.required) {
                 // TODO: This constraint is imposed only because argparse enforces "required" parameters, but
@@ -60,17 +71,14 @@ class CommandLineParameter {
             }
         }
         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` +
+                    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")`);
+                    throw new Error(`Invalid name: "${undocumentedSynonym}". All undocumented synonyms name must be lower-case and ` +
+                        'use dash delimiters (e.g. "--do-a-thing")');
                 }
             }
         }
@@ -106,10 +114,15 @@ class CommandLineParameter {
     }
 }
 exports.CommandLineParameter = CommandLineParameter;
+// Matches kebab-case formatted strings prefixed with double dashes.
 // Example: "--do-something"
 CommandLineParameter._longNameRegExp = /^-(-[a-z0-9]+)+$/;
+// Matches a single upper-case or lower-case letter prefixed with a dash.
 // Example: "-d"
 CommandLineParameter._shortNameRegExp = /^-[a-zA-Z]$/;
+// Matches kebab-case formatted strings
+// Example: "my-scope"
+CommandLineParameter._scopeRegExp = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 // "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."

package/lib/parameters/BaseClasses.js.map

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

package/lib/parameters/CommandLineDefinition.d.ts

@@ -1,3 +1,4 @@
+import type { SCOPING_PARAMETER_GROUP } from '../Constants';
 /**
  * For use with CommandLineParser, this interface represents a generic command-line parameter
  *
@@ -12,6 +13,17 @@ export interface IBaseCommandLineDefinition {
      * An optional short name for the flag including the dash, e.g. "-d"
      */
     parameterShortName?: string;
+    /**
+     * An optional parameter group name, shown when invoking the tool with "--help"
+     */
+    parameterGroup?: string | typeof SCOPING_PARAMETER_GROUP;
+    /**
+     * An optional parameter scope name, used to add a scope-prefixed parameter synonym,
+     * e.g. "--scope:do-something". Scopes provide additional flexibility for parameters
+     * in conflict resolution since when a scope is specified, parameters that have
+     * conflicting long names will be defined using only the scope-prefixed name.
+     */
+    parameterScope?: string;
     /**
      * Documentation for the parameter that will be shown when invoking the tool with "--help"
      */

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

@@ -1 +1 @@
-{"version":3,"file":"CommandLineDefinition.d.ts","sourceRoot":"","sources":["../../src/parameters/CommandLineDefinition.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC;;OAEG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;;;;;OAQG;IACH,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,sCAAuC,SAAQ,0BAA0B;IACxF;;;;;;;OAOG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACvC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,4BAA6B,SAAQ,0BAA0B;IAC9E;;OAEG;IACH,YAAY,EAAE,MAAM,EAAE,CAAC;IAEvB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACvC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gCAAiC,SAAQ,0BAA0B;IAClF;;OAEG;IACH,YAAY,EAAE,MAAM,EAAE,CAAC;IAEvB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACvC;AAED;;;;;GAKG;AACH,MAAM,WAAW,0BAA2B,SAAQ,0BAA0B;CAAG;AAEjF;;;;;GAKG;AACH,MAAM,WAAW,6BAA8B,SAAQ,sCAAsC;IAC3F;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iCAAkC,SAAQ,sCAAsC;CAAG;AAEpG;;;;;GAKG;AACH,MAAM,WAAW,4BAA6B,SAAQ,sCAAsC;IAC1F;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gCAAiC,SAAQ,sCAAsC;CAAG;AAEnG;;;;;GAKG;AACH,MAAM,WAAW,+BAA+B;IAC9C;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB"}
+{"version":3,"file":"CommandLineDefinition.d.ts","sourceRoot":"","sources":["../../src/parameters/CommandLineDefinition.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAE5D;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC;;OAEG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,uBAAuB,CAAC;IAEzD;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;;;;;OAQG;IACH,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,sCAAuC,SAAQ,0BAA0B;IACxF;;;;;;;OAOG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACvC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,4BAA6B,SAAQ,0BAA0B;IAC9E;;OAEG;IACH,YAAY,EAAE,MAAM,EAAE,CAAC;IAEvB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACvC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gCAAiC,SAAQ,0BAA0B;IAClF;;OAEG;IACH,YAAY,EAAE,MAAM,EAAE,CAAC;IAEvB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACvC;AAED;;;;;GAKG;AACH,MAAM,WAAW,0BAA2B,SAAQ,0BAA0B;CAAG;AAEjF;;;;;GAKG;AACH,MAAM,WAAW,6BAA8B,SAAQ,sCAAsC;IAC3F;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iCAAkC,SAAQ,sCAAsC;CAAG;AAEpG;;;;;GAKG;AACH,MAAM,WAAW,4BAA6B,SAAQ,sCAAsC;IAC1F;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gCAAiC,SAAQ,sCAAsC;CAAG;AAEnG;;;;;GAKG;AACH,MAAM,WAAW,+BAA+B;IAC9C;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB"}

package/lib/parameters/CommandLineDefinition.js.map

@@ -1 +1 @@
-{"version":3,"file":"CommandLineDefinition.js","sourceRoot":"","sources":["../../src/parameters/CommandLineDefinition.ts"],"names":[],"mappings":";AAAA,4FAA4F;AAC5F,2DAA2D","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\n/**\n * For use with CommandLineParser, this interface represents a generic command-line parameter\n *\n * @public\n */\nexport interface IBaseCommandLineDefinition {\n  /**\n   * The long name of the flag including double dashes, e.g. \"--do-something\"\n   */\n  parameterLongName: string;\n\n  /**\n   * An optional short name for the flag including the dash, e.g. \"-d\"\n   */\n  parameterShortName?: string;\n\n  /**\n   * Documentation for the parameter that will be shown when invoking the tool with \"--help\"\n   */\n  description: string;\n\n  /**\n   * If true, then an error occurs if the parameter was not included on the command-line.\n   */\n  required?: boolean;\n\n  /**\n   * The name of an environment variable that the parameter value will be read from,\n   * if it was omitted from the command-line.  An error will be reported if the\n   * environment value cannot be parsed.\n   *\n   * @remarks\n   * The environment variable name must consist only of upper-case letters, numbers,\n   * and underscores. It may not start with a number.\n   *\n   * This feature cannot be used when {@link IBaseCommandLineDefinition.required} is true,\n   * because in that case the environmentVariable would never be used.\n   *\n   * Syntax notes for environment variable values:\n   *\n   * - Choice Parameter: The value must match one of the defined choices,\n   *   otherwise a validation error is reported.\n   *   An empty string causes the environment variable to be ignored.\n   *\n   * - Flag Parameter: The value must be `1` for true, or `0` for false,\n   *   otherwise a validation error is reported.\n   *   An empty string causes the environment variable to be ignored.\n   *\n   * - Integer Parameter: The value must be an integer number,\n   *   otherwise a validation error is reported.\n   *   An empty string causes the environment variable to be ignored.\n   *\n   * - String Parameter: Any value is accepted, including an empty string.\n   *\n   * - String List Parameter: If the string starts with `[` (ignoring whitespace)\n   *   then it will be parsed as a JSON array, whose elements must be strings,\n   *   numbers, or boolean values.\n   *   If the string does not start with `[`, then it behaves like an\n   *   ordinary String Parameter:  Any value is accepted, including an empty string.\n   */\n  environmentVariable?: string;\n\n  /**\n   * Specifies additional names for this parameter that are accepted but not displayed\n   * in the command line help.\n   *\n   * @remarks\n   * This option can be used in cases where a command-line parameter may have been renamed,\n   * but the developer doesn't want to break backwards compatibility with systems that may\n   * still be using the old name. Only the `parameterLongName` syntax is currently allowed.\n   */\n  undocumentedSynonyms?: string[];\n}\n\n/**\n * The common base interface for parameter types that accept an argument.\n *\n * @remarks\n * An argument is an accompanying command-line token, such as \"123\" in the\n * example \"--max-count 123\".\n * @public\n */\nexport interface IBaseCommandLineDefinitionWithArgument extends IBaseCommandLineDefinition {\n  /**\n   * The name of the argument, which will be shown in the command-line help.\n   *\n   * @remarks\n   * For example, if the parameter name is '--count\" and the argument name is \"NUMBER\",\n   * then the command-line help would display \"--count NUMBER\".  The argument name must\n   * be comprised of upper-case letters, numbers, and underscores.  It should be kept short.\n   */\n  argumentName: string;\n\n  /**\n   * An optional callback that provides a list of custom choices for tab completion.\n   * @remarks\n   * This option is only used when `ICommandLineParserOptions.enableTabCompletionAction`\n   * is enabled.\n   */\n  completions?: () => Promise<string[]>;\n}\n\n/**\n * For use with {@link CommandLineParameterProvider.defineChoiceParameter},\n * this interface defines a command line parameter which is constrained to a list of possible\n * options.\n *\n * @public\n */\nexport interface ICommandLineChoiceDefinition extends IBaseCommandLineDefinition {\n  /**\n   * A list of strings (which contain no spaces), of possible options which can be selected\n   */\n  alternatives: string[];\n\n  /**\n   * {@inheritDoc ICommandLineStringDefinition.defaultValue}\n   */\n  defaultValue?: string;\n\n  /**\n   * An optional callback that provides a list of custom choices for tab completion.\n   * @remarks\n   * This option is only used when `ICommandLineParserOptions.enableTabCompletionAction`\n   * is enabled.\n   */\n  completions?: () => Promise<string[]>;\n}\n\n/**\n * For use with {@link CommandLineParameterProvider.defineChoiceListParameter},\n * this interface defines a command line parameter which is constrained to a list of possible\n * options. The parameter can be specified multiple times to build a list.\n *\n * @public\n */\nexport interface ICommandLineChoiceListDefinition extends IBaseCommandLineDefinition {\n  /**\n   * A list of strings (which contain no spaces), of possible options which can be selected\n   */\n  alternatives: string[];\n\n  /**\n   * An optional callback that provides a list of custom choices for tab completion.\n   * @remarks\n   * This option is only used when `ICommandLineParserOptions.enableTabCompletionAction`\n   * is enabled.\n   */\n  completions?: () => Promise<string[]>;\n}\n\n/**\n * For use with {@link CommandLineParameterProvider.defineFlagParameter},\n * this interface defines a command line parameter that is a boolean flag.\n *\n * @public\n */\nexport interface ICommandLineFlagDefinition extends IBaseCommandLineDefinition {}\n\n/**\n * For use with {@link CommandLineParameterProvider.defineIntegerParameter},\n * this interface defines a command line parameter whose argument is an integer value.\n *\n * @public\n */\nexport interface ICommandLineIntegerDefinition extends IBaseCommandLineDefinitionWithArgument {\n  /**\n   * {@inheritDoc ICommandLineStringDefinition.defaultValue}\n   */\n  defaultValue?: number;\n}\n\n/**\n * For use with {@link CommandLineParameterProvider.defineIntegerListParameter},\n * this interface defines a command line parameter whose argument is an integer value. The\n * parameter can be specified multiple times to build a list.\n *\n * @public\n */\nexport interface ICommandLineIntegerListDefinition extends IBaseCommandLineDefinitionWithArgument {}\n\n/**\n * For use with {@link CommandLineParameterProvider.defineStringParameter},\n * this interface defines a command line parameter whose argument is a string value.\n *\n * @public\n */\nexport interface ICommandLineStringDefinition extends IBaseCommandLineDefinitionWithArgument {\n  /**\n   * The default value which will be used if the parameter is omitted from the command line.\n   *\n   * @remarks\n   * If a default value is specified, then {@link IBaseCommandLineDefinition.required}\n   * must not be true.  Instead, a custom error message should be used to report cases\n   * where a default value was not available.\n   */\n  defaultValue?: string;\n}\n\n/**\n * For use with {@link CommandLineParameterProvider.defineStringListParameter},\n * this interface defines a command line parameter whose argument is a single text string.\n * The parameter can be specified multiple times to build a list.\n *\n * @public\n */\nexport interface ICommandLineStringListDefinition extends IBaseCommandLineDefinitionWithArgument {}\n\n/**\n * For use with {@link CommandLineParameterProvider.defineCommandLineRemainder},\n * this interface defines a rule that captures any remaining command line arguments after the recognized portion.\n *\n * @public\n */\nexport interface ICommandLineRemainderDefinition {\n  /**\n   * Documentation for how the remaining arguments will be used.  This will be shown when invoking\n   * the tool with \"--help\".\n   */\n  description: string;\n}\n"]}
+{"version":3,"file":"CommandLineDefinition.js","sourceRoot":"","sources":["../../src/parameters/CommandLineDefinition.ts"],"names":[],"mappings":";AAAA,4FAA4F;AAC5F,2DAA2D","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 { SCOPING_PARAMETER_GROUP } from '../Constants';\n\n/**\n * For use with CommandLineParser, this interface represents a generic command-line parameter\n *\n * @public\n */\nexport interface IBaseCommandLineDefinition {\n  /**\n   * The long name of the flag including double dashes, e.g. \"--do-something\"\n   */\n  parameterLongName: string;\n\n  /**\n   * An optional short name for the flag including the dash, e.g. \"-d\"\n   */\n  parameterShortName?: string;\n\n  /**\n   * An optional parameter group name, shown when invoking the tool with \"--help\"\n   */\n  parameterGroup?: string | typeof SCOPING_PARAMETER_GROUP;\n\n  /**\n   * An optional parameter scope name, used to add a scope-prefixed parameter synonym,\n   * e.g. \"--scope:do-something\". Scopes provide additional flexibility for parameters\n   * in conflict resolution since when a scope is specified, parameters that have\n   * conflicting long names will be defined using only the scope-prefixed name.\n   */\n  parameterScope?: string;\n\n  /**\n   * Documentation for the parameter that will be shown when invoking the tool with \"--help\"\n   */\n  description: string;\n\n  /**\n   * If true, then an error occurs if the parameter was not included on the command-line.\n   */\n  required?: boolean;\n\n  /**\n   * The name of an environment variable that the parameter value will be read from,\n   * if it was omitted from the command-line.  An error will be reported if the\n   * environment value cannot be parsed.\n   *\n   * @remarks\n   * The environment variable name must consist only of upper-case letters, numbers,\n   * and underscores. It may not start with a number.\n   *\n   * This feature cannot be used when {@link IBaseCommandLineDefinition.required} is true,\n   * because in that case the environmentVariable would never be used.\n   *\n   * Syntax notes for environment variable values:\n   *\n   * - Choice Parameter: The value must match one of the defined choices,\n   *   otherwise a validation error is reported.\n   *   An empty string causes the environment variable to be ignored.\n   *\n   * - Flag Parameter: The value must be `1` for true, or `0` for false,\n   *   otherwise a validation error is reported.\n   *   An empty string causes the environment variable to be ignored.\n   *\n   * - Integer Parameter: The value must be an integer number,\n   *   otherwise a validation error is reported.\n   *   An empty string causes the environment variable to be ignored.\n   *\n   * - String Parameter: Any value is accepted, including an empty string.\n   *\n   * - String List Parameter: If the string starts with `[` (ignoring whitespace)\n   *   then it will be parsed as a JSON array, whose elements must be strings,\n   *   numbers, or boolean values.\n   *   If the string does not start with `[`, then it behaves like an\n   *   ordinary String Parameter:  Any value is accepted, including an empty string.\n   */\n  environmentVariable?: string;\n\n  /**\n   * Specifies additional names for this parameter that are accepted but not displayed\n   * in the command line help.\n   *\n   * @remarks\n   * This option can be used in cases where a command-line parameter may have been renamed,\n   * but the developer doesn't want to break backwards compatibility with systems that may\n   * still be using the old name. Only the `parameterLongName` syntax is currently allowed.\n   */\n  undocumentedSynonyms?: string[];\n}\n\n/**\n * The common base interface for parameter types that accept an argument.\n *\n * @remarks\n * An argument is an accompanying command-line token, such as \"123\" in the\n * example \"--max-count 123\".\n * @public\n */\nexport interface IBaseCommandLineDefinitionWithArgument extends IBaseCommandLineDefinition {\n  /**\n   * The name of the argument, which will be shown in the command-line help.\n   *\n   * @remarks\n   * For example, if the parameter name is '--count\" and the argument name is \"NUMBER\",\n   * then the command-line help would display \"--count NUMBER\".  The argument name must\n   * be comprised of upper-case letters, numbers, and underscores.  It should be kept short.\n   */\n  argumentName: string;\n\n  /**\n   * An optional callback that provides a list of custom choices for tab completion.\n   * @remarks\n   * This option is only used when `ICommandLineParserOptions.enableTabCompletionAction`\n   * is enabled.\n   */\n  completions?: () => Promise<string[]>;\n}\n\n/**\n * For use with {@link CommandLineParameterProvider.defineChoiceParameter},\n * this interface defines a command line parameter which is constrained to a list of possible\n * options.\n *\n * @public\n */\nexport interface ICommandLineChoiceDefinition extends IBaseCommandLineDefinition {\n  /**\n   * A list of strings (which contain no spaces), of possible options which can be selected\n   */\n  alternatives: string[];\n\n  /**\n   * {@inheritDoc ICommandLineStringDefinition.defaultValue}\n   */\n  defaultValue?: string;\n\n  /**\n   * An optional callback that provides a list of custom choices for tab completion.\n   * @remarks\n   * This option is only used when `ICommandLineParserOptions.enableTabCompletionAction`\n   * is enabled.\n   */\n  completions?: () => Promise<string[]>;\n}\n\n/**\n * For use with {@link CommandLineParameterProvider.defineChoiceListParameter},\n * this interface defines a command line parameter which is constrained to a list of possible\n * options. The parameter can be specified multiple times to build a list.\n *\n * @public\n */\nexport interface ICommandLineChoiceListDefinition extends IBaseCommandLineDefinition {\n  /**\n   * A list of strings (which contain no spaces), of possible options which can be selected\n   */\n  alternatives: string[];\n\n  /**\n   * An optional callback that provides a list of custom choices for tab completion.\n   * @remarks\n   * This option is only used when `ICommandLineParserOptions.enableTabCompletionAction`\n   * is enabled.\n   */\n  completions?: () => Promise<string[]>;\n}\n\n/**\n * For use with {@link CommandLineParameterProvider.defineFlagParameter},\n * this interface defines a command line parameter that is a boolean flag.\n *\n * @public\n */\nexport interface ICommandLineFlagDefinition extends IBaseCommandLineDefinition {}\n\n/**\n * For use with {@link CommandLineParameterProvider.defineIntegerParameter},\n * this interface defines a command line parameter whose argument is an integer value.\n *\n * @public\n */\nexport interface ICommandLineIntegerDefinition extends IBaseCommandLineDefinitionWithArgument {\n  /**\n   * {@inheritDoc ICommandLineStringDefinition.defaultValue}\n   */\n  defaultValue?: number;\n}\n\n/**\n * For use with {@link CommandLineParameterProvider.defineIntegerListParameter},\n * this interface defines a command line parameter whose argument is an integer value. The\n * parameter can be specified multiple times to build a list.\n *\n * @public\n */\nexport interface ICommandLineIntegerListDefinition extends IBaseCommandLineDefinitionWithArgument {}\n\n/**\n * For use with {@link CommandLineParameterProvider.defineStringParameter},\n * this interface defines a command line parameter whose argument is a string value.\n *\n * @public\n */\nexport interface ICommandLineStringDefinition extends IBaseCommandLineDefinitionWithArgument {\n  /**\n   * The default value which will be used if the parameter is omitted from the command line.\n   *\n   * @remarks\n   * If a default value is specified, then {@link IBaseCommandLineDefinition.required}\n   * must not be true.  Instead, a custom error message should be used to report cases\n   * where a default value was not available.\n   */\n  defaultValue?: string;\n}\n\n/**\n * For use with {@link CommandLineParameterProvider.defineStringListParameter},\n * this interface defines a command line parameter whose argument is a single text string.\n * The parameter can be specified multiple times to build a list.\n *\n * @public\n */\nexport interface ICommandLineStringListDefinition extends IBaseCommandLineDefinitionWithArgument {}\n\n/**\n * For use with {@link CommandLineParameterProvider.defineCommandLineRemainder},\n * this interface defines a rule that captures any remaining command line arguments after the recognized portion.\n *\n * @public\n */\nexport interface ICommandLineRemainderDefinition {\n  /**\n   * Documentation for how the remaining arguments will be used.  This will be shown when invoking\n   * the tool with \"--help\".\n   */\n  description: string;\n}\n"]}