Add "defaultValue" and "required" options for command-line parameters

pgonzal · pgonzal · commit a435d576384d · 2018-04-25T22:02:27.000-07:00
diff --git a/common/reviews/api/ts-command-line.api.ts b/common/reviews/api/ts-command-line.api.ts
@@ -52,6 +52,7 @@ class CommandLineIntegerParameter extends CommandLineParameterWithArgument {
   constructor(definition: ICommandLineIntegerDefinition);
   // @internal
   _setValue(data: any): void;
+  readonly defaultValue: number | undefined;
   readonly kind: CommandLineParameterKind;
   readonly value: number | undefined;
 }
@@ -68,7 +69,10 @@ class CommandLineParameter {
   readonly kind: CommandLineParameterKind;
   readonly longName: string;
   protected reportInvalidData(data: any): never;
+  readonly required: boolean;
   readonly shortName: string | undefined;
+  // (undocumented)
+  protected validateDefaultValue(hasDefaultValue: boolean): void;
 }
 
 // @public
@@ -142,6 +146,7 @@ class CommandLineStringParameter extends CommandLineParameterWithArgument {
   constructor(definition: ICommandLineStringDefinition);
   // @internal
   _setValue(data: any): void;
+  readonly defaultValue: string | undefined;
   readonly kind: CommandLineParameterKind;
   readonly value: string | undefined;
 }
@@ -165,6 +170,7 @@ interface IBaseCommandLineDefinition {
   description: string;
   parameterLongName: string;
   parameterShortName?: string;
+  required?: boolean;
 }
 
 // @public
