import { ClapNode } from "./clap-node.js"; import { NixClap } from "./nix-clap.js"; import { ClapNodeGenerator } from "./node-generator.js"; import { CommandNode } from "./command-node.js"; import { CommandBase } from "./command-base.js"; import { isBoolean } from "./xtil.js"; /** * The `Parser` class is responsible for parsing command-line arguments * and building a command tree structure. * * @class * @description * This class provides functionality to parse command-line arguments into a structured * representation of commands, options, and their values. It uses a tree-like structure * to represent nested commands and their associated options. * * @remarks * - The parser works with an instance of `NixClap` to handle the actual parsing logic. * - It maintains a list of `ClapNode` objects to represent the parsed structure. * - The parsing process is managed using a stack of `ClapNodeBuilder` instances. * - Error handling is implemented to catch and store parsing errors within the relevant nodes. * * @example * ```typescript * const nixClap = new NixClap(); * const parser = new Parser(nixClap); * const { command, index } = parser.parse(process.argv, 2); * // Now `command` contains the root of the parsed command tree * ``` */ export class Parser { /** * An instance of the NixClap class used for parsing command-line arguments. * This private member variable is utilized internally within the parser. * * @private */ private _nc: NixClap; /** * An array of command-line arguments passed to the application. * This is typically populated from the process.argv array. * * @private */ private _argv: string[]; /** * Creates an instance of the parser. * * @param nc - An instance of NixClap. */ constructor(nc: NixClap) { this._nc = nc; } /** * A stack of `ClapNodeBuilder` instances used to build the structure of the parsed command-line arguments. * This stack helps in managing nested command structures and ensures that the correct hierarchy is maintained. */ private _builderStack: ClapNodeGenerator[]; /** * Consumes the next argument and processes it using the current builder. * * If the argument is not an option (does not start with a "-"), it is processed as a non-option. * Otherwise, it is processed as an option. * * Depending on the result of the processing, the builder stack is updated: * - If the builder returns `null`, it is removed from the stack. * - If the builder is not complete, it is pushed back onto the stack. * * @param arg - The argument to be consumed and processed. */ private _consumeNext(arg: string) { const builder = this._builderStack.at(-1); const rets = !(arg[0] === "-") ? // not an option builder.consumeNonOpt(arg) : // an option builder.consumeOpt(arg); for (const _builder of rets) { if (_builder === null) { // avoid popping the root node if (this._builderStack.length > 1) { this._builderStack.pop(); } } else if (!_builder.isComplete) { this._builderStack.push(_builder); } } } /** * Parses the given command-line arguments starting from the specified index. * * This method processes the provided command-line arguments and builds a command tree structure. * It handles both options and non-option arguments, and can work with nested command structures. * * @param {string[]} argv - The array of command-line arguments to parse. * @param {number} start - The index in the argv array from which to start parsing. * @param {CommandNode} [command] - An optional root command node to start parsing with. * If not provided, a new root CommandNode will be created. * * @returns {{ command: CommandNode; index: number }} An object containing: * - command: The root CommandNode of the parsed command tree. * - index: The index in the argv array at which parsing ended. * * @throws {Error} Catches and stores any errors encountered during parsing in the command node's errors array. * * @remarks * - The method uses a stack of ClapNodeBuilder instances to manage the parsing process. * - It handles the '--' terminator, which signals the end of options. * - Any errors encountered during parsing are caught and stored in the relevant command node's errors array. * - After processing all arguments, it completes any remaining builders in the stack. */ /** * How many following argv entries this option token consumes as its value. * * Mirrors the tokenizer in ClapNodeGenerator.consumeOpt so the pre-scan agrees with the real * parse: `--no-x` and `--x=v` carry their value inline and consume nothing, a single-dash * cluster like `-abc` is boolean flags with only the last character able to take arguments, * and anything unrecognized consumes nothing so the real parse can report it as unknown. * * Options are looked up on the root command and on the configured default command, since a * CLI may declare them on either. * * @param arg - a raw argv entry already known to start with '-' * @returns count of subsequent argv entries taken as this option's value */ private _optionValueCount(arg: string, nextArg?: string): number { if (arg.startsWith("--no-")) { return 0; } const dashes = arg.startsWith("--") ? 2 : 1; let name = arg.substring(dashes); if (name.indexOf("=") > 0) { return 0; } if (dashes === 1 && name.length > 1) { // leading characters are boolean flags; only the last one may take arguments name = name[name.length - 1]; } // parse() already dereferences _rootCommand unconditionally before this runs, so it is // present by the time any option token is scanned - no guard needed for the optional type. const rootCmd = this._nc._rootCommand as CommandBase; const candidates: CommandBase[] = [rootCmd]; const defaultCommand = rootCmd.ncConfig?.defaultCommand; if (defaultCommand !== undefined) { const matched = rootCmd.matchSubCommand(defaultCommand); if (matched?.cmd) { candidates.push(matched.cmd); } } for (const cmd of candidates) { const matched = cmd.options?.match({ name, value: undefined, verbatim: name, dashes, arg } as any); if (matched && matched.option) { if ( matched.option.expectArgs > 0 && matched.option.args[0].type === "boolean" && !isBoolean(nextArg) ) { return 0; } return matched.option.expectArgs || 0; } } return 0; } parse( argv: string[], start: number, command?: CommandNode ): { command: CommandNode; index: number } { this._argv = argv; let rootNode = command || new CommandNode( this._nc._rootCommand.name, this._nc._rootCommand.alias[0], this._nc._rootCommand ); let _index = start; // Preprocess: check if there are any non-option arguments // If all arguments are options (start with '-'), we may need to insert default command // If there are non-option arguments, we don't need to insert default command // // An option's own value is not a command argument. `--name foo` puts `foo` in argv as its // own entry, so a scan that only looks at the leading dash would read it as a command and // suppress the default command - which broke every `defaultCommand` CLI invoked with a // separated option value, while `--name=foo` worked by accident (FJM-137). Consult the // option specs and skip the values they consume. let hasNonOptionArgs = false; let hasHelpOrVersion = false; for (let i = start; i < argv.length; i++) { const arg = argv[i]; if (arg === "--") { // Everything after -- is treated as non-option hasNonOptionArgs = true; break; } if (arg[0] !== "-") { hasNonOptionArgs = true; break; } i += this._optionValueCount(arg, argv[i + 1]); // Check for --help, -h, -?, --version, -v, -V // These should show root command help/version, not default command's if ( arg === "--help" || arg === "-h" || arg === "-?" || arg === "--version" || arg === "-v" || arg === "-V" ) { hasHelpOrVersion = true; } } // Check if default command is configured const hasDefaultCommand = this._nc._rootCommand?.ncConfig?.defaultCommand !== undefined; // Check if default command execution is skipped // If skipped, don't insert upfront (it will be inserted during execution if needed) const skipExecDefault = (this._nc as any)._skipExecDefault === true; // If no non-option args exist and default command is configured, insert it upfront // This way all parsing happens under the default command from the start // Skip if skipExecDefault is true (to prevent execution) // Skip if --help or --version is present (should show root help/version) if (!hasNonOptionArgs && hasDefaultCommand && !skipExecDefault && !hasHelpOrVersion) { const defaultCmdName = this._nc._rootCommand.ncConfig.defaultCommand; const matched = rootNode.cmdBase.matchSubCommand(defaultCmdName); if (matched.cmd) { const defaultCmdNode = new CommandNode(matched.name, matched.alias, matched.cmd); defaultCmdNode.applyDefaults(); rootNode.addCommandNode(defaultCmdNode); // Start parsing under the default command, with root as parent // This allows root options to be checked when they don't match default command const rootBuilder = new ClapNodeGenerator(rootNode); const defaultCmdBuilder = new ClapNodeGenerator(defaultCmdNode, rootBuilder); this._builderStack = [defaultCmdBuilder]; } else { // Default command not found, set error rootNode.addError(new Error(`default command ${defaultCmdName} not found`)); this._builderStack = [new ClapNodeGenerator(rootNode)]; } } else { this._builderStack = [new ClapNodeGenerator(rootNode)]; } while (_index < argv.length) { const arg = this._argv[_index]; _index++; if (arg === "--") { break; } try { this._consumeNext(arg); } catch (e) { this._builderStack.at(-1).node.errors.push(e); } } try { let builder = this._builderStack.at(-1); while (builder) { builder.complete(); builder = builder.parent; } } catch (e) { rootNode.errors.push(e); } return { command: rootNode, index: _index }; } }