From 76127d1065db78167133947630651454258ba0a6 Mon Sep 17 00:00:00 2001 From: Christer Date: Thu, 19 Nov 2026 19:57:01 +0100 Subject: [PATCH] feat(command): Accept arguments after -- via parser settings CommandRunner takes ParserSettings and passes them through, so a standalone -- can stop parsing and the remaining arguments can be read back. Co-authored-by: Cursor --- .../better_command_runner.dart | 22 ++++++- .../command_line_properties_test.dart | 3 + packages/config/README_command.md | 66 +++++++++++++++++++ .../lib/src/command/command_resolver.dart | 9 +-- .../lib/src/command/command_runner.dart | 47 ++++++++----- .../command/completion/completion_engine.dart | 11 ++-- .../config/arg_parser/parser_settings.dart | 5 +- .../config/lib/src/config/configuration.dart | 4 ++ .../completion/completion_engine_test.dart | 6 +- .../completion/fixtures/completion_cli.dart | 2 + 10 files changed, 140 insertions(+), 35 deletions(-) diff --git a/packages/cli_tools/lib/src/better_command_runner/better_command_runner.dart b/packages/cli_tools/lib/src/better_command_runner/better_command_runner.dart index 1ab77be2..1b0c3901 100644 --- a/packages/cli_tools/lib/src/better_command_runner/better_command_runner.dart +++ b/packages/cli_tools/lib/src/better_command_runner/better_command_runner.dart @@ -132,11 +132,31 @@ class BetterCommandRunner /// final ConfigOptionBase option; /// } /// ``` + /// + /// ## Arguments after `--` + /// + /// To keep arguments written after `--`, pass [parserSettings] with + /// [DoubleDashHandling.passThroughRest] and set + /// [ignoreUnexpectedPositionalArgs] to true. `runWithConfig` reads them + /// from [Configuration.remainingPosArgs]: + /// + /// ```dart + /// BetterCommandRunner( + /// 'tool', + /// 'Tools', + /// parserSettings: const ParserSettings( + /// doubleDashHandling: DoubleDashHandling.passThroughRest, + /// ), + /// ignoreUnexpectedPositionalArgs: true, + /// ); + /// // tool build -q -- --some --remaining + /// // commandConfig.remainingPosArgs == ['--some', '--remaining'] + /// ``` BetterCommandRunner( super.executableName, super.description, { final UsageOutputHandler? usageOutput, - super.suggestionDistanceLimit, + super.parserSettings, @Deprecated('Use usageOutput instead') final MessageOutput? messageOutput, final SetLogLevel? setLogLevel, @Deprecated('Use a middleware instead') diff --git a/packages/cli_tools/test/analytics/command_line_properties_test.dart b/packages/cli_tools/test/analytics/command_line_properties_test.dart index 3791973f..73bbcaf0 100644 --- a/packages/cli_tools/test/analytics/command_line_properties_test.dart +++ b/packages/cli_tools/test/analytics/command_line_properties_test.dart @@ -60,6 +60,9 @@ void main() { 'tool', 'test cli', ignoreUnexpectedPositionalArgs: true, + parserSettings: const ParserSettings( + doubleDashHandling: DoubleDashHandling.passThroughRest, + ), subcommands: [_createLeafCommand()], ); }); diff --git a/packages/config/README_command.md b/packages/config/README_command.md index 69ef7c32..16739eed 100644 --- a/packages/config/README_command.md +++ b/packages/config/README_command.md @@ -144,6 +144,72 @@ The built-ins `--help`, the `help` command, and `--completion` accept an incomplete line. A custom command opts in by overriding `acceptsPartialCommandLine`. +## Parser settings and extra positional arguments + +`CommandRunner` has two independent settings for arguments that are not +options of the command being parsed. + +### `ParserSettings` + +`CommandRunner.parserSettings` is passed through to the parser. +The default is `ParserSettings()`. + +`doubleDashHandling` decides what a standalone `--` means: + +- `DoubleDashHandling.noSpecialHandling`, the default. `--` is an unexpected + value, and parsing continues. A later `--flag` is still parsed as an option. +- `DoubleDashHandling.passThroughRest`. Parsing stops at `--`. Every argument + after it is left unparsed, so it is not an option, a subcommand, or an + option value. A `--` that is consumed as an option value does not stop + parsing, and a later `--` still does. + +`suggestionDistanceLimit` is the maximum edit distance for "Did you mean" +command suggestions. The default is 2. Set it to 0 to disable suggestions. + +### `ignoreUnexpectedPositionalArgs` + +A positional word that matches no positional option is unexpected. +Arguments left unparsed after `--` count as such words. + +When `ignoreUnexpectedPositionalArgs` is false, the default, those words +fail the run and are reported as a usage error. + +When it is true, they do not fail the run. Positional options take words +in position order, including words that followed `--`. Anything left is +`Configuration.remainingPosArgs` on the command where parsing of those +words stopped. + +Accepting a tail of arguments uses both settings. `passThroughRest` stops +option parsing, and `ignoreUnexpectedPositionalArgs` keeps the unparsed +words instead of failing: + +```dart +import 'package:config/command.dart'; +import 'package:config/config.dart'; + +final runner = CommandRunner( + 'tool', + 'Tools', + parserSettings: const ParserSettings( + doubleDashHandling: DoubleDashHandling.passThroughRest, + ), + ignoreUnexpectedPositionalArgs: true, +); +``` + +```sh +tool build -q -- --some --remaining --args +``` + +`-q` is parsed as a flag of `build`. In that command, +`context.config.remainingPosArgs` is +`['--some', '--remaining', '--args']`. + +If `build` declares a positional option, that option takes the first of +those words, and only the unused ones stay in `remainingPosArgs`. +`BetterCommand.runWithConfig` receives the same configuration, so the list +there is `commandConfig.remainingPosArgs`. + ## Shell completion The `CommandRunner` in `package:config/command.dart` has built-in command line diff --git a/packages/config/lib/src/command/command_resolver.dart b/packages/config/lib/src/command/command_resolver.dart index 8255135a..62315cb1 100644 --- a/packages/config/lib/src/command/command_resolver.dart +++ b/packages/config/lib/src/command/command_resolver.dart @@ -1,8 +1,6 @@ import '../../config.dart' show ArgParseResult, - DoubleDashHandling, - ParserSettings, scanAndParseCommands, subcommandRequiredErrorPrefix, CommandDefinition, @@ -61,12 +59,7 @@ class StandardCommandResolver final argParseResult = scanAndParseCommands( args, rootCommand: runner, - settings: ParserSettings( - doubleDashHandling: runner.ignoreUnexpectedPositionalArgs - ? DoubleDashHandling.passThroughRest - : DoubleDashHandling.noSpecialHandling, - suggestionDistanceLimit: runner.suggestionDistanceLimit, - ), + settings: runner.parserSettings, ); final contextChain = resolveNext( diff --git a/packages/config/lib/src/command/command_runner.dart b/packages/config/lib/src/command/command_runner.dart index fb2ebc29..d8f3d1b4 100644 --- a/packages/config/lib/src/command/command_runner.dart +++ b/packages/config/lib/src/command/command_runner.dart @@ -14,6 +14,8 @@ import '../../config.dart' FlagOption, MultiOption, ArgParseResult, + DoubleDashHandling, + ParserSettings, NewParsedArgs; import 'abstract_command.dart'; import 'builtin_global_option.dart'; @@ -113,21 +115,14 @@ class CommandRunner const CommandAliasesDefinition(); /// Whether a positional argument that matches no positional option is allowed. - /// If true, such arguments are included in [Configuration.remainingPosArgs] - /// of the last command's configuration. - /// This also enables the `--` double dash argument, which stops parsing of - /// the command line and instead puts the following arguments in - /// [Configuration.remainingPosArgs] of the last parsed command. /// - /// When false, the default, those arguments are included in the - /// [UsageException] thrown before any command runs. + /// When true, such arguments are included in [Configuration.remainingPosArgs] + /// of the command that received them and do not fail the run. + /// When false (default) they are reported as a usage error. final bool ignoreUnexpectedPositionalArgs; - /// The maximum edit distance allowed when suggesting possible intended - /// commands. - /// - /// Set to `0` in order to disable suggestions, defaults to `2`. - final int suggestionDistanceLimit; + /// Settings for scanning and parsing the command line. + final ParserSettings parserSettings; /// The settings and behavior for the usage output - /// controls the help output and the usage exception output. @@ -157,7 +152,28 @@ class CommandRunner /// /// [middlewares] is a list of middlewares that will be added to the runner. /// - /// [ignoreUnexpectedPositionalArgs] is a boolean that determines whether unexpected positional arguments should be ignored. + /// [ignoreUnexpectedPositionalArgs] when true keeps positional arguments + /// that match no positional option on [Configuration.remainingPosArgs]. + /// Defaults to false, which reports them as a usage error. + /// + /// [parserSettings] controls parsing and defaults to [ParserSettings]. + /// To keep arguments written after `--`, pass + /// [DoubleDashHandling.passThroughRest] and set + /// [ignoreUnexpectedPositionalArgs] to true. The command that received + /// them reads the list from [Configuration.remainingPosArgs]: + /// + /// ```dart + /// CommandRunner( + /// 'tool', + /// 'Tools', + /// parserSettings: const ParserSettings( + /// doubleDashHandling: DoubleDashHandling.passThroughRest, + /// ), + /// ignoreUnexpectedPositionalArgs: true, + /// ); + /// // tool build -q -- --some --remaining + /// // context.config.remainingPosArgs == ['--some', '--remaining'] + /// ``` /// /// [rootFooter] is a string that will be added to the runner's usage footer. /// @@ -174,7 +190,7 @@ class CommandRunner super.usageLineLength, final UsageGenerator? usageGenerator, final bool? ignoreUnexpectedPositionalArgs, - final int? suggestionDistanceLimit, + final ParserSettings? parserSettings, final UsageOutputHandler? usageOutput, final CompletionSettings? completion, }) : usageDefinition = CommandUsageDefinition( @@ -184,7 +200,7 @@ class CommandRunner usageOutput = usageOutput ?? UsageOutputHandler(), completion = completion ?? const CompletionSettings(), ignoreUnexpectedPositionalArgs = ignoreUnexpectedPositionalArgs ?? false, - suggestionDistanceLimit = suggestionDistanceLimit ?? 2, + parserSettings = parserSettings ?? const ParserSettings(), super( usageGenerator: usageGenerator ?? const StandardRunnerUsageGenerator(), persistentOptions: globalOptions, @@ -307,6 +323,7 @@ class CommandRunner this, resolver: resolver, ignoreUnexpectedPositionalArgs: ignoreUnexpectedPositionalArgs, + parserSettings: parserSettings, onError: (final error, final stackTrace) { completion.sinks.err.writeln( 'Completion failed: $error\n$stackTrace', diff --git a/packages/config/lib/src/command/completion/completion_engine.dart b/packages/config/lib/src/command/completion/completion_engine.dart index 472c9ded..1adfca9e 100644 --- a/packages/config/lib/src/command/completion/completion_engine.dart +++ b/packages/config/lib/src/command/completion/completion_engine.dart @@ -3,7 +3,6 @@ import 'dart:async' show FutureOr; import '../../config/arg_parser/arg_parser.dart' show ArgParseResult, - DoubleDashHandling, ParserSettings, optionAwaitingValue, scanAndParseCommands, @@ -39,6 +38,9 @@ class CompletionEngine { /// See `CommandRunner.ignoreUnexpectedPositionalArgs`. final bool ignoreUnexpectedPositionalArgs; + /// See `CommandRunner.parserSettings`. + final ParserSettings parserSettings; + /// Receives a diagnostic message when a completion request fails. final void Function(Object error, StackTrace stackTrace)? onError; @@ -53,6 +55,7 @@ class CompletionEngine { this.rootCommand, { this.resolver, this.ignoreUnexpectedPositionalArgs = false, + this.parserSettings = const ParserSettings(), this.onError, }); @@ -101,11 +104,7 @@ class CompletionEngine { final parsed = scanAndParseCommands( [...preceding, _sentinel], rootCommand: rootCommand, - settings: ParserSettings( - doubleDashHandling: ignoreUnexpectedPositionalArgs - ? DoubleDashHandling.passThroughRest - : DoubleDashHandling.noSpecialHandling, - ), + settings: parserSettings, ); final chain = parsed.toList(); final line = _CommandLine( diff --git a/packages/config/lib/src/config/arg_parser/parser_settings.dart b/packages/config/lib/src/config/arg_parser/parser_settings.dart index 66c001d1..1ce5f82b 100644 --- a/packages/config/lib/src/config/arg_parser/parser_settings.dart +++ b/packages/config/lib/src/config/arg_parser/parser_settings.dart @@ -2,9 +2,8 @@ enum DoubleDashHandling { /// No special handling means it is treated as any other word. noSpecialHandling, - /// When `--` is not taken as an option value, leave the following - /// arguments unparsed. A `--` used as a value does not start this, - /// so a later `--` still can. + /// Every argument after a `--` is left unparsed, unless the `--` is consumed + /// as an option value (in which case a later `--` still stops parsing). passThroughRest, } diff --git a/packages/config/lib/src/config/configuration.dart b/packages/config/lib/src/config/configuration.dart index 9098d65f..91458151 100644 --- a/packages/config/lib/src/config/configuration.dart +++ b/packages/config/lib/src/config/configuration.dart @@ -86,6 +86,10 @@ class Configuration { /// /// If [presetValues] is provided, the values present will override the other sources, /// including if they are null. + /// + /// If [ignoreUnexpectedPositionalArgs] is true, unexpected positional + /// arguments will be ignored, and available as [remainingPosArgs]. + /// If false they will be reported as errors. /// {@endtemplate} /// /// This does not throw upon value parsing or validation errors, diff --git a/packages/config/test/command/completion/completion_engine_test.dart b/packages/config/test/command/completion/completion_engine_test.dart index 47797928..82f27cac 100644 --- a/packages/config/test/command/completion/completion_engine_test.dart +++ b/packages/config/test/command/completion/completion_engine_test.dart @@ -544,11 +544,13 @@ void main() { }); test('when completing after a double dash ' - 'and unexpected positional arguments are ignored ' + 'and arguments after -- are passed through ' 'then file completion is requested', () async { runner = buildCompletionCli( usageOutput: UsageOutputHandler(sinks: OutputSinks(out: out)), - ignoreUnexpectedPositionalArgs: true, + parserSettings: const ParserSettings( + doubleDashHandling: DoubleDashHandling.passThroughRest, + ), completionOutput: out, ); final response = await complete(runner, out, ['build', '--', '-']); diff --git a/packages/config/test/command/completion/fixtures/completion_cli.dart b/packages/config/test/command/completion/fixtures/completion_cli.dart index 55d81d1f..42e459eb 100644 --- a/packages/config/test/command/completion/fixtures/completion_cli.dart +++ b/packages/config/test/command/completion/fixtures/completion_cli.dart @@ -188,6 +188,7 @@ CommandRunner buildCompletionCli({ final StringSink? completionOutput, final StringSink? completionError, final bool ignoreUnexpectedPositionalArgs = false, + final ParserSettings parserSettings = const ParserSettings(), final List? trace, final List> extraCommands = const [], }) { @@ -210,6 +211,7 @@ CommandRunner buildCompletionCli({ errorOutput: completionError, ), ignoreUnexpectedPositionalArgs: ignoreUnexpectedPositionalArgs, + parserSettings: parserSettings, middlewares: [ Middlewares.onBeforeRun((final ctx) { trace?.add('middleware:${ctx.command.name}');