diff --git a/packages/config/example/command_example.dart b/packages/config/example/command_example.dart index 252bd23..410a232 100644 --- a/packages/config/example/command_example.dart +++ b/packages/config/example/command_example.dart @@ -92,7 +92,7 @@ Future main(final List args) async { } /// `--version` / `-v`: prints the version instead of running a subcommand. -class VersionActionOption extends FlagOption with ActionOptionMixin { +class VersionActionOption extends FlagOption with ActionOptionMixin { /// Creates the version action option. const VersionActionOption() : super( diff --git a/packages/config/lib/src/command/abstract_command.dart b/packages/config/lib/src/command/abstract_command.dart index 3573e65..bcb8d8c 100644 --- a/packages/config/lib/src/command/abstract_command.dart +++ b/packages/config/lib/src/command/abstract_command.dart @@ -1,7 +1,6 @@ import 'dart:async' show FutureOr; -import '../../middleware.dart' show MiddlewareChain, Middleware; -import '../config/config.dart' +import '../../config.dart' show OptionDefinition, CommandDefinition, @@ -9,6 +8,7 @@ import '../config/config.dart' ConfigurationBroker, ArgParseResult, NewParsedArgs; +import '../../middleware.dart' show MiddlewareChain, Middleware; import 'command.dart' show Command; import 'command_context.dart'; import 'command_middleware.dart'; diff --git a/packages/config/lib/src/command/action_option.dart b/packages/config/lib/src/command/action_option.dart new file mode 100644 index 0000000..e576fb4 --- /dev/null +++ b/packages/config/lib/src/command/action_option.dart @@ -0,0 +1,25 @@ +import 'dart:async' show FutureOr; + +import '../../config.dart' show OptionDefinition; +import 'command_context.dart'; + +/// ActionOptionMixin can be added to an option definition to make CommandRunner +/// run it as an "action option" when it is specified on the command line. +/// +/// As a convenience, access the full option object via the inherited [option] +/// getter. +mixin ActionOptionMixin implements OptionDefinition { + /// Whether this action option accepts a partial command line, + /// i.e. runs even if the command line is incomplete. + /// + /// True by default for action options. + /// + /// {@macro acceptsPartialCommandLine} + bool get acceptsPartialCommandLine => true; + + /// Runs this action option. + /// [context] is the context of the command that defined this action option. + FutureOr run( + final CommandContext context, + ); +} diff --git a/packages/config/lib/src/command/builtin_global_option.dart b/packages/config/lib/src/command/builtin_global_option.dart index aee66c9..0cd4488 100644 --- a/packages/config/lib/src/command/builtin_global_option.dart +++ b/packages/config/lib/src/command/builtin_global_option.dart @@ -1,9 +1,9 @@ import 'dart:async' show FutureOr; -import '../config/config.dart' +import '../../config.dart' show ConfigOptionBase, EnumOption, EnumParser, FlagOption, OptionDefinition; +import 'action_option.dart'; import 'command_context.dart'; -import 'command_runner.dart' show ActionOptionMixin; import 'completion/completion.dart' show printCompletionScript; import 'completion/completion_shell.dart' show CompletionShell; import 'help_command.dart' show printCommandUsage; @@ -23,7 +23,7 @@ enum BuiltinGlobalOption implements OptionDefinition { final ConfigOptionBase option; } -class HelpActionOption extends FlagOption with ActionOptionMixin { +class HelpActionOption extends FlagOption with ActionOptionMixin { const HelpActionOption() : super( argName: 'help', @@ -42,7 +42,7 @@ class HelpActionOption extends FlagOption with ActionOptionMixin { } class CompletionActionOption extends EnumOption - with ActionOptionMixin { + with ActionOptionMixin { const CompletionActionOption() : super( enumParser: const EnumParser(CompletionShell.values), diff --git a/packages/config/lib/src/command/command.dart b/packages/config/lib/src/command/command.dart index beac779..39f0fac 100644 --- a/packages/config/lib/src/command/command.dart +++ b/packages/config/lib/src/command/command.dart @@ -1,6 +1,6 @@ import 'dart:async' show FutureOr; -import '../config/config.dart' +import '../../config.dart' show OptionDefinition, CommandUsageDefinition, diff --git a/packages/config/lib/src/command/command_context.dart b/packages/config/lib/src/command/command_context.dart index 4459f92..ff68023 100644 --- a/packages/config/lib/src/command/command_context.dart +++ b/packages/config/lib/src/command/command_context.dart @@ -1,5 +1,7 @@ -import '../../config.dart' show OptionDefinition, Configuration; +import '../../config.dart' + show OptionDefinition, Configuration, ValueSourceType; import 'abstract_command.dart'; +import 'action_option.dart'; import 'builtin_global_option.dart'; import 'context_provider.dart'; @@ -84,4 +86,23 @@ class CommandContext { final nextContext = next; return nextContext == null ? this : nextContext.leaf(); } + + /// Returns the action options of the command that were specified on the + /// command line, if any. + /// + /// If non-empty, the first one is run instead of the command. + List specifiedActionOptions() { + final allArgOptions = [ + ...config.optionsWhereSource( + (final ValueSourceType s) => s == ValueSourceType.arg, + ), + ...builtinConfig.optionsWhereSource( + (final ValueSourceType s) => s == ValueSourceType.arg, + ), + ]; + return allArgOptions + .map((final o) => o is ActionOptionMixin ? o : o.option) + .whereType() + .toList(); + } } diff --git a/packages/config/lib/src/command/command_middleware.dart b/packages/config/lib/src/command/command_middleware.dart index a81fbb7..ac9cae7 100644 --- a/packages/config/lib/src/command/command_middleware.dart +++ b/packages/config/lib/src/command/command_middleware.dart @@ -1,7 +1,7 @@ import 'dart:async' show FutureOr; +import '../../config.dart' show OptionDefinition; import '../../middleware.dart'; -import '../config/config.dart' show OptionDefinition; import 'command_context.dart'; typedef CommandHandler = diff --git a/packages/config/lib/src/command/command_resolver.dart b/packages/config/lib/src/command/command_resolver.dart index afcdfeb..8255135 100644 --- a/packages/config/lib/src/command/command_resolver.dart +++ b/packages/config/lib/src/command/command_resolver.dart @@ -1,21 +1,19 @@ -import '../config/arg_parser/arg_parser.dart' +import '../../config.dart' show ArgParseResult, DoubleDashHandling, ParserSettings, scanAndParseCommands, - subcommandRequiredErrorPrefix; -import '../config/config.dart' - show + subcommandRequiredErrorPrefix, CommandDefinition, OptionDefinition, UsageException, - CommandUsageException; -import '../config/output_formatting.dart' show formatConfigError; + CommandUsageException, + formatConfigError; import 'abstract_command.dart'; +import 'action_option.dart'; import 'command_context.dart'; -import 'command_runner.dart' - show CommandRunner, specifiedActionOption, ActionOptionMixin; +import 'command_runner.dart' show CommandRunner; import 'context_provider.dart'; /// Interface for the command resolver, which resolves the configurations for @@ -166,7 +164,7 @@ class StandardCommandResolver } bool _acceptsPartialCommandLine(final CommandContext contexts) { - if (specifiedActionOption(contexts) + if (_specifiedActionOption(contexts) case final ActionOptionMixin actionOption) { return actionOption.acceptsPartialCommandLine; } @@ -197,3 +195,15 @@ class StandardCommandResolver } } } + +/// Returns the first of the action options that were specified on the command +/// line, or null if none. +ActionOptionMixin? _specifiedActionOption(final CommandContext contexts) { + CommandContext? context = contexts; + while (context != null) { + final actionOption = context.specifiedActionOptions().firstOrNull; + if (actionOption != null) return actionOption; + context = context.next; + } + return null; +} diff --git a/packages/config/lib/src/command/command_runner.dart b/packages/config/lib/src/command/command_runner.dart index eef092d..3471ef9 100644 --- a/packages/config/lib/src/command/command_runner.dart +++ b/packages/config/lib/src/command/command_runner.dart @@ -1,20 +1,20 @@ import 'dart:async' show Future, FutureOr; import 'dart:io' show Platform, stderr; -import '../config/arg_parser/arg_parser.dart' - show CommandAliasesDefinition, CommandDefinition, CommandUsageDefinition; -import '../config/config.dart' +import '../../config.dart' show - OptionDefinition, + CommandAliasesDefinition, + CommandDefinition, + CommandUsageDefinition, Configuration, + OptionDefinition, UsageException, ParsedArgs, ConfigOptionBase, FlagOption, MultiOption, ArgParseResult, - NewParsedArgs, - ValueSourceType; + NewParsedArgs; import 'abstract_command.dart'; import 'builtin_global_option.dart'; import 'command_context.dart'; @@ -399,7 +399,7 @@ class CommandRunner FutureOr _runNested( final CommandContext context, ) { - final actionOption = _specifiedActionOptions(context).firstOrNull; + final actionOption = context.specifiedActionOptions().firstOrNull; if (actionOption != null) { return context.command.runCommand( context, @@ -456,51 +456,6 @@ class CommandRunner /// by third-party completion engines such as Carapace. const String _completeRequestCommand = '__complete'; -/// ActionOptionMixin can be added to an option definition to make CommandRunner -/// run it as an "action option" when it is specified on the command line. -mixin ActionOptionMixin { - /// Whether this action option accepts a partial command line, - /// i.e. runs even if the command line is incomplete. - /// - /// True by default for action options. - /// - /// {@macro acceptsPartialCommandLine} - bool get acceptsPartialCommandLine => true; - - /// Runs this action option. - /// [context] is the context of the command that defined this action option. - FutureOr run( - final CommandContext context, - ); -} - -ActionOptionMixin? specifiedActionOption(final CommandContext contexts) { - CommandContext? context = contexts; - while (context != null) { - final actionOption = _specifiedActionOptions(context).firstOrNull; - if (actionOption != null) return actionOption; - context = context.next; - } - return null; -} - -List _specifiedActionOptions( - final CommandContext context, -) { - final allArgOptions = [ - ...context.config.optionsWhereSource( - (final ValueSourceType s) => s == ValueSourceType.arg, - ), - ...context.builtinConfig.optionsWhereSource( - (final ValueSourceType s) => s == ValueSourceType.arg, - ), - ]; - return allArgOptions - .map((final option) => option.option) - .whereType() - .toList(); -} - class OriginalCommandLine { final List args; diff --git a/packages/config/lib/src/command/commands.dart b/packages/config/lib/src/command/commands.dart index 9715ad3..22625b2 100644 --- a/packages/config/lib/src/command/commands.dart +++ b/packages/config/lib/src/command/commands.dart @@ -2,6 +2,7 @@ /// help, usage output and shell completion. library; +export 'action_option.dart'; export 'builtin_global_option.dart'; export 'command.dart'; export 'command_context.dart'; diff --git a/packages/config/lib/src/command/help_command.dart b/packages/config/lib/src/command/help_command.dart index 1b0ea9e..cd29c1d 100644 --- a/packages/config/lib/src/command/help_command.dart +++ b/packages/config/lib/src/command/help_command.dart @@ -2,7 +2,7 @@ import 'dart:async' show FutureOr; import 'package:collection/collection.dart'; -import '../config/config.dart' +import '../../config.dart' show OptionDefinition, CommandUsageDefinition, CommandAliasesDefinition; import 'abstract_command.dart' show AbstractCommand; import 'command.dart' show Command; diff --git a/packages/config/test/command/command_middleware_test.dart b/packages/config/test/command/command_middleware_test.dart index 73018a3..6478634 100644 --- a/packages/config/test/command/command_middleware_test.dart +++ b/packages/config/test/command/command_middleware_test.dart @@ -1426,6 +1426,48 @@ void main() { }); }); + group('Given an action option enum that is itself the action', () { + late List trace; + late CommandRunner runner; + + setUp(() { + trace = []; + _enumActionTrace = trace; + runner = CommandRunner( + 'tool', + 'Tools', + globalOptions: [_EnumVersionOption.version], + subcommands: [ + RecordingCommand( + name: 'project', + description: 'Manage projects', + trace: trace, + ), + ], + ); + }); + + tearDown(() { + _enumActionTrace = null; + }); + + group('when --version is passed', () { + late String? result; + + setUp(() async { + result = await runner.run(['--version', 'project']); + }); + + test('then that enum runs and the subcommand does not', () { + expect(trace, ['enum-version']); + }); + + test('then the runner returns the enum action result', () { + expect(result, 'enum-version'); + }); + }); + }); + group('Given an action option defined on a leaf command', () { late List trace; late CommandRunner runner; @@ -1496,7 +1538,26 @@ CommandMiddleware _traceMiddleware( }; } -class _VersionAction extends FlagOption with ActionOptionMixin { +List? _enumActionTrace; + +enum _EnumVersionOption with ActionOptionMixin { + version(FlagOption(argName: 'version', negatable: false)); + + const _EnumVersionOption(this.option); + + @override + final ConfigOptionBase option; + + @override + FutureOr run( + final CommandContext context, + ) { + _enumActionTrace?.add('enum-version'); + return 'enum-version' as R?; + } +} + +class _VersionAction extends FlagOption with ActionOptionMixin { _VersionAction(this.trace) : super(argName: 'version', negatable: false); final List trace;