diff --git a/packages/config/lib/src/command/command_runner.dart b/packages/config/lib/src/command/command_runner.dart index 96c425a..eef092d 100644 --- a/packages/config/lib/src/command/command_runner.dart +++ b/packages/config/lib/src/command/command_runner.dart @@ -31,12 +31,13 @@ import 'usage_output.dart'; /// /// Returns the result of the nested middleware chain for the commands on /// the command line. Each ancestor's middleware wraps the commands that -/// follow it. Only the last command's [run] is invoked. +/// follow it. Only the last command's [run] (or the action option's, if +/// present) is invoked. /// /// T is the return type of the run methods of this runner and the commands. /// [CommandRunner.run] returns the result of the nested middleware chain. /// When each middleware returns the result of its next handler, that is the -/// result of the last command on the command line. +/// result of the last command on the command line, or of the action option. /// This means that T must match across the runner and all its commands. /// Using int as T can be sensible in order to return the exit code that the /// command executable should return. @@ -213,9 +214,13 @@ class CommandRunner /// middleware returns the result of its next handler, the result is that /// of the last command. /// - /// When `--help`, `-h`, or a `help` command is present on a command - /// line, prints usage for the last command and returns `null` without - /// running any command. + /// An action option ends that chain at the command that defined it. + /// Middleware runs up through that command, and the option runs instead of + /// any command. + /// + /// When `--help` or `-h` is present, prints usage for the last command + /// 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: /// ```dart @@ -380,8 +385,8 @@ class CommandRunner ); } - /// Runs the command line, i.e. the middlewares of the commands on the command - /// line and run the tail command. + /// Runs the command line: the middlewares of the commands on the command + /// line, then the tail command or an action option. FutureOr runCommandLine(final CommandContext contexts) { return _runNested(contexts); } @@ -390,26 +395,31 @@ class CommandRunner /// /// The first command's middleware is the outermost span. Each following /// command's middleware runs inside the previous command's middleware. - /// Only the last command's [run] is invoked. + /// Only the last command's [run] or the action option's [run] is invoked. FutureOr _runNested( final CommandContext context, ) { - final next = context.next == null - ? null - : (final CommandContext forwarded) { - // (forwarded context may have been replaced by a middleware) - final next = forwarded.next; - if (next == null) { - throw StateError( - '${forwarded.command.name} has no following command.', - ); - } - return _runNested(next); - }; - final actionOption = _specifiedActionOptions(context).firstOrNull; if (actionOption != null) { - return actionOption.run(context); + return context.command.runCommand( + context, + runNextCommand: (final forwarded) => actionOption.run(forwarded), + ); + } + + if (context.next == null) { + return context.command.runCommand(context); + } + + FutureOr next(final CommandContext forwarded) { + // (forwarded context may have been replaced by a middleware) + final next = forwarded.next; + if (next == null) { + throw StateError( + '${forwarded.command.name} has no following command.', + ); + } + return _runNested(next); } return context.command.runCommand(context, runNextCommand: next); @@ -458,7 +468,6 @@ mixin ActionOptionMixin { 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/test/command/command_middleware_test.dart b/packages/config/test/command/command_middleware_test.dart index 3957795..73018a3 100644 --- a/packages/config/test/command/command_middleware_test.dart +++ b/packages/config/test/command/command_middleware_test.dart @@ -1,3 +1,5 @@ +import 'dart:async' show FutureOr; + import 'package:config/command.dart'; import 'package:config/config.dart'; import 'package:test/test.dart'; @@ -1322,6 +1324,190 @@ void main() { }); }, ); + + group('Given an action option defined on the runner', () { + late List trace; + late CommandRunner runner; + + setUp(() { + trace = []; + runner = CommandRunner( + 'tool', + 'Tools', + globalOptions: [_VersionAction(trace)], + middlewares: [_traceMiddleware(trace, 'root')], + subcommands: [ + RecordingCommand( + name: 'project', + description: 'Manage projects', + trace: trace, + middlewares: [_traceMiddleware(trace, 'project')], + ), + ], + ); + }); + + group('when --version precedes a subcommand', () { + late String? result; + + setUp(() async { + result = await runner.run(['--version', 'project']); + }); + + test( + 'then middleware runs through the runner ' + 'and the subcommand does not run', + () { + expect(trace, [ + 'root-before', + 'version', + 'root-after', + ]); + }, + ); + + test('then the runner returns the wrapped action result', () { + expect(result, 'root:version'); + }); + }); + }); + + group('Given an action option defined on a branch command', () { + late List trace; + late CommandRunner runner; + + setUp(() { + trace = []; + final list = RecordingCommand( + name: 'list', + description: 'List projects', + trace: trace, + middlewares: [_traceMiddleware(trace, 'list')], + ); + final project = CommandImpl.branch( + name: 'project', + description: 'Manage projects', + persistentOptions: [_VersionAction(trace)], + middlewares: [_traceMiddleware(trace, 'project')], + subcommands: [list], + ); + runner = CommandRunner( + 'tool', + 'Tools', + middlewares: [_traceMiddleware(trace, 'root')], + subcommands: [project], + ); + }); + + group('when --version follows a nested subcommand', () { + late String? result; + + setUp(() async { + result = await runner.run(['project', 'list', '--version']); + }); + + test( + 'then middleware runs through the branch ' + 'and the nested command does not run', + () { + expect(trace, [ + 'root-before', + 'project-before', + 'version', + 'project-after', + 'root-after', + ]); + }, + ); + + test('then the runner returns the wrapped action result', () { + expect(result, 'root:project:version'); + }); + }); + }); + + group('Given an action option defined on a leaf command', () { + late List trace; + late CommandRunner runner; + + setUp(() { + trace = []; + final list = RecordingCommand( + name: 'list', + description: 'List projects', + trace: trace, + options: [_VersionAction(trace)], + middlewares: [_traceMiddleware(trace, 'list')], + ); + final project = RecordingCommand( + name: 'project', + description: 'Manage projects', + trace: trace, + middlewares: [_traceMiddleware(trace, 'project')], + subcommands: [list], + ); + runner = CommandRunner( + 'tool', + 'Tools', + middlewares: [_traceMiddleware(trace, 'root')], + subcommands: [project], + ); + }); + + group('when --version is passed to that command', () { + late String? result; + + setUp(() async { + result = await runner.run(['project', 'list', '--version']); + }); + + test( + 'then middleware runs through the leaf ' + 'and the leaf command does not run', + () { + expect(trace, [ + 'root-before', + 'project-before', + 'list-before', + 'version', + 'list-after', + 'project-after', + 'root-after', + ]); + }, + ); + + test('then the runner returns the wrapped action result', () { + expect(result, 'root:project:list:version'); + }); + }); + }); +} + +CommandMiddleware _traceMiddleware( + final List trace, + final String label, +) { + return (final next) => (final context) { + trace.add('$label-before'); + final result = next(context); + trace.add('$label-after'); + return '$label:$result'; + }; +} + +class _VersionAction extends FlagOption with ActionOptionMixin { + _VersionAction(this.trace) : super(argName: 'version', negatable: false); + + final List trace; + + @override + FutureOr run( + final CommandContext context, + ) { + trace.add('version'); + return 'version' as R?; + } } class _MarkerProvider implements ContextProvider { diff --git a/packages/config/test/command/help_command_test.dart b/packages/config/test/command/help_command_test.dart index cad8360..c0f0eba 100644 --- a/packages/config/test/command/help_command_test.dart +++ b/packages/config/test/command/help_command_test.dart @@ -928,9 +928,13 @@ void main() { }, ); - test('when --help is passed then middleware does not run', () { - expect(trace, isEmpty); - }); + test( + 'when --help is passed ' + 'then the runner middleware runs', + () { + expect(trace, ['root']); + }, + ); }); group('Given middleware on the runner and its subcommands', () { @@ -991,9 +995,9 @@ void main() { test( 'when --help follows the subcommand ' - 'then no middleware runs', + 'then only the runner middleware runs', () { - expect(trace, isEmpty); + expect(trace, ['root-middleware']); }, ); });