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