diff --git a/pkgs/args/CHANGELOG.md b/pkgs/args/CHANGELOG.md index 03e693c5..7484eee2 100644 --- a/pkgs/args/CHANGELOG.md +++ b/pkgs/args/CHANGELOG.md @@ -1,6 +1,8 @@ ## 2.6.1-wip * Fix the reporitory URL in `pubspec.yaml`. +* Added option `hideNegatedUsage` to `ArgParser.flag()` allowing a flag to be + `negatable` without showing it in the usage text. ## 2.6.0 diff --git a/pkgs/args/lib/src/allow_anything_parser.dart b/pkgs/args/lib/src/allow_anything_parser.dart index 46dfc940..69472b37 100644 --- a/pkgs/args/lib/src/allow_anything_parser.dart +++ b/pkgs/args/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 aliases = const []}) { throw UnsupportedError( "ArgParser.allowAnything().addFlag() isn't supported."); diff --git a/pkgs/args/lib/src/arg_parser.dart b/pkgs/args/lib/src/arg_parser.dart index c47c0030..50c3991d 100644 --- a/pkgs/args/lib/src/arg_parser.dart +++ b/pkgs/args/lib/src/arg_parser.dart @@ -119,6 +119,11 @@ 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 +138,7 @@ class ArgParser { bool negatable = true, void Function(bool)? callback, bool hide = false, + bool hideNegatedUsage = false, List aliases = const []}) { _addOption( name, @@ -146,6 +152,7 @@ class ArgParser { OptionType.flag, negatable: negatable, hide: hide, + hideNegatedUsage: hideNegatedUsage, aliases: aliases); } @@ -285,6 +292,7 @@ class ArgParser { bool? splitCommas, bool mandatory = false, bool hide = false, + bool hideNegatedUsage = false, List aliases = const []}) { var allNames = [name, ...aliases]; if (allNames.any((name) => findByNameOrAlias(name) != null)) { @@ -306,12 +314,20 @@ 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); diff --git a/pkgs/args/lib/src/option.dart b/pkgs/args/lib/src/option.dart index 50a8628a..463e5e2d 100644 --- a/pkgs/args/lib/src/option.dart +++ b/pkgs/args/lib/src/option.dart @@ -20,6 +20,7 @@ Option newOption( bool? splitCommas, bool mandatory = false, bool hide = false, + bool hideNegatedUsage = false, List aliases = const []}) { return Option._(name, abbr, help, valueHelp, allowed, allowedHelp, defaultsTo, callback, type, @@ -27,6 +28,7 @@ Option newOption( 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 = diff --git a/pkgs/args/lib/src/usage.dart b/pkgs/args/lib/src/usage.dart index 1ef96273..bd39f112 100644 --- a/pkgs/args/lib/src/usage.dart +++ b/pkgs/args/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}'; diff --git a/pkgs/args/test/usage_test.dart b/pkgs/args/test/usage_test.dart index 11671860..6f5315b5 100644 --- a/pkgs/args/test/usage_test.dart +++ b/pkgs/args/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');