@rushstack/ts-command-line - npm Package Compare versions

Comparing version 4.3.14 to 4.4.0

CHANGELOG.json

@@ -5,2 +5,31 @@ {
     {
+      "version": "4.4.0",
+      "tag": "@rushstack/ts-command-line_v4.4.0",
+      "date": "Fri, 15 May 2020 08:10:59 GMT",
+      "comments": {
+        "minor": [
+          {
+            "comment": "Add a new feature defineCommandLineRemainder() which allows additional unvalidated CLI arguments, e.g. to pass along to another tool"
+          },
+          {
+            "comment": "Add the ability for an environment variable to specify multiple values for CommandLineStringListParameter, encoded as a JSON array"
+          },
+          {
+            "comment": "Fix some bugs that prevented a CommandLineParser from being defined without any actions"
+          }
+        ],
+        "patch": [
+          {
+            "comment": "Fix a bug with environmentVariable mapping for CommandLineFlagParameter"
+          },
+          {
+            "comment": "Use API Extractor to trim internal APIs from the .d.ts rollup"
+          },
+          {
+            "comment": "Improve the README.md and API documentation"
+          }
+        ]
+      }
+    },
+    {
       "version": "4.3.14",
@@ -7,0 +36,0 @@ "tag": "@rushstack/ts-command-line_v4.3.14",

CHANGELOG.md

 # Change Log - @rushstack/ts-command-line
 
-This log was last generated on Wed, 08 Apr 2020 04:07:33 GMT and should not be manually modified.
+This log was last generated on Fri, 15 May 2020 08:10:59 GMT and should not be manually modified.
 
+## 4.4.0
+Fri, 15 May 2020 08:10:59 GMT
+
+### Minor changes
+
+- Add a new feature defineCommandLineRemainder() which allows additional unvalidated CLI arguments, e.g. to pass along to another tool
+- Add the ability for an environment variable to specify multiple values for CommandLineStringListParameter, encoded as a JSON array
+- Fix some bugs that prevented a CommandLineParser from being defined without any actions
+
+### Patches
+
+- Fix a bug with environmentVariable mapping for CommandLineFlagParameter
+- Use API Extractor to trim internal APIs from the .d.ts rollup
+- Improve the README.md and API documentation
+
 ## 4.3.14
@@ -6,0 +21,0 @@ Wed, 08 Apr 2020 04:07:33 GMT

dist/ts-command-line.d.ts

@@ -32,23 +32,7 @@ /**
     constructor(options: ICommandLineActionOptions);
+    /* Excluded from this release type: _buildParser */
+    /* Excluded from this release type: _processParsedData */
+    /* Excluded from this release type: _execute */
+    /* Excluded from this release type: _getArgumentParser */
     /**
-     * This is called internally by CommandLineParser.addAction()
-     * @internal
-     */
-    _buildParser(actionsSubParser: argparse.SubParser): void;
-    /**
-     * This is called internally by CommandLineParser.execute()
-     * @internal
-     */
-    _processParsedData(data: _ICommandLineParserData): void;
-    /**
-     * Invoked by CommandLineParser.onExecute().
-     * @internal
-     */
-    _execute(): Promise<void>;
-    /**
-     * {@inheritDoc CommandLineParameterProvider._getArgumentParser}
-     * @internal
-     */
-    protected _getArgumentParser(): argparse.ArgumentParser;
-    /**
      * {@inheritDoc CommandLineParameterProvider.onDefineParameters}
@@ -73,17 +57,8 @@ */
     private _value;
-    /** @internal */
-    constructor(definition: ICommandLineChoiceDefinition);
+    /* Excluded from this release type: __constructor */
     /** {@inheritDoc CommandLineParameter.kind} */
     readonly kind: CommandLineParameterKind;
+    /* Excluded from this release type: _setValue */
+    /* Excluded from this release type: _getSupplementaryNotes */
     /**
-     * {@inheritDoc CommandLineParameter._setValue}
-     * @internal
-     */
-    _setValue(data: any): void;
-    /**
-     * {@inheritDoc CommandLineParameter._getSupplementaryNotes}
-     * @internal
-     */
-    _getSupplementaryNotes(supplementaryNotes: string[]): void;
-    /**
      * Returns the argument value for a choice parameter that was parsed from the command line.
@@ -106,12 +81,7 @@ *
     private _value;
-    /** @internal */
-    constructor(definition: ICommandLineFlagDefinition);
+    /* Excluded from this release type: __constructor */
     /** {@inheritDoc CommandLineParameter.kind} */
     readonly kind: CommandLineParameterKind;
+    /* Excluded from this release type: _setValue */
     /**
-     * {@inheritDoc CommandLineParameter._setValue}
-     * @internal
-     */
-    _setValue(data: any): void;
-    /**
      * Returns a boolean indicating whether the parameter was included in the command line.
@@ -136,17 +106,8 @@ *
     private _value;
-    /** @internal */
-    constructor(definition: ICommandLineIntegerDefinition);
+    /* Excluded from this release type: __constructor */
     /** {@inheritDoc CommandLineParameter.kind} */
     readonly kind: CommandLineParameterKind;
+    /* Excluded from this release type: _setValue */
+    /* Excluded from this release type: _getSupplementaryNotes */
     /**
-     * {@inheritDoc CommandLineParameter._setValue}
-     * @internal
-     */
-    _setValue(data: any): void;
-    /**
-     * {@inheritDoc CommandLineParameter._getSupplementaryNotes}
-     * @internal
-     */
-    _getSupplementaryNotes(supplementaryNotes: string[]): void;
-    /**
      * Returns the argument value for an integer parameter that was parsed from the command line.
@@ -171,7 +132,3 @@ *
     private static _environmentVariableRegExp;
-    /**
-     * A unique internal key used to retrieve the value from the parser's dictionary.
-     * @internal
-     */
-    _parserKey: string;
+    /* Excluded from this release type: _parserKey */
     /** {@inheritDoc IBaseCommandLineDefinition.parameterLongName} */
@@ -187,15 +144,6 @@ readonly longName: string;
     readonly environmentVariable: string | undefined;
-    /** @internal */
-    constructor(definition: IBaseCommandLineDefinition);
+    /* Excluded from this release type: __constructor */
+    /* Excluded from this release type: _setValue */
+    /* Excluded from this release type: _getSupplementaryNotes */
     /**
-     * Called internally by CommandLineParameterProvider._processParsedData()
-     * @internal
-     */
-    abstract _setValue(data: any): void;
-    /**
-     * Returns additional text used by the help formatter.
-     * @internal
-     */
-    _getSupplementaryNotes(supplementaryNotes: string[]): void;
-    /**
      * Indicates the type of parameter.
@@ -252,4 +200,4 @@ */
     private _parametersByLongName;
-    /** @internal */
-    constructor();
+    private _remainder;
+    /* Excluded from this release type: __constructor */
     /**
@@ -260,2 +208,7 @@ * Returns a collection of the parameters that were defined for this object.
     /**
+     * If {@link CommandLineParameterProvider.defineCommandLineRemainder} was called,
+     * this object captures any remaining command line arguments after the recognized portion.
+     */
+    readonly remainder: CommandLineRemainder | undefined;
+    /**
      * Defines a command-line parameter whose value must be a string from a fixed set of
@@ -265,3 +218,6 @@ * allowable choices (similar to an enum).
      * @remarks
-     * Example:  example-tool --log-level warn
+     * Example of a choice parameter:
+     * ```
+     * example-tool --log-level warn
+     * ```
      */
@@ -280,3 +236,6 @@ defineChoiceParameter(definition: ICommandLineChoiceDefinition): CommandLineChoiceParameter;
      * @remarks
-     * Example:  example-tool --debug
+     * Example usage of a flag parameter:
+     * ```
+     * example-tool --debug
+     * ```
      */
@@ -291,6 +250,9 @@ defineFlagParameter(definition: ICommandLineFlagDefinition): CommandLineFlagParameter;
     /**
-     * Defines a command-line parameter whose value is an integer.
+     * Defines a command-line parameter whose argument is an integer.
      *
      * @remarks
-     * Example:  example-tool --max-attempts 5
+     * Example usage of an integer parameter:
+     * ```
+     * example-tool --max-attempts 5
+     * ```
      */
@@ -305,6 +267,9 @@ defineIntegerParameter(definition: ICommandLineIntegerDefinition): CommandLineIntegerParameter;
     /**
-     * Defines a command-line parameter whose value is a single text string.
+     * Defines a command-line parameter whose argument is a single text string.
      *
      * @remarks
-     * Example:  example-tool --message "Hello, world!"
+     * Example usage of a string parameter:
+     * ```
+     * example-tool --message "Hello, world!"
+     * ```
      */
@@ -319,9 +284,29 @@ defineStringParameter(definition: ICommandLineStringDefinition): CommandLineStringParameter;
     /**
-     * Defines a command-line parameter whose value is one or more text strings.
+     * Defines a command-line parameter whose argument is a single text string.  The parameter can be
+     * specified multiple times to build a list.
      *
      * @remarks
-     * Example:  example-tool --add file1.txt --add file2.txt --add file3.txt
+     * Example usage of a string list parameter:
+     * ```
+     * example-tool --add file1.txt --add file2.txt --add file3.txt
+     * ```
      */
     defineStringListParameter(definition: ICommandLineStringListDefinition): CommandLineStringListParameter;
     /**
+     * Defines a rule that captures any remaining command line arguments after the recognized portion.
+     *
+     * @remarks
+     * This feature is useful for commands that pass their arguments along to an external tool, relying on
+     * that tool to perform validation.  (It could also be used to parse parameters without any validation
+     * or documentation, but that is not recommended.)
+     *
+     * Example of capturing the remainder after an optional flag parameter.
+     * ```
+     * example-tool --my-flag this is the remainder
+     * ```
+     *
+     * In the "--help" documentation, the remainder rule will be represented as "...".
+     */
+    defineCommandLineRemainder(definition: ICommandLineRemainderDefinition): CommandLineRemainder;
+    /**
      * Returns the CommandLineStringListParameter with the specified long name.
@@ -341,9 +326,4 @@ * @remarks
     protected abstract onDefineParameters(): void;
-    /**
-     * Retrieves the argparse object.
-     * @internal
-     */
-    protected abstract _getArgumentParser(): argparse.ArgumentParser;
-    /** @internal */
-    protected _processParsedData(data: _ICommandLineParserData): void;
+    /* Excluded from this release type: _getArgumentParser */
+    /* Excluded from this release type: _processParsedData */
     private _generateKey;
@@ -366,4 +346,3 @@ private _getParameter;
     readonly argumentName: string;
-    /** @internal */
-    constructor(definition: IBaseCommandLineDefinitionWithArgument);
+    /* Excluded from this release type: __constructor */
 }
@@ -440,8 +419,5 @@
     executeWithoutErrorHandling(args?: string[]): Promise<void>;
+    private _validateDefinitions;
+    /* Excluded from this release type: _getArgumentParser */
     /**
-     * {@inheritDoc CommandLineParameterProvider._getArgumentParser}
-     * @internal
-     */
-    protected _getArgumentParser(): argparse.ArgumentParser;
-    /**
      * This hook allows the subclass to perform additional operations before or after
@@ -454,2 +430,24 @@ * the chosen action is executed.
 /**
+ * The data type returned by {@link CommandLineParameterProvider.defineCommandLineRemainder}.
+ * @public
+ */
+export declare class CommandLineRemainder {
+    private _values;
+    /** {@inheritDoc IBaseCommandLineDefinition.description} */
+    readonly description: string;
+    /* Excluded from this release type: __constructor */
+    /**
+     * 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.
+     */
+    readonly values: ReadonlyArray<string>;
+    /* Excluded from this release type: _setValue */
+    /** {@inheritDoc CommandLineParameter.appendToArgList} @override */
+    appendToArgList(argList: string[]): void;
+}
+
+/**
  * The data type returned by {@link CommandLineParameterProvider.defineStringListParameter}.
@@ -460,12 +458,7 @@ * @public
     private _values;
-    /** @internal */
-    constructor(definition: ICommandLineStringListDefinition);
+    /* Excluded from this release type: __constructor */
     /** {@inheritDoc CommandLineParameter.kind} */
     readonly kind: CommandLineParameterKind;
+    /* Excluded from this release type: _setValue */
     /**
-     * {@inheritDoc CommandLineParameter._setValue}
-     * @internal
-     */
-    _setValue(data: any): void;
-    /**
      * Returns the string arguments for a string list parameter that was parsed from the command line.
@@ -490,17 +483,8 @@ *
     private _value;
-    /** @internal */
-    constructor(definition: ICommandLineStringDefinition);
+    /* Excluded from this release type: __constructor */
     /** {@inheritDoc CommandLineParameter.kind} */
     readonly kind: CommandLineParameterKind;
+    /* Excluded from this release type: _setValue */
+    /* Excluded from this release type: _getSupplementaryNotes */
     /**
-     * {@inheritDoc CommandLineParameter._setValue}
-     * @internal
-     */
-    _setValue(data: any): void;
-    /**
-     * {@inheritDoc CommandLineParameter._getSupplementaryNotes}
-     * @internal
-     */
-    _getSupplementaryNotes(supplementaryNotes: string[]): void;
-    /**
      * Returns the argument value for a string parameter that was parsed from the command line.
@@ -547,3 +531,3 @@ *
     /**
-     * Documentation for the flag, that will be shown when invoking the tool with "--help"
+     * Documentation for the parameter that will be shown when invoking the tool with "--help"
      */
@@ -559,2 +543,3 @@ description: string;
      * environment value cannot be parsed.
+     *
      * @remarks
@@ -566,2 +551,24 @@ * The environment variable name must consist only of upper-case letters, numbers,
      * because in that case the environmentVariable would never be used.
+     *
+     * Syntax notes for environment variable values:
+     *
+     * - Choice Parameter: The value must match one of the defined choices,
+     *   otherwise a validation error is reported.
+     *   An empty string causes the environment variable to be ignored.
+     *
+     * - Flag Parameter: The value must be `1` for true, or `0` for false,
+     *   otherwise a validation error is reported.
+     *   An empty string causes the environment variable to be ignored.
+     *
+     * - Integer Parameter: The value must be an integer number,
+     *   otherwise a validation error is reported.
+     *   An empty string causes the environment variable to be ignored.
+     *
+     * - String Parameter: Any value is accepted, including an empty string.
+     *
+     * - String List Parameter: If the string starts with `[` (ignoring whitespace)
+     *   then it will be parsed as a JSON array, whose elements must be strings,
+     *   numbers, or boolean values.
+     *   If the string does not start with `[`, then it behaves like an
+     *   ordinary String Parameter:  Any value is accepted, including an empty string.
      */
@@ -631,4 +638,4 @@ environmentVariable?: string;
 /**
- * For use with CommandLineParser, this interface represents a command line parameter
- * that is a boolean flag.
+ * For use with {@link CommandLineParameterProvider.defineFlagParameter},
+ * this interface defines a command line parameter that is a boolean flag.
  *
@@ -641,4 +648,4 @@ * @public
 /**
- * For use with CommandLineParser, this interface represents a command line parameter
- * whose argument is an integer value.
+ * For use with {@link CommandLineParameterProvider.defineIntegerParameter},
+ * this interface defines a command line parameter whose argument is an integer value.
  *
@@ -654,10 +661,3 @@ * @public
 
-/**
- * This is the argparse result data object
- * @internal
- */
-export declare interface _ICommandLineParserData {
-    action: string;
-    [key: string]: any;
-}
+/* Excluded from this release type: _ICommandLineParserData */
 
@@ -680,7 +680,21 @@ /**
 /**
- * For use with CommandLineParser, this interface represents a command line parameter
- * whose argument is a string value.
+ * For use with {@link CommandLineParameterProvider.defineCommandLineRemainder},
+ * this interface defines a rule that captures any remaining command line arguments after the recognized portion.
  *
  * @public
  */
+export declare interface ICommandLineRemainderDefinition {
+    /**
+     * Documentation for how the remaining arguments will be used.  This will be shown when invoking
+     * the tool with "--help".
+     */
+    description: string;
+}
+
+/**
+ * For use with {@link CommandLineParameterProvider.defineStringParameter},
+ * this interface defines a command line parameter whose argument is a string value.
+ *
+ * @public
+ */
 export declare interface ICommandLineStringDefinition extends IBaseCommandLineDefinitionWithArgument {
@@ -699,4 +713,5 @@ /**
 /**
- * For use with CommandLineParser, this interface represents a command line parameter
- * whose argument is a list of strings.
+ * For use with {@link CommandLineParameterProvider.defineStringListParameter},
+ * this interface defines a command line parameter whose argument is a single text string.
+ * The parameter can be specified multiple times to build a list.
  *
@@ -703,0 +718,0 @@ * @public

lib/index.d.ts

@@ -6,9 +6,15 @@ /**
  */
-export { CommandLineAction, ICommandLineActionOptions } from './CommandLineAction';
-export { IBaseCommandLineDefinition, IBaseCommandLineDefinitionWithArgument, ICommandLineFlagDefinition, ICommandLineStringDefinition, ICommandLineStringListDefinition, ICommandLineIntegerDefinition, ICommandLineChoiceDefinition } from './CommandLineDefinition';
-export { CommandLineParameterKind, CommandLineParameter, CommandLineParameterWithArgument, CommandLineStringParameter, CommandLineStringListParameter, CommandLineFlagParameter, CommandLineIntegerParameter, CommandLineChoiceParameter } from './CommandLineParameter';
-export { CommandLineParameterProvider, ICommandLineParserData as _ICommandLineParserData } from './CommandLineParameterProvider';
-export { ICommandLineParserOptions, CommandLineParser } from './CommandLineParser';
-export { DynamicCommandLineAction } from './DynamicCommandLineAction';
-export { DynamicCommandLineParser } from './DynamicCommandLineParser';
+export { CommandLineAction, ICommandLineActionOptions } from './providers/CommandLineAction';
+export { IBaseCommandLineDefinition, IBaseCommandLineDefinitionWithArgument, ICommandLineFlagDefinition, ICommandLineStringDefinition, ICommandLineStringListDefinition, ICommandLineIntegerDefinition, ICommandLineChoiceDefinition, ICommandLineRemainderDefinition } from './parameters/CommandLineDefinition';
+export { CommandLineParameterKind, CommandLineParameter, CommandLineParameterWithArgument } from './parameters/BaseClasses';
+export { CommandLineFlagParameter } from './parameters/CommandLineFlagParameter';
+export { CommandLineStringParameter } from './parameters/CommandLineStringParameter';
+export { CommandLineStringListParameter } from './parameters/CommandLineStringListParameter';
+export { CommandLineIntegerParameter } from './parameters/CommandLineIntegerParameter';
+export { CommandLineChoiceParameter } from './parameters/CommandLineChoiceParameter';
+export { CommandLineRemainder } from './parameters/CommandLineRemainder';
+export { CommandLineParameterProvider, ICommandLineParserData as _ICommandLineParserData } from './providers/CommandLineParameterProvider';
+export { ICommandLineParserOptions, CommandLineParser } from './providers/CommandLineParser';
+export { DynamicCommandLineAction } from './providers/DynamicCommandLineAction';
+export { DynamicCommandLineParser } from './providers/DynamicCommandLineParser';
 //# sourceMappingURL=index.d.ts.map

lib/index.js

@@ -10,21 +10,28 @@ "use strict";
  */
-var CommandLineAction_1 = require("./CommandLineAction");
+var CommandLineAction_1 = require("./providers/CommandLineAction");
 exports.CommandLineAction = CommandLineAction_1.CommandLineAction;
-var CommandLineParameter_1 = require("./CommandLineParameter");
-exports.CommandLineParameterKind = CommandLineParameter_1.CommandLineParameterKind;
-exports.CommandLineParameter = CommandLineParameter_1.CommandLineParameter;
-exports.CommandLineParameterWithArgument = CommandLineParameter_1.CommandLineParameterWithArgument;
-exports.CommandLineStringParameter = CommandLineParameter_1.CommandLineStringParameter;
-exports.CommandLineStringListParameter = CommandLineParameter_1.CommandLineStringListParameter;
-exports.CommandLineFlagParameter = CommandLineParameter_1.CommandLineFlagParameter;
-exports.CommandLineIntegerParameter = CommandLineParameter_1.CommandLineIntegerParameter;
-exports.CommandLineChoiceParameter = CommandLineParameter_1.CommandLineChoiceParameter;
-var CommandLineParameterProvider_1 = require("./CommandLineParameterProvider");
+var BaseClasses_1 = require("./parameters/BaseClasses");
+exports.CommandLineParameterKind = BaseClasses_1.CommandLineParameterKind;
+exports.CommandLineParameter = BaseClasses_1.CommandLineParameter;
+exports.CommandLineParameterWithArgument = BaseClasses_1.CommandLineParameterWithArgument;
+var CommandLineFlagParameter_1 = require("./parameters/CommandLineFlagParameter");
+exports.CommandLineFlagParameter = CommandLineFlagParameter_1.CommandLineFlagParameter;
+var CommandLineStringParameter_1 = require("./parameters/CommandLineStringParameter");
+exports.CommandLineStringParameter = CommandLineStringParameter_1.CommandLineStringParameter;
+var CommandLineStringListParameter_1 = require("./parameters/CommandLineStringListParameter");
+exports.CommandLineStringListParameter = CommandLineStringListParameter_1.CommandLineStringListParameter;
+var CommandLineIntegerParameter_1 = require("./parameters/CommandLineIntegerParameter");
+exports.CommandLineIntegerParameter = CommandLineIntegerParameter_1.CommandLineIntegerParameter;
+var CommandLineChoiceParameter_1 = require("./parameters/CommandLineChoiceParameter");
+exports.CommandLineChoiceParameter = CommandLineChoiceParameter_1.CommandLineChoiceParameter;
+var CommandLineRemainder_1 = require("./parameters/CommandLineRemainder");
+exports.CommandLineRemainder = CommandLineRemainder_1.CommandLineRemainder;
+var CommandLineParameterProvider_1 = require("./providers/CommandLineParameterProvider");
 exports.CommandLineParameterProvider = CommandLineParameterProvider_1.CommandLineParameterProvider;
-var CommandLineParser_1 = require("./CommandLineParser");
+var CommandLineParser_1 = require("./providers/CommandLineParser");
 exports.CommandLineParser = CommandLineParser_1.CommandLineParser;
-var DynamicCommandLineAction_1 = require("./DynamicCommandLineAction");
+var DynamicCommandLineAction_1 = require("./providers/DynamicCommandLineAction");
 exports.DynamicCommandLineAction = DynamicCommandLineAction_1.DynamicCommandLineAction;
-var DynamicCommandLineParser_1 = require("./DynamicCommandLineParser");
+var DynamicCommandLineParser_1 = require("./providers/DynamicCommandLineParser");
 exports.DynamicCommandLineParser = DynamicCommandLineParser_1.DynamicCommandLineParser;
 //# sourceMappingURL=index.js.map

package.json

 {
 	"name": "@rushstack/ts-command-line",
-	"version": "4.3.14",
+	"version": "4.4.0",
 	"description": "An object-oriented command-line parser for TypeScript",
@@ -16,3 +16,3 @@ "repository": {
 	"dependencies": {
-		"@types/argparse": "1.0.33",
+		"@types/argparse": "1.0.38",
 		"argparse": "~1.0.9",
@@ -22,6 +22,6 @@ "colors": "~1.2.1"
 	"devDependencies": {
-		"@types/jest": "23.3.11",
+		"@types/jest": "25.2.1",
 		"@types/node": "10.17.13",
 		"gulp": "~4.0.2",
-		"@microsoft/node-library-build": "6.4.5",
+		"@microsoft/node-library-build": "6.4.10",
 		"@microsoft/rush-stack-compiler-3.5": "0.4.4",
@@ -28,0 +28,0 @@ "@rushstack/eslint-config": "0.5.7"

README.md

 # ts-command-line
 
-This library helps you create professional command-line tools for Node.js. By "professional", we mean:
+This library helps you create professional command-line tools using TypeScript.  By "professional", we mean:
 
-- **no gotchas for users**:  Seems obvious, but try typing "`npm install --save-dex`" instead of "`npm install --save-dev`" sometime.  The command seems to execute successfully, but it doesn't save anything! The misspelled flag was silently ignored.  This lack of rigor plagues many familiar NodeJS tools and can be confusing and frustrating.  For a great user experience, a command line tool should always be strict about its syntax.
+- **no gotchas for users**:  Seems obvious, but try typing "`npm install --save-dex`" instead of "`npm install --save-dev`" sometime.  The command seems to execute successfully, but it doesn't save anything! The misspelled flag was silently ignored. This lack of rigor plagues many familiar Node.js tools and can be confusing and frustrating. For a great user experience, a command line tool should always be strict about its syntax.
 
-- **no gotchas for developers**:  Many command-line libraries store their parsed data in a simple JavaScript hash object.  This is convenient for small projects. But suppose a large project has many different source files that define and read parameters. If you try to read `data['output-dir']` when it wasn't defined, or if you misspell the key name, your tool will silently behave as if the parameter was omitted.  And is `data['max-count']` a string or a number? Hard to tell! We solve this by modeling each parameter kind as a real TypeScript class.
+- **no gotchas for developers**:  Many command-line libraries store their parsed data in a simple JavaScript object. This is convenient for small projects. But suppose a large project has many different source files that define and read parameters. If you try to read `data['output-dir']` when it wasn't defined, or if you misspell the key name, your tool will silently behave as if the parameter was omitted. And is `data['max-count']` a string or a number? Hard to tell! We solve this by modeling each parameter kind as a real TypeScript class.
 
-- **automatic documentation**: Some command-line libraries treat the `--help` docs as someone else's job.  **ts-command-line** requires each every parameter to have a documentation string, and will automatically generate the `--help` docs for you.  If you like to write long paragraphs, no problem -- they will be word-wrapped correctly.   *[golf clap]*
+- **simple by design**:  Making a CLI is similar to making a graphical UI -- some people have a knack for clean and intuitive designs, but your average developer... needs some help.  :-)  Keeping things simple is the best help.  **ts-command-line** intentionally provides a minimalist set of CLI building blocks that encourage simple designs.  If your app has lots of knobs and switches, we recommend NOT to design a complex CLI with hundreds of parameters.  Move those options into a commented config file with a published JSON schema.
 
-- **structure and extensibility**: Instead of a simple function chain, **ts-command-line** provides a  "scaffold" pattern that makes it easy to find and understand the command-line implementation for any tool project.  The scaffold model is generally recommended, but there's also a "dynamic" model if you need it.  See below for examples.
+- **automatic documentation**: Some command-line libraries treat the `--help` docs as someone else's job.  **ts-command-line** requires each every parameter to follow a standardized naming pattern and have a documentation string.  It will automatically generate the `--help` docs for you.  If you like to write long paragraphs, no problem -- they will be word-wrapped correctly. *[golf clap]*
 
-Internally, the implementation is based on [argparse](https://www.npmjs.com/package/argparse) and the Python approach to command-lines.  Compared to other libraries, **ts-command-line** doesn't provide zillions of custom syntaxes and bells and whistles.  Instead it aims to be a simple, consistent, and professional solution for your command-line tool.  Give it a try!
+- **structure and extensibility**: Instead of a simple function chain, **ts-command-line** provides a "scaffold" pattern that makes it easy to find and understand the command-line implementation for any tool project.  The scaffold model is generally recommended, but there's also a "dynamic" model if you need it.  See below for examples.
 
+- **environment variable mappings**: Any CLI parameter can be associated with an environment variable.  If the parameter is not explicitly provided, the value from the environment will be used.  The associated environment variables are automatically documented in the `--help`.
 
+Internally, the implementation is based on [argparse](https://www.npmjs.com/package/argparse) and the Python approach to command-lines.
+
+Compared to other libraries, **ts-command-line** doesn't provide zillions of custom syntaxes and bells and whistles.  Instead it aims to be a simple, consistent, and professional solution for your command-line tool.  Give it a try!
+
 ### Some Terminology
@@ -28,3 +33,2 @@
 - The **parameters** are  `--verbose`, `--force`, and `--max-count`.
-- The currently supported **parameter kinds** include: **flag** (i.e. boolean), **integer**, **string**, **choice** (i.e. enums), and **string list**.
 - The value "123" is the **argument** for the `--max-count` integer parameter.  (Flags don't have arguments, because their value is determined by whether the flag was provided or not.)
@@ -36,2 +40,17 @@ - Similar to Git's command-line, the `push` token is called an **action**.  It acts as sub-command with its own unique set of parameters.
 
+### Parameter Kinds
+
+Several different kinds of parameters are supported:
+
+| Parameter Kind | Example | Data Type | Description |
+| --- | --- | --- | --- |
+| flag | `--verbose` | `boolean` | Value is `true` if the flag was specified on the command line, `false` otherwise. |
+| integer | `--max-retry 3` | `int` | The argument is an integer number |
+| string | `--title "Hello, world"` | `string` | The argument is a text string. |
+| choice | `--color red` | `string` | The argument is must be a string from a list of allowed choices (similar to an enum). |
+| string list | `-o file1.txt -o file2.txt` | `string[]` | The argument is a text string. The parameter can be specified multiple times to build a list. |
+
+Other parameter kinds could be implemented if requested.  That said, keeping your CLI grammar simple and systematic makes it easier for users to learn.
+
+
 ## Scaffold Model
@@ -50,4 +69,5 @@
 ```typescript
-class PushAction extends CommandLineAction {
+export class PushAction extends CommandLineAction {
   private _force: CommandLineFlagParameter;
+  private _protocol: CommandLineChoiceParameter;
 
@@ -58,3 +78,3 @@ public constructor() {
       summary: 'Pushes a widget to the service',
-      documentation: 'Your long description goes here.'
+      documentation: 'Here we provide a longer description of how our action works.'
     });
@@ -64,3 +84,3 @@ }
   protected onExecute(): Promise<void> { // abstract
-    return BusinessLogic.doTheWork(this._force.value);
+    return BusinessLogic.doTheWork(this._force.value, this._protocol.value || "(none)");
   }
@@ -74,2 +94,10 @@
     });
+
+    this._protocol = this.defineChoiceParameter({
+      parameterLongName: '--protocol',
+      description: 'Specify the protocol to use',
+      alternatives: ['ftp', 'webdav', 'scp'],
+      environmentVariable: 'WIDGET_PROTOCOL',
+      defaultValue: 'scp'
+    });
   }
@@ -82,3 +110,3 @@ }
 ```typescript
-class WidgetCommandLine extends CommandLineParser {
+export class WidgetCommandLine extends CommandLineParser {
   private _verbose: CommandLineFlagParameter;
@@ -89,3 +117,3 @@
       toolFilename: 'widget',
-      toolDescription: 'The widget tool is really great.'
+      toolDescription: 'The "widget" tool is a code sample for using the @rushstack/ts-command-line library.'
     });
@@ -120,3 +148,8 @@
 
+---
 
+**For a more complete example, take a look at the [ts-command-line-test](https://github.com/microsoft/rushstack/tree/master/build-tests/ts-command-line-test) sample project.**
+
+---
+
 #### Testing out the docs
@@ -129,3 +162,4 @@
 
-The widget tool is really great.
+The "widget" tool is a code sample for using the @rushstack/ts-command-line
+library.
 
@@ -146,9 +180,13 @@ Positional arguments:
 ```
-usage: widget push [-h] [-f]
+usage: widget push [-h] [-f] [--protocol {ftp,webdav,scp}]
 
-Your long description goes here.
+Here we provide a longer description of how our action works.
 
 Optional arguments:
-  -h, --help   Show this help message and exit.
-  -f, --force  Push and overwrite any existing state
+  -h, --help            Show this help message and exit.
+  -f, --force           Push and overwrite any existing state
+  --protocol {ftp,webdav,scp}
+                        Specify the protocol to use. This parameter may
+                        alternatively specified via the WIDGET_PROTOCOL
+                        environment variable. The default value is "scp".
 ```
@@ -169,4 +207,5 @@
   toolFilename: 'widget',
-  toolDescription: 'The widget tool is really great.'
+  toolDescription: 'The "widget" tool is a code sample for using the @rushstack/ts-command-line library.'
 });
+
 commandLineParser.defineFlagParameter({
@@ -182,4 +221,5 @@ parameterLongName: '--verbose',
   summary: 'Pushes a widget to the service',
-  documentation: 'More detail about the "push" action'
+  documentation: 'Here we provide a longer description of how our action works.'
 });
+
 commandLineParser.addAction(action);
@@ -193,2 +233,10 @@
 
+action.defineChoiceParameter({
+  parameterLongName: '--protocol',
+  description: 'Specify the protocol to use',
+  alternatives: ['ftp', 'webdav', 'scp'],
+  environmentVariable: 'WIDGET_PROTOCOL',
+  defaultValue: 'scp'
+});
+
 // Parse the command line
@@ -195,0 +243,0 @@ commandLineParser.execute(process.argv).then(() => {

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

261713

increased by18.82%

Number of package files

67

increased by71.79%

Lines of code

3575

increased by11.27%

Number of lines in readme file

248

increased by24%

Worsened metrics

Number of low supply chain risk alerts

5

increased byInfinity%

Number of medium supply chain risk alerts

1

increased byInfinity%

Dependency changes

• + Added@types/argparse@1.0.38(transitive)

• - Removed@types/argparse@1.0.33(transitive)

• Updated@types/argparse@1.0.38