Make it possible to add default subcommand

Make it possible to add default subcommand (designated by an empty
name) for a branch command: default subcommand will be run when no other
subcommand is selected. This allows creating command line interfaces
where both `program command` and `program command subcommand` are
runnable.

Fixes #103

Author: mraleph

pkgs/args/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2.8.0-dev
+
+* Make it possible to add default subcommand (designated by an empty name)
+  for a branch command: default subcommand will be run when no other
+  subcommand is selected. This allows creating command line interfaces where
+  both `program command` and `program command subcommand` are runnable.
+  (Fixes #103).
+
 ## 2.7.0
 
 * Remove sorting of the `allowedHelp` argument in usage output. Ordering will

pkgs/args/lib/command_runner.dart

@@ -33,7 +33,15 @@ class CommandRunner<T> {
   ///
   /// Defaults to `"$executableName <command> arguments`". Subclasses can
   /// override this for a more specific template.
-  String get invocation => '$executableName <command> [arguments]';
+  String get invocation {
+    var command = '<command>';
+
+    if (commands.containsKey(Command.defaultSubcommand)) {
+      command = '[$command]';
+    }
+
+    return '$executableName $command [arguments]';
+  }
 
   /// Generates a string displaying usage information for the executable.
   ///
@@ -51,11 +59,24 @@ class CommandRunner<T> {
   String get _usageWithoutDescription {
     var usagePrefix = 'Usage:';
     var buffer = StringBuffer();
+
+    if (commands[Command.defaultSubcommand] case final defaultCommand?) {
+      final cmdLine = '$executableName [arguments]';
+      buffer.writeln(
+        '$usagePrefix ${_wrap(cmdLine, hangingIndent: usagePrefix.length)}\n',
+      );
+      buffer.writeln(defaultCommand.description);
+      buffer.writeln();
+      buffer.writeln('${defaultCommand.argParser.usage}\n');
+    }
+
+    final cmdLine = '$executableName <command> [arguments]';
     buffer.writeln(
-      '$usagePrefix ${_wrap(invocation, hangingIndent: usagePrefix.length)}\n',
+      '$usagePrefix ${_wrap(cmdLine, hangingIndent: usagePrefix.length)}\n',
     );
     buffer.writeln(_wrap('Global options:'));
     buffer.writeln('${argParser.usage}\n');
+
     buffer.writeln(
       '${_getCommandUsage(_commands, lineLength: argParser.usageLineLength)}\n',
     );
@@ -205,8 +226,17 @@ class CommandRunner<T> {
 
     // Make sure there aren't unexpected arguments.
     if (!command!.takesArguments && argResults.rest.isNotEmpty) {
-      command.usageException(
-          'Command "${argResults.name}" does not take any arguments.');
+      if (argResults.name == Command.defaultSubcommand) {
+        if (command.parent case final parent?) {
+          parent.usageException(
+              'Command "${parent.name}" does not take any arguments.');
+        } else {
+          command.usageException('Command does not take any arguments.');
+        }
+      } else {
+        command.usageException(
+            'Command "${argResults.name}" does not take any arguments.');
+      }
     }
 
     return (await command.run()) as T?;
@@ -258,8 +288,17 @@ class CommandRunner<T> {
 ///
 /// A command with subcommands is known as a "branch command" and cannot be run
 /// itself. It should call [addSubcommand] (often from the constructor) to
-/// register subcommands.
+/// register subcommands. If a registered subcommand has an empty (`''`) name
+/// or an alias then it will be used as a default subcommand and will be
+/// selected when no other subcommand matches.
 abstract class Command<T> {
+  /// Marker name used to denote default subcommands.
+  ///
+  /// Default subcommand triggers when no other subcommand matches then can
+  /// be used to define command line interfaces where both `program command`
+  /// and `program command subcommand` perform meaningful actions.
+  static const String defaultSubcommand = '';
+
   /// The name of this command.
   String get name;
 
@@ -281,16 +320,24 @@ abstract class Command<T> {
   /// A single-line template for how to invoke this command (e.g. `"pub get
   /// `package`"`).
   String get invocation {
-    var parents = [name];
+    var invocation = _invocationChain;
+    if (_subcommands.containsKey(defaultSubcommand)) {
+      return '$invocation [<subcommand>] [arguments]';
+    } else if (_subcommands.isNotEmpty) {
+      return '$invocation <subcommand> [arguments]';
+    } else {
+      return '$invocation [arguments]';
+    }
+  }
+
+  String get _invocationChain {
+    var parents = [if (name != defaultSubcommand) name];
     for (var command = parent; command != null; command = command.parent) {
       parents.add(command.name);
     }
     parents.add(runner!.executableName);
 
-    var invocation = parents.reversed.join(' ');
-    return _subcommands.isNotEmpty
-        ? '$invocation <subcommand> [arguments]'
-        : '$invocation [arguments]';
+    return parents.reversed.join(' ');
   }
 
   /// The command's parent command, if this is a subcommand.
@@ -356,18 +403,35 @@ abstract class Command<T> {
   String get _usageWithoutDescription {
     var length = argParser.usageLineLength;
     var usagePrefix = 'Usage: ';
-    var buffer = StringBuffer()
-      ..writeln(
-          usagePrefix + _wrap(invocation, hangingIndent: usagePrefix.length))
-      ..writeln(argParser.usage);
+    var buffer = StringBuffer();
 
-    if (_subcommands.isNotEmpty) {
+    if (_subcommands[Command.defaultSubcommand] case final defaultSubcommand?) {
+      final invocationChain = _invocationChain;
+      buffer.writeln(usagePrefix +
+          _wrap('$invocationChain [arguments]',
+              hangingIndent: usagePrefix.length));
+      buffer.writeln(defaultSubcommand.argParser.usage);
       buffer.writeln();
-      buffer.writeln(_getCommandUsage(
+      buffer.writeln(usagePrefix +
+          _wrap('$invocationChain <subcommand> [arguments]',
+              hangingIndent: usagePrefix.length));
+    } else {
+      buffer.writeln(
+          usagePrefix + _wrap(invocation, hangingIndent: usagePrefix.length));
+      buffer.writeln(argParser.usage);
+    }
+
+    if (_subcommands.isNotEmpty) {
+      final commandUsage = _getCommandUsage(
         _subcommands,
         isSubcommand: true,
         lineLength: length,
-      ));
+      );
+
+      if (commandUsage != '') {
+        buffer.writeln();
+        buffer.writeln(commandUsage);
+      }
     }
 
     buffer.writeln();
@@ -447,6 +511,10 @@ abstract class Command<T> {
 
   /// Adds [Command] as a subcommand of this.
   void addSubcommand(Command<T> command) {
+    if (name == defaultSubcommand) {
+      throw StateError('default subcommand must be a leaf command');
+    }
+
     var names = [command.name, ...command.aliases];
     for (var name in names) {
       _subcommands[name] = command;
@@ -472,9 +540,15 @@ abstract class Command<T> {
 /// "subcommands".
 String _getCommandUsage(Map<String, Command> commands,
     {bool isSubcommand = false, int? lineLength}) {
-  // Don't include aliases.
-  var names =
-      commands.keys.where((name) => !commands[name]!.aliases.contains(name));
+  // Don't include aliases and the default subcommand name (which is just an
+  // empty string).
+  var names = commands.keys.where((name) =>
+      name != Command.defaultSubcommand &&
+      !commands[name]!.aliases.contains(name));
+
+  if (names.isEmpty) {
+    return '';
+  }
 
   // Filter out hidden ones, unless they are all hidden.
   var visible = names.where((name) => !commands[name]!.hidden);

pkgs/args/lib/src/parser.dart

@@ -4,6 +4,7 @@
 
 import 'dart:collection';
 
+import '../command_runner.dart';
 import 'arg_parser.dart';
 import 'arg_parser_exception.dart';
 import 'arg_results.dart';
@@ -50,6 +51,7 @@ class Parser {
     }
 
     ArgResults? commandResults;
+    (String, ArgParser)? command;
 
     // Parse the args.
     while (_args.isNotEmpty) {
@@ -61,26 +63,12 @@ class Parser {
 
       // Try to parse the current argument as a command. This happens before
       // options so that commands can have option-like names.
-      var command = _grammar.commands[_current];
-      if (command != null) {
-        _validate(_rest.isEmpty, 'Cannot specify arguments before a command.',
-            _current);
-        var commandName = _args.removeFirst();
-        var commandParser = Parser(commandName, command, _args, this, _rest);
-
-        try {
-          commandResults = commandParser.parse();
-        } on ArgParserException catch (error) {
-          throw ArgParserException(
-              error.message,
-              [commandName, ...error.commands],
-              error.argumentName,
-              error.source,
-              error.offset);
-        }
-
-        // All remaining arguments were passed to command so clear them here.
-        _rest.clear();
+      if (_grammar.commands[_current] case final parser?) {
+        command = (_args.removeFirst(), parser);
+        break;
+      } else if (_grammar.commands[Command.defaultSubcommand]
+          case final parser?) {
+        command = (Command.defaultSubcommand, parser);
         break;
       }
 
@@ -96,6 +84,32 @@ class Parser {
       _rest.add(_args.removeFirst());
     }
 
+    if (command == null && _rest.isEmpty) {
+      if (_grammar.commands[Command.defaultSubcommand] case final parser?) {
+        command = (Command.defaultSubcommand, parser);
+      }
+    }
+
+    if (command case (final commandName, final parser)?) {
+      _validate(_rest.isEmpty, 'Cannot specify arguments before a command.',
+          commandName);
+      var commandParser = Parser(commandName, parser, _args, this, _rest);
+
+      try {
+        commandResults = commandParser.parse();
+      } on ArgParserException catch (error) {
+        throw ArgParserException(
+            error.message,
+            [commandName, ...error.commands],
+            error.argumentName,
+            error.source,
+            error.offset);
+      }
+
+      // All remaining arguments were passed to command so clear them here.
+      _rest.clear();
+    }
+
     // Check if mandatory and invoke existing callbacks.
     _grammar.options.forEach((name, option) {
       var parsedOption = _results[name];

pkgs/args/pubspec.yaml

@@ -1,5 +1,5 @@
 name: args
-version: 2.7.0
+version: 2.8.0-dev
 description: >-
   Library for defining parsers for parsing raw command-line arguments into a set
   of options and values using GNU and POSIX style options.