Introduce new typed ArgResults flag(String), option(String), an…

…d `multiOption(String)` methods (#248)

* introduce types methods to ArgResults

* rename methods

* updates

* review feedback

* reduce PR diffs

* reduce PR diffs

* review feedback

* Update arg_results.dart

CHANGELOG.md

@@ -1,3 +1,8 @@
+## 2.5.0-wip
+
+* Introduce new typed `ArgResults` `flag(String)`, `option(String)`, and
+  `multiOption(String)` methods.
+
 ## 2.4.2
 
 * Change the validation of `mandatory` options; they now perform validation when

README.md

@@ -111,8 +111,8 @@ parser.addOption('mode');
 parser.addFlag('verbose', defaultsTo: true);
 var results = parser.parse(['--mode', 'debug', 'something', 'else']);
 
-print(results['mode']); // debug
-print(results['verbose']); // true
+print(results.option('mode')); // debug
+print(results.flag('verbose')); // true
 ```
 
 By default, the `parse()` method allows additional flags and options to be
@@ -187,7 +187,7 @@ overriding earlier ones; for example:
 var parser = ArgParser();
 parser.addOption('mode');
 var results = parser.parse(['--mode', 'on', '--mode', 'off']);
-print(results['mode']); // prints 'off'
+print(results.option('mode')); // prints 'off'
 ```
 
 Multiple values can be parsed with `addMultiOption()`. With this method, an
@@ -198,7 +198,7 @@ values:
 var parser = ArgParser();
 parser.addMultiOption('mode');
 var results = parser.parse(['--mode', 'on', '--mode', 'off']);
-print(results['mode']); // prints '[on, off]'
+print(results.multiOption('mode')); // prints '[on, off]'
 ```
 
 By default, values for a multi-valued option may also be separated with commas:
@@ -207,7 +207,7 @@ By default, values for a multi-valued option may also be separated with commas:
 var parser = ArgParser();
 parser.addMultiOption('mode');
 var results = parser.parse(['--mode', 'on,off']);
-print(results['mode']); // prints '[on, off]'
+print(results.multiOption('mode')); // prints '[on, off]'
 ```
 
 This can be disabled by passing `splitCommas: false`.
@@ -326,7 +326,7 @@ class CommitCommand extends Command {
   void run() {
     // [argResults] is set before [run()] is called and contains the flags/options
     // passed to this command.
-    print(argResults['all']);
+    print(argResults.flag('all'));
   }
 }
 ```

example/command_runner/draw.dart

@@ -33,8 +33,8 @@ class SquareCommand extends Command<String> {
 
   @override
   FutureOr<String>? run() {
-    final size = int.parse(argResults?['size'] as String? ?? '20');
-    final char = (globalResults?['char'] as String?)?[0] ?? '#';
+    final size = int.parse(argResults?.option('size') ?? '20');
+    final char = globalResults?.option('char')?[0] ?? '#';
     return draw(size, size, char, (x, y) => true);
   }
 }
@@ -55,8 +55,8 @@ class CircleCommand extends Command<String> {
 
   @override
   FutureOr<String>? run() {
-    final size = 2 * int.parse(argResults?['radius'] as String? ?? '10');
-    final char = (globalResults?['char'] as String?)?[0] ?? '#';
+    final size = 2 * int.parse(argResults?.option('radius') ?? '10');
+    final char = globalResults?.option('char')?[0] ?? '#';
     return draw(size, size, char, (x, y) => x * x + y * y < 1);
   }
 }
@@ -93,8 +93,8 @@ class EquilateralTriangleCommand extends Command<String> {
 
   @override
   FutureOr<String>? run() {
-    final size = int.parse(argResults?['size'] as String? ?? '20');
-    final char = (globalResults?['char'] as String?)?[0] ?? '#';
+    final size = int.parse(argResults?.option('size') ?? '20');
+    final char = globalResults?.option('char')?[0] ?? '#';
     return drawTriangle(size, size * sqrt(3) ~/ 2, char);
   }
 }
@@ -116,9 +116,9 @@ class IsoscelesTriangleCommand extends Command<String> {
 
   @override
   FutureOr<String>? run() {
-    final width = int.parse(argResults?['width'] as String? ?? '50');
-    final height = int.parse(argResults?['height'] as String? ?? '10');
-    final char = (globalResults?['char'] as String?)?[0] ?? '#';
+    final width = int.parse(argResults?.option('width') ?? '50');
+    final height = int.parse(argResults?.option('height') ?? '10');
+    final char = globalResults?.option('char')?[0] ?? '#';
     return drawTriangle(width, height, char);
   }
 }

lib/command_runner.dart

@@ -192,13 +192,13 @@ class CommandRunner<T> {
       commands = command._subcommands as Map<String, Command<T>>;
       commandString += ' ${argResults.name}';
 
-      if (argResults.options.contains('help') && (argResults['help'] as bool)) {
+      if (argResults.options.contains('help') && argResults.flag('help')) {
         command.printUsage();
         return null;
       }
     }
 
-    if (topLevelResults['help'] as bool) {
+    if (topLevelResults.flag('help')) {
       command!.printUsage();
       return null;
     }

lib/src/arg_results.dart

@@ -21,7 +21,7 @@ ArgResults newArgResults(
 }
 
 /// The results of parsing a series of command line arguments using
-/// [ArgParser.parse()].
+/// [ArgParser.parse].
 ///
 /// Includes the parsed options and any remaining unparsed command line
 /// arguments.
@@ -57,9 +57,13 @@ class ArgResults {
       : rest = UnmodifiableListView(rest),
         arguments = UnmodifiableListView(arguments);
 
-  /// Returns the parsed ore default command-line option named [name].
+  /// Returns the parsed or default command-line option named [name].
   ///
   /// [name] must be a valid option name in the parser.
+  ///
+  /// > [!Note]
+  /// > Callers should prefer using the more strongly typed methods - [flag] for
+  /// > flags, [option] for options, and [multiOption] for multi-options.
   dynamic operator [](String name) {
     if (!_parser.options.containsKey(name)) {
       throw ArgumentError('Could not find an option named "$name".');
@@ -73,6 +77,48 @@ class ArgResults {
     return option.valueOrDefault(_parsed[name]);
   }
 
+  /// Returns the parsed or default command-line flag named [name].
+  ///
+  /// [name] must be a valid flag name in the parser.
+  bool flag(String name) {
+    var option = _parser.options[name];
+    if (option == null) {
+      throw ArgumentError('Could not find an option named "$name".');
+    }
+    if (!option.isFlag) {
+      throw ArgumentError('"$name" is not a flag.');
+    }
+    return option.valueOrDefault(_parsed[name]) as bool;
+  }
+
+  /// Returns the parsed or default command-line option named [name].
+  ///
+  /// [name] must be a valid option name in the parser.
+  String? option(String name) {
+    var option = _parser.options[name];
+    if (option == null) {
+      throw ArgumentError('Could not find an option named "$name".');
+    }
+    if (!option.isSingle) {
+      throw ArgumentError('"$name" is a multi-option.');
+    }
+    return option.valueOrDefault(_parsed[name]) as String?;
+  }
+
+  /// Returns the list of parsed (or default) command-line options for [name].
+  ///
+  /// [name] must be a valid option name in the parser.
+  List<String> multiOption(String name) {
+    var option = _parser.options[name];
+    if (option == null) {
+      throw ArgumentError('Could not find an option named "$name".');
+    }
+    if (!option.isMultiple) {
+      throw ArgumentError('"$name" is not a multi-option.');
+    }
+    return option.valueOrDefault(_parsed[name]) as List<String>;
+  }
+
   /// The names of the available options.
   ///
   /// Includes the options whose values were parsed or that have defaults.

pubspec.yaml

@@ -1,8 +1,8 @@
 name: args
-version: 2.4.2
+version: 2.5.0-wip
 description: >-
- Library for defining parsers for parsing raw command-line arguments into a set
- of options and values using GNU and POSIX style options.
+  Library for defining parsers for parsing raw command-line arguments into a set
+  of options and values using GNU and POSIX style options.
 repository: https://github.com/dart-lang/args
 
 topics: