@rushstack/ts-command-line 5.2.0 → 5.3.0

package/lib-esm/parameters/CommandLineFlagParameter.js

@@ -0,0 +1,65 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import { CommandLineParameterBase, CommandLineParameterKind } from './BaseClasses';
+/**
+ * The data type returned by {@link CommandLineParameterProvider.defineFlagParameter}.
+ * @public
+ */
+export class CommandLineFlagParameter extends CommandLineParameterBase {
+    /** @internal */
+    constructor(definition) {
+        super(definition);
+        this._value = false;
+        /** {@inheritDoc CommandLineParameterBase.kind} */
+        this.kind = CommandLineParameterKind.Flag;
+    }
+    /**
+     * {@inheritDoc CommandLineParameterBase._setValue}
+     * @internal
+     */
+    _setValue(data) {
+        // abstract
+        if (data !== null && data !== undefined) {
+            if (typeof data !== 'boolean') {
+                this.reportInvalidData(data);
+            }
+            // If the flag is omitted, then argparse sets the data to "false" instead of "undefined".
+            // This design prevents a syntax such as "--flag=false", probably because argparse prefers "--no-flag".
+            // If we switch to a new CLI parser, we should try to add support for "--flag=false".
+            if (data) {
+                this._value = data;
+                return;
+            }
+        }
+        if (this.environmentVariable !== undefined) {
+            // Try reading the environment variable
+            const environmentValue = process.env[this.environmentVariable];
+            if (environmentValue !== undefined && environmentValue !== '') {
+                if (environmentValue !== '0' && environmentValue !== '1') {
+                    throw new Error(`Invalid value "${environmentValue}" for the environment variable` +
+                        ` ${this.environmentVariable}.  Valid choices are 0 or 1.`);
+                }
+                this._value = environmentValue === '1';
+                return;
+            }
+        }
+        this._value = false;
+    }
+    /**
+     * Returns a boolean indicating whether the parameter was included in the command line.
+     *
+     * @remarks
+     * The return value will be false if the command-line has not been parsed yet,
+     * or if the flag was not used.
+     */
+    get value() {
+        return this._value;
+    }
+    /** {@inheritDoc CommandLineParameterBase.appendToArgList} @override */
+    appendToArgList(argList) {
+        if (this.value) {
+            argList.push(this.longName);
+        }
+    }
+}
+//# sourceMappingURL=CommandLineFlagParameter.js.map

package/lib-esm/parameters/CommandLineFlagParameter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandLineFlagParameter.js","sourceRoot":"","sources":["../../src/parameters/CommandLineFlagParameter.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAG3D,OAAO,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAEnF;;;GAGG;AACH,MAAM,OAAO,wBAAyB,SAAQ,wBAAwB;IAMpE,gBAAgB;IAChB,YAAmB,UAAsC;QACvD,KAAK,CAAC,UAAU,CAAC,CAAC;QAPZ,WAAM,GAAY,KAAK,CAAC;QAEhC,kDAAkD;QAClC,SAAI,GAAkC,wBAAwB,CAAC,IAAI,CAAC;IAKpF,CAAC;IAED;;;OAGG;IACI,SAAS,CAAC,IAAa;QAC5B,WAAW;QACX,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACxC,IAAI,OAAO,IAAI,KAAK,SAAS,EAAE,CAAC;gBAC9B,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;YAC/B,CAAC;YAED,yFAAyF;YACzF,uGAAuG;YACvG,qFAAqF;YACrF,IAAI,IAAI,EAAE,CAAC;gBACT,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;gBACnB,OAAO;YACT,CAAC;QACH,CAAC;QAED,IAAI,IAAI,CAAC,mBAAmB,KAAK,SAAS,EAAE,CAAC;YAC3C,uCAAuC;YACvC,MAAM,gBAAgB,GAAuB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;YACnF,IAAI,gBAAgB,KAAK,SAAS,IAAI,gBAAgB,KAAK,EAAE,EAAE,CAAC;gBAC9D,IAAI,gBAAgB,KAAK,GAAG,IAAI,gBAAgB,KAAK,GAAG,EAAE,CAAC;oBACzD,MAAM,IAAI,KAAK,CACb,kBAAkB,gBAAgB,gCAAgC;wBAChE,IAAI,IAAI,CAAC,mBAAmB,8BAA8B,CAC7D,CAAC;gBACJ,CAAC;gBACD,IAAI,CAAC,MAAM,GAAG,gBAAgB,KAAK,GAAG,CAAC;gBACvC,OAAO;YACT,CAAC;QACH,CAAC;QAED,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED;;;;;;OAMG;IACH,IAAW,KAAK;QACd,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,uEAAuE;IAChE,eAAe,CAAC,OAAiB;QACtC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;CACF","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 { ICommandLineFlagDefinition } from './CommandLineDefinition';\nimport { CommandLineParameterBase, CommandLineParameterKind } from './BaseClasses';\n\n/**\n * The data type returned by {@link CommandLineParameterProvider.defineFlagParameter}.\n * @public\n */\nexport class CommandLineFlagParameter extends CommandLineParameterBase {\n  private _value: boolean = false;\n\n  /** {@inheritDoc CommandLineParameterBase.kind} */\n  public readonly kind: CommandLineParameterKind.Flag = CommandLineParameterKind.Flag;\n\n  /** @internal */\n  public constructor(definition: ICommandLineFlagDefinition) {\n    super(definition);\n  }\n\n  /**\n   * {@inheritDoc CommandLineParameterBase._setValue}\n   * @internal\n   */\n  public _setValue(data: unknown): void {\n    // abstract\n    if (data !== null && data !== undefined) {\n      if (typeof data !== 'boolean') {\n        this.reportInvalidData(data);\n      }\n\n      // If the flag is omitted, then argparse sets the data to \"false\" instead of \"undefined\".\n      // This design prevents a syntax such as \"--flag=false\", probably because argparse prefers \"--no-flag\".\n      // If we switch to a new CLI parser, we should try to add support for \"--flag=false\".\n      if (data) {\n        this._value = data;\n        return;\n      }\n    }\n\n    if (this.environmentVariable !== undefined) {\n      // Try reading the environment variable\n      const environmentValue: string | undefined = process.env[this.environmentVariable];\n      if (environmentValue !== undefined && environmentValue !== '') {\n        if (environmentValue !== '0' && environmentValue !== '1') {\n          throw new Error(\n            `Invalid value \"${environmentValue}\" for the environment variable` +\n              ` ${this.environmentVariable}.  Valid choices are 0 or 1.`\n          );\n        }\n        this._value = environmentValue === '1';\n        return;\n      }\n    }\n\n    this._value = false;\n  }\n\n  /**\n   * Returns a boolean indicating whether the parameter was included in the command line.\n   *\n   * @remarks\n   * The return value will be false if the command-line has not been parsed yet,\n   * or if the flag was not used.\n   */\n  public get value(): boolean {\n    return this._value;\n  }\n\n  /** {@inheritDoc CommandLineParameterBase.appendToArgList} @override */\n  public appendToArgList(argList: string[]): void {\n    if (this.value) {\n      argList.push(this.longName);\n    }\n  }\n}\n"]}

package/lib-esm/parameters/CommandLineIntegerListParameter.js

@@ -0,0 +1,75 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import { CommandLineParameterWithArgument, CommandLineParameterKind } from './BaseClasses';
+import { EnvironmentVariableParser } from './EnvironmentVariableParser';
+/**
+ * The data type returned by {@link CommandLineParameterProvider.defineIntegerListParameter}.
+ * @public
+ */
+export class CommandLineIntegerListParameter extends CommandLineParameterWithArgument {
+    /** @internal */
+    constructor(definition) {
+        super(definition);
+        this._values = [];
+        /** {@inheritDoc CommandLineParameterBase.kind} */
+        this.kind = CommandLineParameterKind.IntegerList;
+    }
+    /**
+     * {@inheritDoc CommandLineParameterBase._setValue}
+     * @internal
+     */
+    _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 !== 'number') {
+                    this.reportInvalidData(data);
+                }
+            }
+            this._values = data;
+            return;
+        }
+        // If an environment variable exists, attempt to parse it as a list
+        if (this.environmentVariable !== undefined) {
+            const values = EnvironmentVariableParser.parseAsList(this.environmentVariable);
+            if (values) {
+                const parsedValues = [];
+                for (const value of values) {
+                    const parsed = parseInt(value, 10);
+                    if (isNaN(parsed) || value.indexOf('.') >= 0) {
+                        throw new Error(`Invalid value "${value}" for the environment variable` +
+                            ` ${this.environmentVariable}.  It must be an integer value.`);
+                    }
+                    parsedValues.push(parsed);
+                }
+                this._values = parsedValues;
+                return;
+            }
+        }
+        // (No default value for integer lists)
+        this._values = [];
+    }
+    /**
+     * Returns the integer arguments for an integer 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 CommandLineParameterBase.appendToArgList} @override */
+    appendToArgList(argList) {
+        if (this.values.length > 0) {
+            for (const value of this.values) {
+                argList.push(this.longName);
+                argList.push(value.toString());
+            }
+        }
+    }
+}
+//# sourceMappingURL=CommandLineIntegerListParameter.js.map

package/lib-esm/parameters/CommandLineIntegerListParameter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandLineIntegerListParameter.js","sourceRoot":"","sources":["../../src/parameters/CommandLineIntegerListParameter.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAG3D,OAAO,EAAE,gCAAgC,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAC3F,OAAO,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AAExE;;;GAGG;AACH,MAAM,OAAO,+BAAgC,SAAQ,gCAAgC;IAMnF,gBAAgB;IAChB,YAAmB,UAA6C;QAC9D,KAAK,CAAC,UAAU,CAAC,CAAC;QAPZ,YAAO,GAAa,EAAE,CAAC;QAE/B,kDAAkD;QAClC,SAAI,GAAyC,wBAAwB,CAAC,WAAW,CAAC;IAKlG,CAAC;IAED;;;OAGG;IACI,SAAS,CAAC,IAAa;QAC5B,qDAAqD;QACrD,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACxC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;gBACzB,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;YAC/B,CAAC;YACD,KAAK,MAAM,SAAS,IAAI,IAAI,EAAE,CAAC;gBAC7B,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;oBAClC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;gBAC/B,CAAC;YACH,CAAC;YACD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;YACpB,OAAO;QACT,CAAC;QAED,mEAAmE;QACnE,IAAI,IAAI,CAAC,mBAAmB,KAAK,SAAS,EAAE,CAAC;YAC3C,MAAM,MAAM,GAAyB,yBAAyB,CAAC,WAAW,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;YACrG,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,YAAY,GAAa,EAAE,CAAC;gBAClC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;oBAC3B,MAAM,MAAM,GAAW,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;oBAC3C,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;wBAC7C,MAAM,IAAI,KAAK,CACb,kBAAkB,KAAK,gCAAgC;4BACrD,IAAI,IAAI,CAAC,mBAAmB,iCAAiC,CAChE,CAAC;oBACJ,CAAC;oBACD,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBAC5B,CAAC;gBACD,IAAI,CAAC,OAAO,GAAG,YAAY,CAAC;gBAC5B,OAAO;YACT,CAAC;QACH,CAAC;QAED,uCAAuC;QAEvC,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;IACpB,CAAC;IAED;;;;;;OAMG;IACH,IAAW,MAAM;QACf,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,uEAAuE;IAChE,eAAe,CAAC,OAAiB;QACtC,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAChC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBAC5B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;YACjC,CAAC;QACH,CAAC;IACH,CAAC;CACF","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 { ICommandLineIntegerListDefinition } from './CommandLineDefinition';\nimport { CommandLineParameterWithArgument, CommandLineParameterKind } from './BaseClasses';\nimport { EnvironmentVariableParser } from './EnvironmentVariableParser';\n\n/**\n * The data type returned by {@link CommandLineParameterProvider.defineIntegerListParameter}.\n * @public\n */\nexport class CommandLineIntegerListParameter extends CommandLineParameterWithArgument {\n  private _values: number[] = [];\n\n  /** {@inheritDoc CommandLineParameterBase.kind} */\n  public readonly kind: CommandLineParameterKind.IntegerList = CommandLineParameterKind.IntegerList;\n\n  /** @internal */\n  public constructor(definition: ICommandLineIntegerListDefinition) {\n    super(definition);\n  }\n\n  /**\n   * {@inheritDoc CommandLineParameterBase._setValue}\n   * @internal\n   */\n  public _setValue(data: unknown): void {\n    // If argparse passed us a value, confirm it is valid\n    if (data !== null && data !== undefined) {\n      if (!Array.isArray(data)) {\n        this.reportInvalidData(data);\n      }\n      for (const arrayItem of data) {\n        if (typeof arrayItem !== 'number') {\n          this.reportInvalidData(data);\n        }\n      }\n      this._values = data;\n      return;\n    }\n\n    // If an environment variable exists, attempt to parse it as a list\n    if (this.environmentVariable !== undefined) {\n      const values: string[] | undefined = EnvironmentVariableParser.parseAsList(this.environmentVariable);\n      if (values) {\n        const parsedValues: number[] = [];\n        for (const value of values) {\n          const parsed: number = parseInt(value, 10);\n          if (isNaN(parsed) || value.indexOf('.') >= 0) {\n            throw new Error(\n              `Invalid value \"${value}\" for the environment variable` +\n                ` ${this.environmentVariable}.  It must be an integer value.`\n            );\n          }\n          parsedValues.push(parsed);\n        }\n        this._values = parsedValues;\n        return;\n      }\n    }\n\n    // (No default value for integer lists)\n\n    this._values = [];\n  }\n\n  /**\n   * Returns the integer arguments for an integer list parameter that was parsed from the command line.\n   *\n   * @remarks\n   * The array will be empty if the command-line has not been parsed yet,\n   * or if the parameter was omitted and has no default value.\n   */\n  public get values(): ReadonlyArray<number> {\n    return this._values;\n  }\n\n  /** {@inheritDoc CommandLineParameterBase.appendToArgList} @override */\n  public appendToArgList(argList: string[]): void {\n    if (this.values.length > 0) {\n      for (const value of this.values) {\n        argList.push(this.longName);\n        argList.push(value.toString());\n      }\n    }\n  }\n}\n"]}

package/lib-esm/parameters/CommandLineIntegerParameter.js

@@ -0,0 +1,79 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import { CommandLineParameterWithArgument, CommandLineParameterKind } from './BaseClasses';
+/**
+ * The data type returned by {@link CommandLineParameterProvider.(defineIntegerParameter:1)}.
+ * @public
+ */
+export class CommandLineIntegerParameter extends CommandLineParameterWithArgument {
+    /** @internal */
+    constructor(definition) {
+        super(definition);
+        this._value = undefined;
+        /** {@inheritDoc CommandLineParameterBase.kind} */
+        this.kind = CommandLineParameterKind.Integer;
+        this.defaultValue = definition.defaultValue;
+        this.validateDefaultValue(!!this.defaultValue);
+    }
+    /**
+     * {@inheritDoc CommandLineParameterBase._setValue}
+     * @internal
+     */
+    _setValue(data) {
+        // abstract
+        if (data !== null && data !== undefined) {
+            if (typeof data !== 'number') {
+                this.reportInvalidData(data);
+            }
+            this._value = data;
+            return;
+        }
+        if (this.environmentVariable !== undefined) {
+            // Try reading the environment variable
+            const environmentValue = process.env[this.environmentVariable];
+            if (environmentValue !== undefined && environmentValue !== '') {
+                const parsed = parseInt(environmentValue, 10);
+                if (isNaN(parsed) || environmentValue.indexOf('.') >= 0) {
+                    throw new Error(`Invalid value "${environmentValue}" for the environment variable` +
+                        ` ${this.environmentVariable}.  It must be an integer value.`);
+                }
+                this._value = parsed;
+                return;
+            }
+        }
+        if (this.defaultValue !== undefined) {
+            this._value = this.defaultValue;
+            return;
+        }
+        this._value = undefined;
+    }
+    /**
+     * {@inheritDoc CommandLineParameterBase._getSupplementaryNotes}
+     * @internal
+     */
+    _getSupplementaryNotes(supplementaryNotes) {
+        // virtual
+        super._getSupplementaryNotes(supplementaryNotes);
+        if (this.defaultValue !== undefined) {
+            supplementaryNotes.push(`The default value is ${this.defaultValue}.`);
+        }
+    }
+    /**
+     * Returns the argument value for an integer parameter that was parsed from the command line.
+     *
+     * @remarks
+     * The return value will be undefined if the command-line has not been parsed yet,
+     * or if the parameter was omitted and has no default value.
+     */
+    get value() {
+        return this._value;
+    }
+    /** {@inheritDoc CommandLineParameterBase.appendToArgList} @override */
+    appendToArgList(argList) {
+        if (this.value !== undefined) {
+            argList.push(this.longName);
+            argList.push(this.value.toString());
+        }
+    }
+}
+//# sourceMappingURL=CommandLineIntegerParameter.js.map

package/lib-esm/parameters/CommandLineIntegerParameter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandLineIntegerParameter.js","sourceRoot":"","sources":["../../src/parameters/CommandLineIntegerParameter.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAG3D,OAAO,EAAE,gCAAgC,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAU3F;;;GAGG;AACH,MAAM,OAAO,2BAA4B,SAAQ,gCAAgC;IAS/E,gBAAgB;IAChB,YAAmB,UAAyC;QAC1D,KAAK,CAAC,UAAU,CAAC,CAAC;QAPZ,WAAM,GAAuB,SAAS,CAAC;QAE/C,kDAAkD;QAClC,SAAI,GAAqC,wBAAwB,CAAC,OAAO,CAAC;QAKxF,IAAI,CAAC,YAAY,GAAG,UAAU,CAAC,YAAY,CAAC;QAC5C,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACjD,CAAC;IAED;;;OAGG;IACI,SAAS,CAAC,IAAa;QAC5B,WAAW;QACX,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACxC,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC7B,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;YAC/B,CAAC;YACD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;YACnB,OAAO;QACT,CAAC;QAED,IAAI,IAAI,CAAC,mBAAmB,KAAK,SAAS,EAAE,CAAC;YAC3C,uCAAuC;YACvC,MAAM,gBAAgB,GAAuB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;YACnF,IAAI,gBAAgB,KAAK,SAAS,IAAI,gBAAgB,KAAK,EAAE,EAAE,CAAC;gBAC9D,MAAM,MAAM,GAAW,QAAQ,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC;gBACtD,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,gBAAgB,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;oBACxD,MAAM,IAAI,KAAK,CACb,kBAAkB,gBAAgB,gCAAgC;wBAChE,IAAI,IAAI,CAAC,mBAAmB,iCAAiC,CAChE,CAAC;gBACJ,CAAC;gBACD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;gBACrB,OAAO;YACT,CAAC;QACH,CAAC;QAED,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YACpC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC;YAChC,OAAO;QACT,CAAC;QAED,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;IAC1B,CAAC;IAED;;;OAGG;IACI,sBAAsB,CAAC,kBAA4B;QACxD,UAAU;QACV,KAAK,CAAC,sBAAsB,CAAC,kBAAkB,CAAC,CAAC;QACjD,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YACpC,kBAAkB,CAAC,IAAI,CAAC,wBAAwB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,IAAW,KAAK;QACd,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,uEAAuE;IAChE,eAAe,CAAC,OAAiB;QACtC,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC7B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC5B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;CACF","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 { ICommandLineIntegerDefinition } from './CommandLineDefinition';\nimport { CommandLineParameterWithArgument, CommandLineParameterKind } from './BaseClasses';\n\n/**\n * The data type returned by {@link CommandLineParameterProvider.(defineIntegerParameter:2)}.\n * @public\n */\nexport interface IRequiredCommandLineIntegerParameter extends CommandLineIntegerParameter {\n  readonly value: number;\n}\n\n/**\n * The data type returned by {@link CommandLineParameterProvider.(defineIntegerParameter:1)}.\n * @public\n */\nexport class CommandLineIntegerParameter extends CommandLineParameterWithArgument {\n  /** {@inheritDoc ICommandLineStringDefinition.defaultValue} */\n  public readonly defaultValue: number | undefined;\n\n  private _value: number | undefined = undefined;\n\n  /** {@inheritDoc CommandLineParameterBase.kind} */\n  public readonly kind: CommandLineParameterKind.Integer = CommandLineParameterKind.Integer;\n\n  /** @internal */\n  public constructor(definition: ICommandLineIntegerDefinition) {\n    super(definition);\n    this.defaultValue = definition.defaultValue;\n    this.validateDefaultValue(!!this.defaultValue);\n  }\n\n  /**\n   * {@inheritDoc CommandLineParameterBase._setValue}\n   * @internal\n   */\n  public _setValue(data: unknown): void {\n    // abstract\n    if (data !== null && data !== undefined) {\n      if (typeof data !== 'number') {\n        this.reportInvalidData(data);\n      }\n      this._value = data;\n      return;\n    }\n\n    if (this.environmentVariable !== undefined) {\n      // Try reading the environment variable\n      const environmentValue: string | undefined = process.env[this.environmentVariable];\n      if (environmentValue !== undefined && environmentValue !== '') {\n        const parsed: number = parseInt(environmentValue, 10);\n        if (isNaN(parsed) || environmentValue.indexOf('.') >= 0) {\n          throw new Error(\n            `Invalid value \"${environmentValue}\" for the environment variable` +\n              ` ${this.environmentVariable}.  It must be an integer value.`\n          );\n        }\n        this._value = parsed;\n        return;\n      }\n    }\n\n    if (this.defaultValue !== undefined) {\n      this._value = this.defaultValue;\n      return;\n    }\n\n    this._value = undefined;\n  }\n\n  /**\n   * {@inheritDoc CommandLineParameterBase._getSupplementaryNotes}\n   * @internal\n   */\n  public _getSupplementaryNotes(supplementaryNotes: string[]): void {\n    // virtual\n    super._getSupplementaryNotes(supplementaryNotes);\n    if (this.defaultValue !== undefined) {\n      supplementaryNotes.push(`The default value is ${this.defaultValue}.`);\n    }\n  }\n\n  /**\n   * Returns the argument value for an integer parameter that was parsed from the command line.\n   *\n   * @remarks\n   * The return value will be undefined if the command-line has not been parsed yet,\n   * or if the parameter was omitted and has no default value.\n   */\n  public get value(): number | undefined {\n    return this._value;\n  }\n\n  /** {@inheritDoc CommandLineParameterBase.appendToArgList} @override */\n  public appendToArgList(argList: string[]): void {\n    if (this.value !== undefined) {\n      argList.push(this.longName);\n      argList.push(this.value.toString());\n    }\n  }\n}\n"]}

package/lib-esm/parameters/CommandLineRemainder.js

@@ -0,0 +1,43 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+/**
+ * The data type returned by {@link CommandLineParameterProvider.defineCommandLineRemainder}.
+ * @public
+ */
+export class CommandLineRemainder {
+    /** @internal */
+    constructor(definition) {
+        this._values = [];
+        this.description = definition.description;
+    }
+    /**
+     * Returns any remaining command line arguments after the recognized portion
+     * that was parsed from the command line.
+     *
+     * @remarks
+     * The array will be empty if the command-line has not been parsed yet.
+     */
+    get values() {
+        return this._values;
+    }
+    /**
+     * {@inheritDoc CommandLineParameterBase._setValue}
+     * @internal
+     */
+    _setValue(data) {
+        // abstract
+        if (!Array.isArray(data) || !data.every((x) => typeof x === 'string')) {
+            throw new Error(`Unexpected data object for remainder: ` + JSON.stringify(data));
+        }
+        this._values.push(...data);
+    }
+    /** {@inheritDoc CommandLineParameterBase.appendToArgList} @override */
+    appendToArgList(argList) {
+        if (this.values.length > 0) {
+            for (const value of this.values) {
+                argList.push(value);
+            }
+        }
+    }
+}
+//# sourceMappingURL=CommandLineRemainder.js.map

package/lib-esm/parameters/CommandLineRemainder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandLineRemainder.js","sourceRoot":"","sources":["../../src/parameters/CommandLineRemainder.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAI3D;;;GAGG;AACH,MAAM,OAAO,oBAAoB;IAM/B,gBAAgB;IAChB,YAAmB,UAA2C;QANtD,YAAO,GAAa,EAAE,CAAC;QAO7B,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC,WAAW,CAAC;IAC5C,CAAC;IAED;;;;;;OAMG;IACH,IAAW,MAAM;QACf,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED;;;OAGG;IACI,SAAS,CAAC,IAAa;QAC5B,WAAW;QACX,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,EAAE,CAAC;YACtE,MAAM,IAAI,KAAK,CAAC,wCAAwC,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;QACnF,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED,uEAAuE;IAChE,eAAe,CAAC,OAAiB;QACtC,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAChC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;IACH,CAAC;CACF","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 { ICommandLineRemainderDefinition } from './CommandLineDefinition';\n\n/**\n * The data type returned by {@link CommandLineParameterProvider.defineCommandLineRemainder}.\n * @public\n */\nexport class CommandLineRemainder {\n  private _values: string[] = [];\n\n  /** {@inheritDoc IBaseCommandLineDefinition.description} */\n  public readonly description: string;\n\n  /** @internal */\n  public constructor(definition: ICommandLineRemainderDefinition) {\n    this.description = definition.description;\n  }\n\n  /**\n   * Returns any remaining command line arguments after the recognized portion\n   * that was parsed from the command line.\n   *\n   * @remarks\n   * The array will be empty if the command-line has not been parsed yet.\n   */\n  public get values(): ReadonlyArray<string> {\n    return this._values;\n  }\n\n  /**\n   * {@inheritDoc CommandLineParameterBase._setValue}\n   * @internal\n   */\n  public _setValue(data: unknown): void {\n    // abstract\n    if (!Array.isArray(data) || !data.every((x) => typeof x === 'string')) {\n      throw new Error(`Unexpected data object for remainder: ` + JSON.stringify(data));\n    }\n\n    this._values.push(...data);\n  }\n\n  /** {@inheritDoc CommandLineParameterBase.appendToArgList} @override */\n  public appendToArgList(argList: string[]): void {\n    if (this.values.length > 0) {\n      for (const value of this.values) {\n        argList.push(value);\n      }\n    }\n  }\n}\n"]}

package/lib-esm/parameters/CommandLineStringListParameter.js

@@ -0,0 +1,66 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import { CommandLineParameterWithArgument, CommandLineParameterKind } from './BaseClasses';
+import { EnvironmentVariableParser } from './EnvironmentVariableParser';
+/**
+ * The data type returned by {@link CommandLineParameterProvider.defineStringListParameter}.
+ * @public
+ */
+export class CommandLineStringListParameter extends CommandLineParameterWithArgument {
+    /** @internal */
+    constructor(definition) {
+        super(definition);
+        this._values = [];
+        /** {@inheritDoc CommandLineParameterBase.kind} */
+        this.kind = CommandLineParameterKind.StringList;
+    }
+    /**
+     * {@inheritDoc CommandLineParameterBase._setValue}
+     * @internal
+     */
+    _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 an environment variable exists, attempt to parse it as a list
+        if (this.environmentVariable !== undefined) {
+            const values = EnvironmentVariableParser.parseAsList(this.environmentVariable);
+            if (values) {
+                this._values = values;
+                return;
+            }
+        }
+        // (No default value for string lists)
+        this._values = [];
+    }
+    /**
+     * Returns the string arguments for a string 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 CommandLineParameterBase.appendToArgList} @override */
+    appendToArgList(argList) {
+        if (this.values.length > 0) {
+            for (const value of this.values) {
+                argList.push(this.longName);
+                argList.push(value);
+            }
+        }
+    }
+}
+//# sourceMappingURL=CommandLineStringListParameter.js.map

package/lib-esm/parameters/CommandLineStringListParameter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandLineStringListParameter.js","sourceRoot":"","sources":["../../src/parameters/CommandLineStringListParameter.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAG3D,OAAO,EAAE,gCAAgC,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAC3F,OAAO,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AAExE;;;GAGG;AACH,MAAM,OAAO,8BAA+B,SAAQ,gCAAgC;IAMlF,gBAAgB;IAChB,YAAmB,UAA4C;QAC7D,KAAK,CAAC,UAAU,CAAC,CAAC;QAPZ,YAAO,GAAa,EAAE,CAAC;QAE/B,kDAAkD;QAClC,SAAI,GAAwC,wBAAwB,CAAC,UAAU,CAAC;IAKhG,CAAC;IAED;;;OAGG;IACI,SAAS,CAAC,IAAa;QAC5B,qDAAqD;QACrD,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACxC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;gBACzB,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;YAC/B,CAAC;YACD,KAAK,MAAM,SAAS,IAAI,IAAI,EAAE,CAAC;gBAC7B,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;oBAClC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;gBAC/B,CAAC;YACH,CAAC;YACD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;YACpB,OAAO;QACT,CAAC;QAED,mEAAmE;QACnE,IAAI,IAAI,CAAC,mBAAmB,KAAK,SAAS,EAAE,CAAC;YAC3C,MAAM,MAAM,GAAyB,yBAAyB,CAAC,WAAW,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;YACrG,IAAI,MAAM,EAAE,CAAC;gBACX,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;gBACtB,OAAO;YACT,CAAC;QACH,CAAC;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,uEAAuE;IAChE,eAAe,CAAC,OAAiB;QACtC,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAChC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBAC5B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;IACH,CAAC;CACF","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 { ICommandLineStringListDefinition } from './CommandLineDefinition';\nimport { CommandLineParameterWithArgument, CommandLineParameterKind } from './BaseClasses';\nimport { EnvironmentVariableParser } from './EnvironmentVariableParser';\n\n/**\n * The data type returned by {@link CommandLineParameterProvider.defineStringListParameter}.\n * @public\n */\nexport class CommandLineStringListParameter extends CommandLineParameterWithArgument {\n  private _values: string[] = [];\n\n  /** {@inheritDoc CommandLineParameterBase.kind} */\n  public readonly kind: CommandLineParameterKind.StringList = CommandLineParameterKind.StringList;\n\n  /** @internal */\n  public constructor(definition: ICommandLineStringListDefinition) {\n    super(definition);\n  }\n\n  /**\n   * {@inheritDoc CommandLineParameterBase._setValue}\n   * @internal\n   */\n  public _setValue(data: unknown): void {\n    // If argparse passed us a value, confirm it is valid\n    if (data !== null && data !== undefined) {\n      if (!Array.isArray(data)) {\n        this.reportInvalidData(data);\n      }\n      for (const arrayItem of data) {\n        if (typeof arrayItem !== 'string') {\n          this.reportInvalidData(data);\n        }\n      }\n      this._values = data;\n      return;\n    }\n\n    // If an environment variable exists, attempt to parse it as a list\n    if (this.environmentVariable !== undefined) {\n      const values: string[] | undefined = EnvironmentVariableParser.parseAsList(this.environmentVariable);\n      if (values) {\n        this._values = values;\n        return;\n      }\n    }\n\n    // (No default value for string lists)\n\n    this._values = [];\n  }\n\n  /**\n   * Returns the string arguments for a string list parameter that was parsed from the command line.\n   *\n   * @remarks\n   * The array will be empty if the command-line has not been parsed yet,\n   * or if the parameter was omitted and has no default value.\n   */\n  public get values(): ReadonlyArray<string> {\n    return this._values;\n  }\n\n  /** {@inheritDoc CommandLineParameterBase.appendToArgList} @override */\n  public appendToArgList(argList: string[]): void {\n    if (this.values.length > 0) {\n      for (const value of this.values) {\n        argList.push(this.longName);\n        argList.push(value);\n      }\n    }\n  }\n}\n"]}

package/lib-esm/parameters/CommandLineStringParameter.js

@@ -0,0 +1,78 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+import { CommandLineParameterWithArgument, CommandLineParameterKind } from './BaseClasses';
+/**
+ * The data type returned by {@link CommandLineParameterProvider.(defineStringParameter:1)}.
+ * @public
+ */
+export class CommandLineStringParameter extends CommandLineParameterWithArgument {
+    /** @internal */
+    constructor(definition) {
+        super(definition);
+        this._value = undefined;
+        /** {@inheritDoc CommandLineParameterBase.kind} */
+        this.kind = CommandLineParameterKind.String;
+        this.defaultValue = definition.defaultValue;
+        this.validateDefaultValue(!!this.defaultValue);
+    }
+    /**
+     * {@inheritDoc CommandLineParameterBase._setValue}
+     * @internal
+     */
+    _setValue(data) {
+        // abstract
+        if (data !== null && data !== undefined) {
+            if (typeof data !== 'string') {
+                this.reportInvalidData(data);
+            }
+            this._value = data;
+            return;
+        }
+        if (this.environmentVariable !== undefined) {
+            // Try reading the environment variable
+            const environmentValue = process.env[this.environmentVariable];
+            if (environmentValue !== undefined) {
+                // NOTE: If the environment variable is defined as an empty string,
+                // here we will accept the empty string as our value.  (For number/flag we don't do that.)
+                this._value = environmentValue;
+                return;
+            }
+        }
+        if (this.defaultValue !== undefined) {
+            this._value = this.defaultValue;
+            return;
+        }
+        this._value = undefined;
+    }
+    /**
+     * {@inheritDoc CommandLineParameterBase._getSupplementaryNotes}
+     * @internal
+     */
+    _getSupplementaryNotes(supplementaryNotes) {
+        // virtual
+        super._getSupplementaryNotes(supplementaryNotes);
+        if (this.defaultValue !== undefined) {
+            if (this.defaultValue.length < 160) {
+                supplementaryNotes.push(`The default value is ${JSON.stringify(this.defaultValue)}.`);
+            }
+        }
+    }
+    /**
+     * Returns the argument value for a string parameter that was parsed from the command line.
+     *
+     * @remarks
+     * The return value will be undefined if the command-line has not been parsed yet,
+     * or if the parameter was omitted and has no default value.
+     */
+    get value() {
+        return this._value;
+    }
+    /** {@inheritDoc CommandLineParameterBase.appendToArgList} @override */
+    appendToArgList(argList) {
+        if (this.value !== undefined) {
+            argList.push(this.longName);
+            argList.push(this.value);
+        }
+    }
+}
+//# sourceMappingURL=CommandLineStringParameter.js.map

package/lib-esm/parameters/CommandLineStringParameter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandLineStringParameter.js","sourceRoot":"","sources":["../../src/parameters/CommandLineStringParameter.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAG3D,OAAO,EAAE,gCAAgC,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAU3F;;;GAGG;AACH,MAAM,OAAO,0BAA2B,SAAQ,gCAAgC;IAS9E,gBAAgB;IAChB,YAAmB,UAAwC;QACzD,KAAK,CAAC,UAAU,CAAC,CAAC;QAPZ,WAAM,GAAuB,SAAS,CAAC;QAE/C,kDAAkD;QAClC,SAAI,GAAoC,wBAAwB,CAAC,MAAM,CAAC;QAMtF,IAAI,CAAC,YAAY,GAAG,UAAU,CAAC,YAAY,CAAC;QAC5C,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACjD,CAAC;IAED;;;OAGG;IACI,SAAS,CAAC,IAAa;QAC5B,WAAW;QACX,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACxC,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC7B,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;YAC/B,CAAC;YACD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;YACnB,OAAO;QACT,CAAC;QAED,IAAI,IAAI,CAAC,mBAAmB,KAAK,SAAS,EAAE,CAAC;YAC3C,uCAAuC;YACvC,MAAM,gBAAgB,GAAuB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;YACnF,IAAI,gBAAgB,KAAK,SAAS,EAAE,CAAC;gBACnC,mEAAmE;gBACnE,0FAA0F;gBAC1F,IAAI,CAAC,MAAM,GAAG,gBAAgB,CAAC;gBAC/B,OAAO;YACT,CAAC;QACH,CAAC;QAED,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YACpC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC;YAChC,OAAO;QACT,CAAC;QAED,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;IAC1B,CAAC;IAED;;;OAGG;IACI,sBAAsB,CAAC,kBAA4B;QACxD,UAAU;QACV,KAAK,CAAC,sBAAsB,CAAC,kBAAkB,CAAC,CAAC;QACjD,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YACpC,IAAI,IAAI,CAAC,YAAY,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;gBACnC,kBAAkB,CAAC,IAAI,CAAC,wBAAwB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;YACxF,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,IAAW,KAAK;QACd,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,uEAAuE;IAChE,eAAe,CAAC,OAAiB;QACtC,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC7B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC5B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;CACF","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 { ICommandLineStringDefinition } from './CommandLineDefinition';\nimport { CommandLineParameterWithArgument, CommandLineParameterKind } from './BaseClasses';\n\n/**\n * The data type returned by {@link CommandLineParameterProvider.(defineStringParameter:2)}.\n * @public\n */\nexport interface IRequiredCommandLineStringParameter extends CommandLineStringParameter {\n  readonly value: string;\n}\n\n/**\n * The data type returned by {@link CommandLineParameterProvider.(defineStringParameter:1)}.\n * @public\n */\nexport class CommandLineStringParameter extends CommandLineParameterWithArgument {\n  /** {@inheritDoc ICommandLineStringDefinition.defaultValue} */\n  public readonly defaultValue: string | undefined;\n\n  private _value: string | undefined = undefined;\n\n  /** {@inheritDoc CommandLineParameterBase.kind} */\n  public readonly kind: CommandLineParameterKind.String = CommandLineParameterKind.String;\n\n  /** @internal */\n  public constructor(definition: ICommandLineStringDefinition) {\n    super(definition);\n\n    this.defaultValue = definition.defaultValue;\n    this.validateDefaultValue(!!this.defaultValue);\n  }\n\n  /**\n   * {@inheritDoc CommandLineParameterBase._setValue}\n   * @internal\n   */\n  public _setValue(data: unknown): void {\n    // abstract\n    if (data !== null && data !== undefined) {\n      if (typeof data !== 'string') {\n        this.reportInvalidData(data);\n      }\n      this._value = data;\n      return;\n    }\n\n    if (this.environmentVariable !== undefined) {\n      // Try reading the environment variable\n      const environmentValue: string | undefined = process.env[this.environmentVariable];\n      if (environmentValue !== undefined) {\n        // NOTE: If the environment variable is defined as an empty string,\n        // here we will accept the empty string as our value.  (For number/flag we don't do that.)\n        this._value = environmentValue;\n        return;\n      }\n    }\n\n    if (this.defaultValue !== undefined) {\n      this._value = this.defaultValue;\n      return;\n    }\n\n    this._value = undefined;\n  }\n\n  /**\n   * {@inheritDoc CommandLineParameterBase._getSupplementaryNotes}\n   * @internal\n   */\n  public _getSupplementaryNotes(supplementaryNotes: string[]): void {\n    // virtual\n    super._getSupplementaryNotes(supplementaryNotes);\n    if (this.defaultValue !== undefined) {\n      if (this.defaultValue.length < 160) {\n        supplementaryNotes.push(`The default value is ${JSON.stringify(this.defaultValue)}.`);\n      }\n    }\n  }\n\n  /**\n   * Returns the argument value for a string parameter that was parsed from the command line.\n   *\n   * @remarks\n   * The return value will be undefined if the command-line has not been parsed yet,\n   * or if the parameter was omitted and has no default value.\n   */\n  public get value(): string | undefined {\n    return this._value;\n  }\n\n  /** {@inheritDoc CommandLineParameterBase.appendToArgList} @override */\n  public appendToArgList(argList: string[]): void {\n    if (this.value !== undefined) {\n      argList.push(this.longName);\n      argList.push(this.value);\n    }\n  }\n}\n"]}

package/lib-esm/parameters/EnvironmentVariableParser.js

@@ -0,0 +1,47 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+/**
+ * Some parameter types can receive their values from an environment variable instead of
+ * a command line argument. This class provides some utility methods for parsing environment
+ * variable values.
+ * @internal
+ */
+export class EnvironmentVariableParser {
+    static parseAsList(envVarName) {
+        const environmentValue = process.env[envVarName];
+        if (environmentValue !== undefined) {
+            // NOTE: If the environment variable is defined as an empty string,
+            // here we will accept the empty string as our value.  (For number/flag we don't do that.)
+            if (environmentValue.trimLeft()[0] === '[') {
+                // Specifying multiple items in an environment variable is a somewhat rare case.  But environment
+                // variables are actually a pretty reliable way for a tool to avoid shell escaping problems
+                // when spawning another tool.  For this case, we need a reliable way to pass an array of strings
+                // that could contain any character.  For example, if we simply used ";" as the list delimiter,
+                // then what to do if a string contains that character?  We'd need to design an escaping mechanism.
+                // Since JSON is simple and standard and can escape every possible string, it's a better option
+                // than a custom delimiter.
+                try {
+                    const parsedJson = JSON.parse(environmentValue);
+                    if (!Array.isArray(parsedJson) ||
+                        !parsedJson.every((x) => typeof x === 'string' || typeof x === 'boolean' || typeof x === 'number')) {
+                        throw new Error(`The ${environmentValue} environment variable value must be a JSON ` +
+                            ` array containing only strings, numbers, and booleans.`);
+                    }
+                    return parsedJson.map((x) => x.toString());
+                }
+                catch (ex) {
+                    throw new Error(`The ${environmentValue} environment variable value looks like a JSON array` +
+                        ` but failed to parse: ` +
+                        ex.message);
+                }
+            }
+            else {
+                // As a shorthand, a single value may be specified without JSON encoding, as long as it does not
+                // start with the "[" character.
+                return [environmentValue];
+            }
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=EnvironmentVariableParser.js.map

package/lib-esm/parameters/EnvironmentVariableParser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EnvironmentVariableParser.js","sourceRoot":"","sources":["../../src/parameters/EnvironmentVariableParser.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,2DAA2D;AAE3D;;;;;GAKG;AACH,MAAM,OAAO,yBAAyB;IAC7B,MAAM,CAAC,WAAW,CAAC,UAAkB;QAC1C,MAAM,gBAAgB,GAAuB,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAErE,IAAI,gBAAgB,KAAK,SAAS,EAAE,CAAC;YACnC,mEAAmE;YACnE,0FAA0F;YAE1F,IAAI,gBAAgB,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;gBAC3C,iGAAiG;gBACjG,2FAA2F;gBAC3F,iGAAiG;gBACjG,+FAA+F;gBAC/F,mGAAmG;gBACnG,+FAA+F;gBAC/F,2BAA2B;gBAC3B,IAAI,CAAC;oBACH,MAAM,UAAU,GAAY,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;oBACzD,IACE,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC;wBAC1B,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,SAAS,IAAI,OAAO,CAAC,KAAK,QAAQ,CAAC,EAClG,CAAC;wBACD,MAAM,IAAI,KAAK,CACb,OAAO,gBAAgB,6CAA6C;4BAClE,wDAAwD,CAC3D,CAAC;oBACJ,CAAC;oBACD,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;gBAC7C,CAAC;gBAAC,OAAO,EAAE,EAAE,CAAC;oBACZ,MAAM,IAAI,KAAK,CACb,OAAO,gBAAgB,qDAAqD;wBAC1E,wBAAwB;wBACvB,EAAY,CAAC,OAAO,CACxB,CAAC;gBACJ,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,gGAAgG;gBAChG,gCAAgC;gBAChC,OAAO,CAAC,gBAAgB,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;CACF","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 * Some parameter types can receive their values from an environment variable instead of\n * a command line argument. This class provides some utility methods for parsing environment\n * variable values.\n * @internal\n */\nexport class EnvironmentVariableParser {\n  public static parseAsList(envVarName: string): string[] | undefined {\n    const environmentValue: string | undefined = process.env[envVarName];\n\n    if (environmentValue !== undefined) {\n      // NOTE: If the environment variable is defined as an empty string,\n      // here we will accept the empty string as our value.  (For number/flag we don't do that.)\n\n      if (environmentValue.trimLeft()[0] === '[') {\n        // Specifying multiple items in an environment variable is a somewhat rare case.  But environment\n        // variables are actually a pretty reliable way for a tool to avoid shell escaping problems\n        // when spawning another tool.  For this case, we need a reliable way to pass an array of strings\n        // that could contain any character.  For example, if we simply used \";\" as the list delimiter,\n        // then what to do if a string contains that character?  We'd need to design an escaping mechanism.\n        // Since JSON is simple and standard and can escape every possible string, it's a better option\n        // than a custom delimiter.\n        try {\n          const parsedJson: unknown = JSON.parse(environmentValue);\n          if (\n            !Array.isArray(parsedJson) ||\n            !parsedJson.every((x) => typeof x === 'string' || typeof x === 'boolean' || typeof x === 'number')\n          ) {\n            throw new Error(\n              `The ${environmentValue} environment variable value must be a JSON ` +\n                ` array containing only strings, numbers, and booleans.`\n            );\n          }\n          return parsedJson.map((x) => x.toString());\n        } catch (ex) {\n          throw new Error(\n            `The ${environmentValue} environment variable value looks like a JSON array` +\n              ` but failed to parse: ` +\n              (ex as Error).message\n          );\n        }\n      } else {\n        // As a shorthand, a single value may be specified without JSON encoding, as long as it does not\n        // start with the \"[\" character.\n        return [environmentValue];\n      }\n    }\n\n    return undefined;\n  }\n}\n"]}