Add option hideNegatable to ArgParser.flag()

[sigurdm]

This can be useful when you want to allow negating a flag for eg. future compatibility.

But you don't want to encumber the --help text with this information

[sigurdm]

cc @jakemac53 might also have input here.

[jonasfj]

I think this is fantastic.

For lots of flags having --[no-] in the --help message just clutters the usage unnecessarily.

Example

$dart pub upgrade --help
Upgrade the current package's dependencies to latest versions.

Usage: dart pub upgrade [dependencies...]
-h, --help               Print this usage information.
    --[no-]offline       Use cached packages instead of accessing the network.
-n, --dry-run            Report what dependencies would change but don't change
                         any.
    --[no-]precompile    Precompile executables in immediate dependencies.
    --tighten            Updates lower bounds in pubspec.yaml to match the
                         resolved version.
    --major-versions     Upgrades packages to their latest resolvable versions,
                         and updates pubspec.yaml.
-C, --directory=<dir>    Run this in the directory <dir>.

Run "dart help" to see global options.
See https://dart.dev/tools/pub/cmd/pub-upgrade for detailed documentation.

For flags like --offline the arguments goes as follows:

• Pro: --no-offline and --offline
  • Forwards compatibility:
    • If in the future the default value changes (maybe it becomes auto-detected), having the ability to put --no-offline into a script is nice.
    • Even, if you don't put --no-offline into scripts now, the fact that it would be supported by older versions of the Dart SDK is nice, if suddenly you find yourself writing scripts where --no-offline makes sense.
  • Appending options to negate previous options:
    • If you have a bash script containing dart pub upgrade --offline $@, it's nice that you can append a --no-offline to the script to negate the previous option.
• Con: --no-offline (arguing we should only have --offline)
  • There is never a reason to negate the option.
    (Examples include --major-versions)
  • It clutters the --help usage message.
  • It causes unnecessary confusion about the default value, because one could infer that the default value might be a 3rd state (something like auto-detect).

In some cases, like --major-versions having the negated flag --no-major-versions really doesn't make much sense, since --major-versions will arguably never be a default flag.

In other cases, it's clearly a feature to have both --no-color and --color (because the default is automatically detected).

But there is a huge grey area in between, where it's not always easy to balance the value of --no- vs having a cleaner --help usage message.

I think hideNegatable: true is a good compromise for cases where:

• It's unclear if we might want to change the default in the future.
• We don't want to clutter the --help message.
• We accidentally created the --no-<option> variant, because negatable: true is the default, and we can't undo it because it would be a breaking change.
  • In these cases we would normally use hide: true, but that doesn't work, if we only want to hide the --no-<option> variant.
  • Examples: --no-precompile and --no-offline.

---

At the end of the day, we can spend a lot of time debating whether an option should be negatable or not. But in practice the biggest argument against supporting a --no-<option> variant is always going to be the --help usage message.

[jakemac53]

This seems like a fine thing to leave up to the user to choose how they want their usage presented. I have one comment about the actual configuration (will leave that as a separate comment).

[jakemac53]

We will also need a pubspec/changelog update here

[jakemac53]

LGTM once the lint is fixed

[mosuem]

Closing as the dart-lang/args repository is merged into the dart-lang/core monorepo. Please re-open this PR there!

Reopened in the core repository!