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
55 changes: 32 additions & 23 deletions packages/config/lib/src/command/command_runner.dart
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -213,9 +214,13 @@ class CommandRunner<O extends OptionDefinition, T>
/// 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
Expand Down Expand Up @@ -380,8 +385,8 @@ class CommandRunner<O extends OptionDefinition, T>
);
}

/// 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<T?> runCommandLine(final CommandContext<O, T> contexts) {
return _runNested(contexts);
}
Expand All @@ -390,26 +395,31 @@ class CommandRunner<O extends OptionDefinition, T>
///
/// 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<T?> _runNested(
final CommandContext<OptionDefinition, T> context,
) {
final next = context.next == null
? null
: (final CommandContext<OptionDefinition, T> 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<T?> next(final CommandContext<OptionDefinition, T> 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);
Expand Down Expand Up @@ -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<R?> run<O extends OptionDefinition, R>(
final CommandContext<O, R> context,
Expand Down
186 changes: 186 additions & 0 deletions packages/config/test/command/command_middleware_test.dart
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
import 'dart:async' show FutureOr;

import 'package:config/command.dart';
import 'package:config/config.dart';
import 'package:test/test.dart';
Expand Down Expand Up @@ -1322,6 +1324,190 @@ void main() {
});
},
);

group('Given an action option defined on the runner', () {
late List<String> trace;
late CommandRunner<OptionDefinition, String> runner;

setUp(() {
trace = [];
runner = CommandRunner<OptionDefinition, String>(
'tool',
'Tools',
globalOptions: [_VersionAction(trace)],
middlewares: [_traceMiddleware(trace, 'root')],
subcommands: [
RecordingCommand<OptionDefinition>(
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<String> trace;
late CommandRunner<OptionDefinition, String> runner;

setUp(() {
trace = [];
final list = RecordingCommand<OptionDefinition>(
name: 'list',
description: 'List projects',
trace: trace,
middlewares: [_traceMiddleware(trace, 'list')],
);
final project = CommandImpl.branch<OptionDefinition, String>(
name: 'project',
description: 'Manage projects',
persistentOptions: [_VersionAction(trace)],
middlewares: [_traceMiddleware(trace, 'project')],
subcommands: [list],
);
runner = CommandRunner<OptionDefinition, String>(
'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<String> trace;
late CommandRunner<OptionDefinition, String> runner;

setUp(() {
trace = [];
final list = RecordingCommand<OptionDefinition>(
name: 'list',
description: 'List projects',
trace: trace,
options: [_VersionAction(trace)],
middlewares: [_traceMiddleware(trace, 'list')],
);
final project = RecordingCommand<OptionDefinition>(
name: 'project',
description: 'Manage projects',
trace: trace,
middlewares: [_traceMiddleware(trace, 'project')],
subcommands: [list],
);
runner = CommandRunner<OptionDefinition, String>(
'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<O, String> _traceMiddleware<O extends OptionDefinition>(
final List<String> 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<String> trace;

@override
FutureOr<R?> run<O extends OptionDefinition, R>(
final CommandContext<O, R> context,
) {
trace.add('version');
return 'version' as R?;
}
}

class _MarkerProvider implements ContextProvider {
Expand Down
14 changes: 9 additions & 5 deletions packages/config/test/command/help_command_test.dart
Original file line number Diff line number Diff line change
Expand Up @@ -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', () {
Expand Down Expand Up @@ -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']);
},
);
});
Expand Down
Loading