search

clap-rs / clap

A full featured, fast Command Line Argument Parser for Rust
docs.rs/clap
Apache License 2.0
13.65k stars 1.02k forks source link

Allow API users to deprecate args #5486

Closed valadaptive closed 2 months ago

valadaptive commented 2 months ago

Please complete the following tasks

Clap Version

4.5.4

Describe your use case

This seems to be a prerequisite to https://github.com/rust-lang/cargo/issues/6790, or at the very least it would really help.

To stabilize Cargo's --out-dir flag, it likely will need to be renamed to something else. However, there are a lot of users of --out-dir, so it would be nice to be able to deprecate --out-dir and direct users to whatever it gets renamed to.

Such a scenario is applicable to other projects as well: API consumers may want to rename arguments or give them a deprecation period before removing them entirely.

Describe the solution you'd like

A way to mark Args as deprecated, or warn when they are passed. Passing such an argument to the program will result in a warning being printed, telling the user to either stop using the argument or migrate to its replacement.

I don't entirely know what this API should look like--should it be a generic "warn on argument use" API or specifically designed around deprecation?

Alternatives, if applicable

  1. A way to specifically mark Args as deprecated, possibly allowing for deprecation-specific functionality like automatically redirecting users to their replacements.
  2. A simpler "print a warning when argument passed" mechanism.

Additional Context

No response

epage commented 2 months ago

Closing in favor of #3321. If there is a reason to keep this open separately, let us know!

As for cargo, I wouldn't wait on anything like this. We've already handled cases like this before by defining both attributes and suing shell.warn if the deprecated one is used.