Add option hideNegatable to ArgParser.flag()

CHANGELOG.md

@@ -1,8 +1,10 @@
-## 2.6.0-wip
+## 2.6.0
 
 * Added source argument when throwing a `ArgParserException`.
 * Fix inconsistent `FormatException` messages
 * Require Dart 3.3
+* Added option `hideNegatedUsage` to `ArgParser.flag()` allowing a flag to be
+  `negatable` without showing it in the usage text.
 
 ## 2.5.0
 

lib/src/allow_anything_parser.dart

@@ -36,6 +36,7 @@ class AllowAnythingParser implements ArgParser {
       bool negatable = true,
       void Function(bool)? callback,
       bool hide = false,
+      bool hideNegatedUsage = false,
       List<String> aliases = const []}) {
     throw UnsupportedError(
         "ArgParser.allowAnything().addFlag() isn't supported.");

lib/src/arg_parser.dart

@@ -119,6 +119,10 @@ class ArgParser {
   ///
   /// If [hide] is `true`, this option won't be included in [usage].
   ///
+  /// If [hideNegatedUsage] is `true`, the fact that this flag can be negated will
+  /// not be documented in [usage].
+  /// It is an error for [hideNegatedUsage] to be `true` if [negatable] is `false`.
+  ///
   /// If [aliases] is provided, these are used as aliases for [name]. These
   /// aliases will not appear as keys in the [options] map.
   ///
@@ -133,6 +137,7 @@ class ArgParser {
       bool negatable = true,
       void Function(bool)? callback,
       bool hide = false,
+      bool hideNegatedUsage = false,
       List<String> aliases = const []}) {
     _addOption(
         name,
@@ -146,6 +151,7 @@ class ArgParser {
         OptionType.flag,
         negatable: negatable,
         hide: hide,
+        hideNegatedUsage: hideNegatedUsage,
         aliases: aliases);
   }
 
@@ -285,6 +291,7 @@ class ArgParser {
       bool? splitCommas,
       bool mandatory = false,
       bool hide = false,
+      bool hideNegatedUsage = false,
       List<String> aliases = const []}) {
     var allNames = [name, ...aliases];
     if (allNames.any((name) => findByNameOrAlias(name) != null)) {
@@ -306,12 +313,19 @@ class ArgParser {
           'The option $name cannot be mandatory and have a default value.');
     }
 
+    if (!negatable && hideNegatedUsage) {
+      throw ArgumentError(
+        'The option $name cannot have `hideNegatedUsage` without being negatable.',
+      );
+    }
+
     var option = newOption(name, abbr, help, valueHelp, allowed, allowedHelp,
         defaultsTo, callback, type,
         negatable: negatable,
         splitCommas: splitCommas,
         mandatory: mandatory,
         hide: hide,
+        hideNegatedUsage: hideNegatedUsage,
         aliases: aliases);
     _options[name] = option;
     _optionsAndSeparators.add(option);

lib/src/option.dart

@@ -20,13 +20,15 @@ Option newOption(
     bool? splitCommas,
     bool mandatory = false,
     bool hide = false,
+    bool hideNegatedUsage = false,
     List<String> aliases = const []}) {
   return Option._(name, abbr, help, valueHelp, allowed, allowedHelp, defaultsTo,
       callback, type,
       negatable: negatable,
       splitCommas: splitCommas,
       mandatory: mandatory,
       hide: hide,
+      hideNegatedUsage: hideNegatedUsage,
       aliases: aliases);
 }
 
@@ -66,6 +68,11 @@ class Option {
   /// This is `null` unless [type] is [OptionType.flag].
   final bool? negatable;
 
+  /// Whether to document that this flag is [negatable].
+  ///
+  /// This is `null` unless [type] is [OptionType.flag].
+  final bool? hideNegatedUsage;
+
   /// The callback to invoke with the option's value when the option is parsed.
   final Function? callback;
 
@@ -108,6 +115,7 @@ class Option {
       bool? splitCommas,
       this.mandatory = false,
       this.hide = false,
+      this.hideNegatedUsage,
       this.aliases = const []})
       : allowed = allowed == null ? null : List.unmodifiable(allowed),
         allowedHelp =

lib/src/usage.dart

@@ -121,7 +121,7 @@ class _Usage {
 
   String _longOption(Option option) {
     String result;
-    if (option.negatable!) {
+    if (option.negatable! && !option.hideNegatedUsage!) {
       result = '--[no-]${option.name}';
     } else {
       result = '--${option.name}';

pubspec.yaml

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

test/usage_test.dart

@@ -16,6 +16,16 @@ void main() {
           ''');
     });
 
+    test('negatable flags with hideNegatedUsage don\'t show "no-" in title',
+        () {
+      var parser = ArgParser();
+      parser.addFlag('mode', help: 'The mode', hideNegatedUsage: true);
+
+      validateUsage(parser, '''
+          --mode    The mode
+          ''');
+    });
+
     test('non-negatable flags don\'t show "no-" in title', () {
       var parser = ArgParser();
       parser.addFlag('mode', negatable: false, help: 'The mode');