From 2335cc9727310888f536e8ada484a084dc62d4f8 Mon Sep 17 00:00:00 2001
From: Eric Seidel <eric@shorebird.dev>
Date: Mon, 5 May 2025 10:25:23 -0700
Subject: [PATCH 1/2] fix: ArgResults.operator[] should throw Exception not
 Error

ArgResults.operator[] and ArgResults.option() would throw
ArgumentError instead of Exception when the user would fail to
pass all expected arguments.

Errors are only supposed to be thrown on programmer error so
changed to throw ArgParserException instead.

This is a breaking change!
---
 pkgs/args/lib/src/arg_results.dart      |  5 +++--
 pkgs/args/test/command_runner_test.dart |  3 ++-
 pkgs/args/test/parse_test.dart          | 15 +++++++++++----
 3 files changed, 16 insertions(+), 7 deletions(-)

diff --git a/pkgs/args/lib/src/arg_results.dart b/pkgs/args/lib/src/arg_results.dart
index 240867f48..523130789 100644
--- a/pkgs/args/lib/src/arg_results.dart
+++ b/pkgs/args/lib/src/arg_results.dart
@@ -5,6 +5,7 @@
 import 'dart:collection';
 
 import 'arg_parser.dart';
+import 'arg_parser_exception.dart';
 
 /// Creates a new [ArgResults].
 ///
@@ -71,7 +72,7 @@ class ArgResults {
 
     final option = _parser.options[name]!;
     if (option.mandatory && !_parsed.containsKey(name)) {
-      throw ArgumentError('Option $name is mandatory.');
+      throw ArgParserException('Option $name is mandatory.');
     }
 
     return option.valueOrDefault(_parsed[name]);
@@ -103,7 +104,7 @@ class ArgResults {
       throw ArgumentError('"$name" is a multi-option.');
     }
     if (option.mandatory && !_parsed.containsKey(name)) {
-      throw ArgumentError('Option $name is mandatory.');
+      throw ArgParserException('Option $name is mandatory.');
     }
     return option.valueOrDefault(_parsed[name]) as String?;
   }
diff --git a/pkgs/args/test/command_runner_test.dart b/pkgs/args/test/command_runner_test.dart
index b9fde8ae3..3d9c75902 100644
--- a/pkgs/args/test/command_runner_test.dart
+++ b/pkgs/args/test/command_runner_test.dart
@@ -2,6 +2,7 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
+import 'package:args/args.dart';
 import 'package:args/command_runner.dart';
 import 'package:test/test.dart';
 
@@ -736,7 +737,7 @@ Run "test help" to see global options.'''));
     runner.addCommand(subcommand);
     expect(
         () => runner.run([subcommand.name]),
-        throwsA(isA<ArgumentError>().having((e) => e.message, 'message',
+        throwsA(isA<ArgParserException>().having((e) => e.message, 'message',
             contains('Option mandatory-option is mandatory'))));
     expect(await runner.run([subcommand.name, '--mandatory-option', 'foo']),
         'foo');
diff --git a/pkgs/args/test/parse_test.dart b/pkgs/args/test/parse_test.dart
index eb2f3ae2d..7b235fe99 100644
--- a/pkgs/args/test/parse_test.dart
+++ b/pkgs/args/test/parse_test.dart
@@ -595,7 +595,10 @@ void main() {
           var parser = ArgParser();
           parser.addOption('username', mandatory: true);
           var results = parser.parse([]);
-          expect(() => results['username'], throwsA(isA<ArgumentError>()));
+          expect(
+              () => results['username'],
+              throwsA(isA<ArgParserException>().having((e) => e.message,
+                  'message', 'Option username is mandatory.')));
         });
 
         test('throw if no mandatory args', () {
@@ -604,7 +607,10 @@ void main() {
           parser.addOption('username', mandatory: true);
           var results = parser.parse(['--test', 'test']);
           expect(results['test'], equals('test'));
-          expect(() => results['username'], throwsA(isA<ArgumentError>()));
+          expect(
+              () => results['username'],
+              throwsA(isA<ArgParserException>().having((e) => e.message,
+                  'message', 'Option username is mandatory.')));
         });
 
         test('parse successfully', () {
@@ -620,8 +626,9 @@ void main() {
           parser.addOption('test', mandatory: true);
           var results = parser.parse(['-h']);
           expect(results['help'], true);
-          expect(() => results['test'], throwsA(isA<ArgumentError>()));
-          expect(() => results.option('test'), throwsA(isA<ArgumentError>()));
+          expect(() => results['test'], throwsA(isA<ArgParserException>()));
+          expect(
+              () => results.option('test'), throwsA(isA<ArgParserException>()));
         });
       });
     });

From d7258ce6ea95499a10c7ccb762c350ecc4d92486 Mon Sep 17 00:00:00 2001
From: Eric Seidel <eric@shorebird.dev>
Date: Mon, 5 May 2025 10:29:57 -0700
Subject: [PATCH 2/2] chore: add Changelog entry

---
 pkgs/args/CHANGELOG.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/pkgs/args/CHANGELOG.md b/pkgs/args/CHANGELOG.md
index f712877b5..498295840 100644
--- a/pkgs/args/CHANGELOG.md
+++ b/pkgs/args/CHANGELOG.md
@@ -1,3 +1,8 @@
+## 3.0.0
+
+* Breaking: ArgResults.operator[] and ArgResults.option now correctly throw
+  Exceptions rather than Errors when defined arguments are missing values.
+
 ## 2.7.0
 
 * Remove sorting of the `allowedHelp` argument in usage output. Ordering will