Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -132,26 +132,6 @@ class BetterCommandRunner<O extends OptionDefinition, T>
/// final ConfigOptionBase<V> 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<OptionDefinition, void>(
/// 'tool',
/// 'Tools',
/// parserSettings: const ParserSettings(
/// doubleDashHandling: DoubleDashHandling.passThroughRest,
/// ),
/// ignoreUnexpectedPositionalArgs: true,
/// );
/// // tool build -q -- --some --remaining
/// // commandConfig.remainingPosArgs == ['--some', '--remaining']
/// ```
BetterCommandRunner(
super.executableName,
super.description, {
Expand All @@ -161,7 +141,6 @@ class BetterCommandRunner<O extends OptionDefinition, T>
final List<CommandMiddleware<O, T>>? prependMiddlewares,
final SetLogLevel? setLogLevel,
super.usageGenerator,
super.ignoreUnexpectedPositionalArgs,
super.parserSettings,
final UsageOutputHandler? usageOutput,
final CompletionSettings? completion,
Expand Down Expand Up @@ -218,12 +197,13 @@ class BetterCommandRunner<O extends OptionDefinition, T>
);

addMiddleware(
Middlewares.onBeforeRun(
(final ctx) => setLogLevel?.call(
Middlewares.onBeforeRun((final ctx) {
if (ctx.runMode == CommandRunMode.completion) return;
setLogLevel?.call(
parsedLogLevel: _determineLogLevel(ctx.config),
commandName: ctx.next?.command.name,
),
),
);
}),
);

if (onBeforeRunCommand case final OnBeforeRunCommand onBeforeRun) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ Command<OptionDefinition, void> _createLeafCommand() {
..._createOptions,
StringOption(argPos: 0),
],
ignoreUnexpectedPositionalArgs: true,
run: (final _) {},
);
}
Expand Down Expand Up @@ -244,7 +245,6 @@ void main() {
runner = CommandRunner<OptionDefinition, void>(
'tool',
'test cli',
ignoreUnexpectedPositionalArgs: true,
subcommands: [
_createBranchCommand(subcommands: [_templateCommand()]),
],
Expand Down
13 changes: 12 additions & 1 deletion packages/config/lib/src/command/abstract_command.dart
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,17 @@ abstract class AbstractCommand<O extends OptionDefinition, T>
final CommandContext<OptionDefinition, T>? prevContext,
) => null;

/// Whether additional positional arguments (that don't match the defined
/// positional options) are allowed after this command. Defaults to false.
///
/// When true, such arguments are included in [Configuration.remainingPosArgs]
/// of this command and do not fail the run.
/// Otherwise they are reported as usage errors.
///
/// Setting this to true only has effect for leaf commands.
@override
bool get ignoreUnexpectedPositionalArgs => false;

/// Whether this command accepts a partial command line, i.e. runs as the
/// last command on the command line even if the command line is incomplete.
///
Expand Down Expand Up @@ -192,7 +203,7 @@ abstract class AbstractCommand<O extends OptionDefinition, T>
parsedArgs: parsedArgs,
env: env,
configBroker: configBroker(prevContext),
ignoreUnexpectedPositionalArgs: runner.ignoreUnexpectedPositionalArgs,
ignoreUnexpectedPositionalArgs: ignoreUnexpectedPositionalArgs,
);

