Add a way to deprecate argument

Hello,

First, thanks a lot for this great tool!

In one of my CLI, I decided to change slightly the API and I want to deprecated some options.

It would be nice if this could be supported out of the box by Clikt.

class MyCommand : CliktCommand() {

  val oldFlag by option("--old-api").convert { it.toBoolean() }.deprecated("Use --new-api instead")
  val newFlag by option("--new-api").flag()

  override fun run() {
     if (oldFlag ?: newFlag) println("Hello world")
  }
}

Then if one run --old-api true, the program would not crash, but display a warning message:

WARNING: The option '--old-api' is deprecated: Use --new-api instead

Running --help could either not show the option at all, or explicitly state it is deprecated.

Eventually deprecatedcould take a severity argument (warning or error) where the “error” level would make the program crash with a nice and explicit error message in case the deprecated api has been used.

What do you think?

[jcornaz]

Do you have any examples of popular CLI programs with deprecated option names

gcloud (CLI for using Google Cloud), regulary deprecate CLI subcomands and options. Just CTRL+F “depreacted” here: https://cloud.google.com/sdk/docs/release-notes.

awscli (CLI for using AWS) is no exception. It is harder to find, because their changelog is not as nice as it is for glcoud. But here is a random deprecated subcommand: https://docs.aws.amazon.com/cli/latest/reference/s3api/put-bucket-lifecycle.html

Jenkins also deprecated few options (like --spdy) for a while before removing them completely.

I’m sure we can find others. I bet some security CLI like ssh deprecate unsecure options from time to time.

[ajalt]

Thanks for the suggestion! I added this in 4bec1458, which is part of the 2.0.0 release.

Docs: https://ajalt.github.io/clikt/options/#deprecating-options