1 line
16 KiB
Plaintext
1 line
16 KiB
Plaintext
{"version":3,"file":"ScopedCommandLineAction.js","sourceRoot":"","sources":["../../src/providers/ScopedCommandLineAction.ts"],"names":[],"mappings":"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","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 { SCOPING_PARAMETER_GROUP } from '../Constants';\nimport { CommandLineAction, type ICommandLineActionOptions } from './CommandLineAction';\nimport { CommandLineParser, type ICommandLineParserOptions } from './CommandLineParser';\nimport { CommandLineParserExitError } from './CommandLineParserExitError';\nimport type { CommandLineParameter } from '../parameters/BaseClasses';\nimport type {\n CommandLineParameterProvider,\n ICommandLineParserData,\n IRegisterDefinedParametersState\n} from './CommandLineParameterProvider';\n\ninterface IInternalScopedCommandLineParserOptions extends ICommandLineParserOptions {\n readonly actionOptions: ICommandLineActionOptions;\n readonly unscopedActionParameters: ReadonlyArray<CommandLineParameter>;\n readonly onDefineScopedParameters: (commandLineParameterProvider: CommandLineParameterProvider) => void;\n readonly aliasAction?: string;\n readonly aliasDocumentation?: string;\n readonly registerDefinedParametersState: IRegisterDefinedParametersState;\n}\n\n/**\n * A CommandLineParser used exclusively to parse the scoped command-line parameters\n * for a ScopedCommandLineAction.\n */\nclass InternalScopedCommandLineParser extends CommandLineParser {\n private _canExecute: boolean;\n private readonly _internalOptions: IInternalScopedCommandLineParserOptions;\n\n public get canExecute(): boolean {\n return this._canExecute;\n }\n\n public constructor(options: IInternalScopedCommandLineParserOptions) {\n const { actionOptions, unscopedActionParameters, toolFilename, aliasAction, aliasDocumentation } =\n options;\n\n const toolCommand: string = `${toolFilename} ${actionOptions.actionName}`;\n // When coming from an alias command, we want to show the alias command name in the help text\n const toolCommandForLogging: string = `${toolFilename} ${aliasAction ?? actionOptions.actionName}`;\n const scopingArgs: string[] = [];\n for (const parameter of unscopedActionParameters) {\n parameter.appendToArgList(scopingArgs);\n }\n const scope: string = scopingArgs.join(' ');\n\n // We can run the parser directly because we are not going to use it for any other actions,\n // so construct a special options object to make the \"--help\" text more useful.\n const scopedCommandLineParserOptions: ICommandLineParserOptions = {\n // Strip the scoping args if coming from an alias command, since they are not applicable\n // to the alias command itself\n toolFilename: `${toolCommandForLogging}${scope && !aliasAction ? ` ${scope} --` : ''}`,\n toolDescription: aliasDocumentation ?? actionOptions.documentation,\n toolEpilog: `For more information on available unscoped parameters, use \"${toolCommand} --help\"`,\n enableTabCompletionAction: false\n };\n\n super(scopedCommandLineParserOptions);\n this._canExecute = false;\n this._internalOptions = options;\n this._internalOptions.onDefineScopedParameters(this);\n }\n\n public _registerDefinedParameters(state: IRegisterDefinedParametersState): void {\n // Since we are in a separate parser, we need to register the parameters using the state\n // from the parent parser.\n super._registerDefinedParameters(this._internalOptions.registerDefinedParametersState);\n }\n\n protected async onExecute(): Promise<void> {\n // override\n // Only set if we made it this far, which may not be the case if an error occurred or\n // if '--help' was specified.\n this._canExecute = true;\n }\n}\n\n/**\n * Represents a sub-command that is part of the CommandLineParser command-line.\n * Applications should create subclasses of ScopedCommandLineAction corresponding to\n * each action that they want to expose.\n *\n * The action name should be comprised of lower case words separated by hyphens\n * or colons. The name should include an English verb (e.g. \"deploy\"). Use a\n * hyphen to separate words (e.g. \"upload-docs\"). A group of related commands\n * can be prefixed with a colon (e.g. \"docs:generate\", \"docs:deploy\",\n * \"docs:serve\", etc).\n *\n * Scoped commands allow for different parameters to be specified for different\n * provided scoping values. For example, the \"scoped-action --scope A\" command\n * may allow for different scoped arguments to be specified than the \"scoped-action\n * --scope B\" command.\n *\n * Scoped arguments are specified after the \"--\" pseudo-argument. For example,\n * \"scoped-action --scope A -- --scopedFoo --scopedBar\".\n *\n * @public\n */\nexport abstract class ScopedCommandLineAction extends CommandLineAction {\n private _options: ICommandLineActionOptions;\n private _scopingParameters: CommandLineParameter[];\n private _unscopedParserOptions: ICommandLineParserOptions | undefined;\n private _scopedCommandLineParser: InternalScopedCommandLineParser | undefined;\n private _subparserState: IRegisterDefinedParametersState | undefined;\n\n /**\n * The required group name to apply to all scoping parameters. At least one parameter\n * must be defined with this group name.\n */\n public static readonly ScopingParameterGroup: typeof SCOPING_PARAMETER_GROUP = SCOPING_PARAMETER_GROUP;\n\n public constructor(options: ICommandLineActionOptions) {\n super(options);\n\n this._options = options;\n this._scopingParameters = [];\n }\n\n /**\n * {@inheritDoc CommandLineParameterProvider.parameters}\n */\n public get parameters(): ReadonlyArray<CommandLineParameter> {\n if (this._scopedCommandLineParser) {\n return [...super.parameters, ...this._scopedCommandLineParser.parameters];\n } else {\n return super.parameters;\n }\n }\n\n /**\n * {@inheritdoc CommandLineAction._processParsedData}\n * @internal\n */\n public _processParsedData(parserOptions: ICommandLineParserOptions, data: ICommandLineParserData): void {\n // override\n super._processParsedData(parserOptions, data);\n\n // This should never happen because the super method should throw if parameters haven't been registered,\n // but guard against this just in-case.\n if (this._subparserState === undefined) {\n throw new Error('Parameters have not been registered');\n }\n\n this._unscopedParserOptions = parserOptions;\n\n // Generate the scoped parser using the parent parser information. We can only create this after we\n // have parsed the data, since the parameter values are used during construction.\n this._scopedCommandLineParser = new InternalScopedCommandLineParser({\n ...parserOptions,\n actionOptions: this._options,\n aliasAction: data.aliasAction,\n aliasDocumentation: data.aliasDocumentation,\n unscopedActionParameters: this.parameters,\n registerDefinedParametersState: this._subparserState,\n onDefineScopedParameters: this.onDefineScopedParameters.bind(this)\n });\n }\n\n /**\n * {@inheritdoc CommandLineAction._execute}\n * @internal\n */\n public async _execute(): Promise<void> {\n // override\n if (!this._unscopedParserOptions || !this._scopedCommandLineParser) {\n throw new Error('The CommandLineAction parameters must be processed before execution.');\n }\n if (!this.remainder) {\n throw new Error('CommandLineAction.onDefineParameters must be called before execution.');\n }\n\n // The '--' argument is required to separate the action parameters from the scoped parameters,\n // so it needs to be trimmed. If remainder values are provided but no '--' is found, then throw.\n const scopedArgs: string[] = [];\n if (this.remainder.values.length) {\n if (this.remainder.values[0] !== '--') {\n throw new CommandLineParserExitError(\n // argparse sets exit code 2 for invalid arguments\n 2,\n // model the message off of the built-in \"unrecognized arguments\" message\n `${this.renderUsageText()}\\n${this._unscopedParserOptions.toolFilename} ${this.actionName}: ` +\n `error: Unrecognized arguments: ${this.remainder.values[0]}.\\n`\n );\n }\n for (const scopedArg of this.remainder.values.slice(1)) {\n scopedArgs.push(scopedArg);\n }\n }\n\n // Call the scoped parser using only the scoped args to handle parsing\n await this._scopedCommandLineParser.executeWithoutErrorHandling(scopedArgs);\n\n // Only call execute if the parser reached the execute stage. This may not be true if\n // the parser exited early due to a specified '--help' parameter.\n if (this._scopedCommandLineParser.canExecute) {\n await super._execute();\n }\n\n return;\n }\n\n /** @internal */\n public _registerDefinedParameters(state: IRegisterDefinedParametersState): void {\n super._registerDefinedParameters(state);\n\n const { parentParameterNames } = state;\n const updatedParentParameterNames: Set<string> = new Set([\n ...parentParameterNames,\n ...this._registeredParameterParserKeysByName.keys()\n ]);\n\n this._subparserState = {\n ...state,\n parentParameterNames: updatedParentParameterNames\n };\n }\n\n /**\n * {@inheritdoc CommandLineParameterProvider.onDefineParameters}\n */\n protected onDefineParameters(): void {\n this.onDefineUnscopedParameters?.();\n\n if (!this._scopingParameters.length) {\n throw new Error(\n 'No scoping parameters defined. At least one scoping parameter must be defined. ' +\n 'Scoping parameters are defined by setting the parameterGroupName to ' +\n 'ScopedCommandLineAction.ScopingParameterGroupName.'\n );\n }\n if (this.remainder) {\n throw new Error(\n 'Unscoped remainder parameters are not allowed. Remainder parameters can only be defined on ' +\n 'the scoped parameter provider in onDefineScopedParameters().'\n );\n }\n\n // Consume the remainder of the command-line, which will later be passed the scoped parser.\n // This will also prevent developers from calling this.defineCommandLineRemainder(...) since\n // we will have already defined it.\n this.defineCommandLineRemainder({\n description:\n 'Scoped parameters. Must be prefixed with \"--\", ex. \"-- --scopedParameter ' +\n 'foo --scopedFlag\". For more information on available scoped parameters, use \"-- --help\".'\n });\n }\n\n /**\n * Retrieves the scoped CommandLineParser, which is populated after the ScopedCommandLineAction is executed.\n * @internal\n */\n protected _getScopedCommandLineParser(): CommandLineParser {\n if (!this._scopedCommandLineParser) {\n throw new Error('The scoped CommandLineParser is only populated after the action is executed.');\n }\n return this._scopedCommandLineParser;\n }\n\n /** @internal */\n protected _defineParameter(parameter: CommandLineParameter): void {\n super._defineParameter(parameter);\n if (parameter.parameterGroup === ScopedCommandLineAction.ScopingParameterGroup) {\n this._scopingParameters.push(parameter);\n }\n }\n\n /**\n * The child class should implement this hook to define its unscoped command-line parameters,\n * e.g. by calling defineFlagParameter(). At least one scoping parameter must be defined.\n * Scoping parameters are defined by setting the parameterGroupName to\n * ScopedCommandLineAction.ScopingParameterGroupName.\n */\n protected onDefineUnscopedParameters?(): void;\n\n /**\n * The child class should implement this hook to define its scoped command-line\n * parameters, e.g. by calling scopedParameterProvider.defineFlagParameter(). These\n * parameters will only be available if the action is invoked with a scope.\n *\n * @remarks\n * onDefineScopedParameters is called after the unscoped parameters have been parsed.\n * The values they provide can be used to vary the defined scope parameters.\n */\n protected abstract onDefineScopedParameters(scopedParameterProvider: CommandLineParameterProvider): void;\n\n /**\n * {@inheritDoc CommandLineAction.onExecute}\n */\n protected abstract onExecute(): Promise<void>;\n}\n"]} |