@@ -191,6 +197,7 @@ interface ICommandLineFlagDefinition extends IBaseCommandLineDefinition {
 
 // @public
 interface ICommandLineIntegerDefinition extends IBaseCommandLineDefinitionWithArgument {
+  defaultValue?: number;
 }
 
 // @public
@@ -201,6 +208,7 @@ interface ICommandLineParserOptions {
 
 // @public
 interface ICommandLineStringDefinition extends IBaseCommandLineDefinitionWithArgument {
+  defaultValue?: string;
 }
 
 // @public
diff --git a/libraries/ts-command-line/src/CommandLineDefinition.ts b/libraries/ts-command-line/src/CommandLineDefinition.ts
@@ -21,6 +21,12 @@ export interface IBaseCommandLineDefinition {
    * Documentation for the flag, that will be shown when invoking the tool with "--help"
    */
   description: string;
+
+  /**
+   * If true, then an error occurs if the parameter was not included on the command-line
+   * or provided via an environment variable.
+   */
+  required?: boolean;
 }
 
 /**
@@ -56,7 +62,7 @@ export interface ICommandLineChoiceDefinition extends IBaseCommandLineDefinition
   alternatives: string[];
 
   /**
-   * The default value which will be used if the parameter is omitted from the command line
+   * {@inheritdoc ICommandLineStringDefinition.defaultValue}
    */
   defaultValue?: string;
 }
@@ -75,15 +81,30 @@ export interface ICommandLineFlagDefinition extends IBaseCommandLineDefinition {
  *
  * @public
  */
-export interface ICommandLineIntegerDefinition extends IBaseCommandLineDefinitionWithArgument { }
+export interface ICommandLineIntegerDefinition extends IBaseCommandLineDefinitionWithArgument {
+  /**
+   * {@inheritdoc ICommandLineStringDefinition.defaultValue}
+   */
+  defaultValue?: number;
+}
 
 /**
  * For use with CommandLineParser, this interface represents a command line parameter
  * whose argument is a string value.
  *
  * @public
  */
-export interface ICommandLineStringDefinition extends IBaseCommandLineDefinitionWithArgument { }
+export interface ICommandLineStringDefinition extends IBaseCommandLineDefinitionWithArgument {
+  /**
+   * The default value which will be used if the parameter is omitted from the command line.
+   *
+   * @remarks
+   * If a default value is specified, then {@link IBaseCommandLineDefinition.required}
+   * must not be true.  Instead, a custom error message should be used to report cases
+   * where the value could not be determined.
+   */
+  defaultValue?: string;
+}
 
 /**
  * For use with CommandLineParser, this interface represents a command line parameter
diff --git a/libraries/ts-command-line/src/CommandLineParameter.ts b/libraries/ts-command-line/src/CommandLineParameter.ts
@@ -53,22 +53,27 @@ export abstract class CommandLineParameter {
   /** {@inheritdoc IBaseCommandLineDefinition.description} */
   public readonly description: string;
 
+  /** {@inheritdoc IBaseCommandLineDefinition.required} */
+  public readonly required: boolean;
+
   /** @internal */
   constructor(definition: IBaseCommandLineDefinition) {
-    if (!CommandLineParameter._longNameRegExp.test(definition.parameterLongName)) {
-      throw new Error(`Invalid name: "${definition.parameterLongName}". The parameter long name must be`
+    this.longName = definition.parameterLongName;
+    this.shortName = definition.parameterShortName;
+    this.description = definition.description;
+    this.required = !!definition.required;
+
+    if (!CommandLineParameter._longNameRegExp.test(this.longName)) {
+      throw new Error(`Invalid name: "${this.longName}". The parameter long name must be`
         + ` lower-case and use dash delimiters (e.g. "--do-a-thing")`);
     }
-    this.longName = definition.parameterLongName;
 
-    if (definition.parameterShortName) {
-      if (!CommandLineParameter._shortNameRegExp.test(definition.parameterShortName)) {
-        throw new Error(`Invalid name: "${definition.parameterShortName}". The parameter short name must be`
+    if (this.shortName) {
+      if (!CommandLineParameter._shortNameRegExp.test(this.shortName)) {
+        throw new Error(`Invalid name: "${this.shortName}". The parameter short name must be`
           + ` a dash followed by a single upper-case or lower-case letter (e.g. "-a")`);
       }
     }
-    this.shortName = definition.parameterShortName;
-    this.description = definition.description;
   }
 
   /**
@@ -89,6 +94,18 @@ export abstract class CommandLineParameter {
     throw new Error(`Unexpected data object for parameter "${this.longName}": `
       + JSON.stringify(data));
   }
+
+  protected validateDefaultValue(hasDefaultValue: boolean): void {
+    if (this.required && hasDefaultValue) {
+      // If a parameter is "required", then the user understands that they always need to
+      // specify a value for this parameter (either via the command line or via an environment variable).
+      // It would be confusing to allow a default value that sometimes allows the "required" parameter
+      // to be omitted.  If you sometimes don't have a suitable default value, then the better approach
+      // is to throw a custom error explaining why the parameter is required in that case.
+      throw new Error(`A default value cannot be specified for "${this.longName}"`
+        + ` because it is a "required" parameter`);
+    }
+  }
 }
 
 /**
@@ -134,7 +151,7 @@ export class CommandLineChoiceParameter extends CommandLineParameter {
   /** {@inheritdoc ICommandLineChoiceDefinition.alternatives} */
   public readonly alternatives: ReadonlyArray<string>;
 
-  /** {@inheritdoc ICommandLineChoiceDefinition.defaultValue} */
+  /** {@inheritdoc ICommandLineStringDefinition.defaultValue} */
   public readonly defaultValue: string | undefined;
 
   private _value: string | undefined = undefined;
@@ -153,6 +170,7 @@ export class CommandLineChoiceParameter extends CommandLineParameter {
 
     this.alternatives = definition.alternatives;
     this.defaultValue = definition.defaultValue;
+    this.validateDefaultValue(!!this.defaultValue);
   }
 
   /** {@inheritdoc CommandLineParameter.kind} */
@@ -236,11 +254,16 @@ export class CommandLineFlagParameter extends CommandLineParameter {
  * @public
  */
 export class CommandLineIntegerParameter extends CommandLineParameterWithArgument {
+  /** {@inheritdoc ICommandLineStringDefinition.defaultValue} */
+  public readonly defaultValue: number | undefined;
+
   private _value: number | undefined = undefined;
 
   /** @internal */
   constructor(definition: ICommandLineIntegerDefinition) {
     super(definition);
+    this.defaultValue = definition.defaultValue;
+    this.validateDefaultValue(!!this.defaultValue);
   }
 
   /** {@inheritdoc CommandLineParameter.kind} */
@@ -280,11 +303,17 @@ export class CommandLineIntegerParameter extends CommandLineParameterWithArgumen
  * @public
  */
 export class CommandLineStringParameter extends CommandLineParameterWithArgument {
+  /** {@inheritdoc ICommandLineStringDefinition.defaultValue} */
+  public readonly defaultValue: string | undefined;
+
   private _value: string | undefined = undefined;
 
   /** @internal */
   constructor(definition: ICommandLineStringDefinition) {
     super(definition);
+
+    this.defaultValue = definition.defaultValue;
+    this.validateDefaultValue(!!this.defaultValue);
   }
 
   /** {@inheritdoc CommandLineParameter.kind} */
diff --git a/libraries/ts-command-line/src/CommandLineParameterProvider.ts b/libraries/ts-command-line/src/CommandLineParameterProvider.ts
@@ -221,6 +221,7 @@ export abstract class CommandLineParameterProvider {
     const argparseOptions: argparse.ArgumentOptions = {
       help: parameter.description,
       dest: parameter._parserKey,
+      required: parameter.required,
       metavar: (parameter as CommandLineParameterWithArgument).argumentName || undefined
     };
 
@@ -234,7 +235,13 @@ export abstract class CommandLineParameterProvider {
         argparseOptions.action = 'storeTrue';
         break;
       case CommandLineParameterKind.Integer:
+        const integerParameter: CommandLineIntegerParameter = parameter as CommandLineIntegerParameter;
         argparseOptions.type = 'int';
+        argparseOptions.defaultValue = integerParameter.defaultValue;
+        break;
+      case CommandLineParameterKind.String:
+        const stringDefaultValue: CommandLineStringParameter = parameter as CommandLineStringParameter;
+        argparseOptions.defaultValue = stringDefaultValue.defaultValue;
         break;
       case CommandLineParameterKind.StringList:
         argparseOptions.action = 'append';