return CommandContext<O, T>(
Expand Down
36 changes: 29 additions & 7 deletions packages/config/lib/src/command/command.dart
Original file line number Diff line number Diff line change
Expand Up @@ -179,25 +179,34 @@ abstract class CommandImpl<O extends OptionDefinition, T>
@override
final String name;

@override
final bool ignoreUnexpectedPositionalArgs;

CommandImpl({
required this.name,
required final String description,
final String? usageFooter,
final String? category,
final bool? hidden,
final String? invocation,
final String? summary,
final List<String>? aliases,
final List<String>? suggestionAliases,
final bool? ignoreUnexpectedPositionalArgs,
super.persistentOptions,
super.options,
super.subcommands,
super.middlewares,
super.canRunAsLeafCommand,
}) : super(
}) : ignoreUnexpectedPositionalArgs = ignoreUnexpectedPositionalArgs ?? false,
super(
usageDefinition: CommandUsageDefinition(
description: description,
usageFooter: usageFooter,
category: category,
hidden: hidden,
invocation: invocation,
summary: summary,
),
aliasesDefinition: CommandAliasesDefinition(
aliases: aliases,
Expand All @@ -216,6 +225,8 @@ abstract class CommandImpl<O extends OptionDefinition, T>
final String? usageFooter,
final String? category,
final bool? hidden,
final String? invocation,
final String? summary,
final List<String>? aliases,
final List<String>? suggestionAliases,
final List<CommandMiddleware<O, T>>? middlewares,
Expand All @@ -229,6 +240,8 @@ abstract class CommandImpl<O extends OptionDefinition, T>
usageFooter: usageFooter,
category: category,
hidden: hidden,
invocation: invocation,
summary: summary,
aliases: aliases,
suggestionAliases: suggestionAliases,
middlewares: middlewares,
Expand Down Expand Up @@ -256,8 +269,11 @@ abstract class CommandImpl<O extends OptionDefinition, T>
final String? usageFooter,
final String? category,
final bool? hidden,
final String? invocation,
final String? summary,
final List<String>? aliases,
final List<String>? suggestionAliases,
final bool? ignoreUnexpectedPositionalArgs,
final List<O>? options,
final List<CommandMiddleware<O, T>>? middlewares,
required final CommandRunFunction<O, T> run,
Expand All @@ -268,8 +284,11 @@ abstract class CommandImpl<O extends OptionDefinition, T>
usageFooter: usageFooter,
category: category,
hidden: hidden,
invocation: invocation,
summary: summary,
aliases: aliases,
suggestionAliases: suggestionAliases,
ignoreUnexpectedPositionalArgs: ignoreUnexpectedPositionalArgs,
middlewares: middlewares,
options: options,
run: run,
Expand All @@ -284,12 +303,15 @@ class _CommandWithRunFunction<O extends OptionDefinition, T>
_CommandWithRunFunction({
required super.name,
required super.description,
required super.usageFooter,
required super.category,
required super.hidden,
required super.aliases,
required super.suggestionAliases,
required super.middlewares,
super.usageFooter,
super.category,
super.hidden,
super.invocation,
super.summary,
super.aliases,
super.suggestionAliases,
super.ignoreUnexpectedPositionalArgs,
super.middlewares,
super.persistentOptions,
super.options,
super.subcommands,
Expand Down
120 changes: 72 additions & 48 deletions packages/config/lib/src/command/command_runner.dart
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,47 @@ import 'usage_output.dart';
/// Using int as T can be sensible in order to return the exit code that the
/// command executable should return.
///
/// ## Usage
///
/// ### Built-in options and commands
///
/// The built-in global option `--help` / `-h` is predefined,
/// as is `--completion <shell>` if the runner has no subcommands,
/// see [builtinPersistentOptions].
///
/// If the runner has subcommands, the built-in commands are added: `help`,
/// and if completion is enabled, `completion` and`__complete`.
///
/// ### Action options
///
/// Action options are arguments that have the syntax of an option flag but run
/// like a command. They are defined by an [OptionDefinition] with the
/// [ActionOptionMixin] mixin. If present, they run instead of a command.
/// A use case example is the `--version` option.
///
/// ### Pass-through arguments after `--`
///
/// To accept arguments written after `--`, pass
/// [DoubleDashHandling.passThroughRest].
/// In addition, the command that receives them must set
/// [ignoreUnexpectedPositionalArgs] to true.
/// It can then read the list from [Configuration.remainingPosArgs]:
///
/// ```dart
/// CommandRunner<OptionDefinition, void>(
/// 'tool',
/// 'Tools',
/// parserSettings: const ParserSettings(
/// doubleDashHandling: DoubleDashHandling.passThroughRest,
/// ),
/// );
/// @override
/// bool get ignoreUnexpectedPositionalArgs => true;
/// ...
/// // tool build -q -- --some --remaining
/// // context.config.remainingPosArgs == ['--some', '--remaining']
/// ```
///
/// ## Design
///
/// Uses the concept of middlewares to customize the execution logic
Expand Down Expand Up @@ -114,13 +155,6 @@ class CommandRunner<O extends OptionDefinition, T>
final CommandAliasesDefinition aliasesDefinition =
const CommandAliasesDefinition();

/// Whether a positional argument that matches no positional option is allowed.
///
/// 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;

/// Settings for scanning and parsing the command line.
final ParserSettings parserSettings;

Expand All @@ -138,71 +172,60 @@ class CommandRunner<O extends OptionDefinition, T>

/// Creates a new command runner with the given executable name and description.
///
/// [globalOptions] is the list of global options.
/// Global options are "persistent" which means they are valid anywhere on the
/// command line. A subcommand shadows an identical spelling of a global
/// option, and leaves the global option's other spellings in place.
/// [executableName] is the name of the executable being run, as presented in
/// usage and error messages.
///
/// [description] is the usage description of this root command
/// (the executable).
///
/// [invocation] overrides the default invocation synopsis of this root
/// command (the executable).
///
/// [rootFooter] is a string that will be added to this root command's usage
/// footer.
///
/// The built-in global option `--help` / `-h` is available in addition,
/// as is `--completion <shell>` for a runner without subcommands,
/// see [builtinPersistentOptions].
/// [globalOptions] is the list of global options. Global options are
/// "persistent" which means they are valid anywhere on the command line.
///
/// [subcommands] is a list of subcommands that will be added to
/// the runner. Can also be added later using [addSubcommand].
/// [subcommands] is a list of subcommands that will be added to the runner.
/// Can also be added later using [addSubcommand].
///
/// [middlewares] is a list of middlewares that will be added to the runner.
///
/// [ignoreUnexpectedPositionalArgs] when true keeps positional arguments
/// that match no positional option on [Configuration.remainingPosArgs].
/// Defaults to false, which reports them as a usage error.
/// If not provided, it defaults to true if [parserSettings.doubleDashHandling]
/// is [DoubleDashHandling.passThroughRest].
/// [canRunAsLeafCommand] when true allows this command to run as a leaf
/// command even if it has subcommands.
///
/// [parserSettings] controls parsing and defaults to [ParserSettings].
/// To accept arguments written after `--`, pass
/// [DoubleDashHandling.passThroughRest]. The command that received
/// them reads the list from [Configuration.remainingPosArgs]:
/// [usageGenerator] overrides the [UsageGenerator] for this root command
/// (not its subcommands, each command has its own).
///
/// ```dart
/// CommandRunner<OptionDefinition, void>(
/// 'tool',
/// 'Tools',
/// parserSettings: const ParserSettings(
/// doubleDashHandling: DoubleDashHandling.passThroughRest,
/// ),
/// ignoreUnexpectedPositionalArgs: true,
/// );
/// // tool build -q -- --some --remaining
/// // context.config.remainingPosArgs == ['--some', '--remaining']
/// ```
/// [parserSettings] overrides the default [ParserSettings] for this runner
/// and its subcommands.
///
/// [rootFooter] is a string that will be added to the runner's usage footer.
/// [usageOutput] overrides the default [UsageOutputHandler] for this runner
/// and its subcommands.
///
/// [completion] configures the built-in shell completion support,
/// which is enabled by default. See [CompletionSettings].
/// [completion] configures the built-in shell completion support for this
/// runner and its subcommands. See [CompletionSettings].
CommandRunner(
this.executableName,
final String description, {
final List<O>? globalOptions,
final String? invocation,
final String? rootFooter,
final List<O>? globalOptions,
super.subcommands,
super.middlewares,
super.canRunAsLeafCommand,
final UsageGenerator? usageGenerator,
final bool? ignoreUnexpectedPositionalArgs,
final ParserSettings? parserSettings,
final UsageOutputHandler? usageOutput,
final CompletionSettings? completion,
}) : usageDefinition = CommandUsageDefinition(
description: description,
usageFooter: rootFooter,
invocation: invocation,
),
usageOutput = usageOutput ?? UsageOutputHandler(),
completion = completion ?? const CompletionSettings(),
ignoreUnexpectedPositionalArgs =
ignoreUnexpectedPositionalArgs ??
parserSettings?.doubleDashHandling ==
DoubleDashHandling.passThroughRest,
parserSettings = parserSettings ?? const ParserSettings(),
super(
usageGenerator: usageGenerator ?? const StandardRunnerUsageGenerator(),
Expand Down Expand Up @@ -242,7 +265,9 @@ class CommandRunner<O extends OptionDefinition, T>
/// and returns `null` without running any command. Middleware still runs
/// through the runner, which defines `--help`.
///
/// To make a subcommand which is named like an option, simply define it, for example:
/// To make a subcommand which is named like an option, simply define it
/// like the following example. But typically it is better to define an
/// action option instead.
/// ```dart
/// CommandImpl.leafWithRunFunction(
/// name: 'version',
Expand Down Expand Up @@ -325,7 +350,6 @@ class CommandRunner<O extends OptionDefinition, T>
final engine = CompletionEngine<O, T>(
this,
resolver: resolver,
ignoreUnexpectedPositionalArgs: ignoreUnexpectedPositionalArgs,
parserSettings: parserSettings,
onError: (final error, final stackTrace) {
completion.sinks.err.writeln(
Expand Down
Loading
Loading