1 line
8.7 KiB
Plaintext
1 line
8.7 KiB
Plaintext
{"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"]} |