GSoC 2024 Cargo Completions Notes

General availability: https://lettucemeet.com/l/e49bd

Parent issues

• https://github.com/clap-rs/clap/issues/3166
  • https://github.com/clap-rs/clap/tree/master/clap_complete/src/dynamic
• https://github.com/rust-lang/cargo/issues/6645

Ed's work schedule: 9am Central US to 5pm Central US
Ed's extended schedule: 7pm-9pm (on a when available basis)

Syncs

2024-05-22

Starting point: https://github.com/clap-rs/clap/issues/3920

2024-05-31

• Review how other custom completers design their dynamic completion parts and design a good dynamic completion: https://github.com/clap-rs/clap/discussions/5512

• Confirm the features of the existing completion scripts for Cargo commands. These need to be considered when designing the dynamic completion for clap_complete.

Q: For value completion in Cargo commands, many require executing some functions to obtain the possible values list. We might need to implement the possible_values method of the TypedValueParser trait for Fn(&str) -> Result<T, E> + Clone + Send + Sync + 'static to support user-defined closures or functions for obtaining possible values.

2024-06-07

• Research: https://github.com/clap-rs/clap/discussions/5512
• https://hackmd.io/aDFjwmx0SSm_oZeaoGeWtQ
  • something like this was done before and stopped in https://github.com/clap-rs/clap/pull/5018
• Maybe shift focus to just --option value

2024-06-21

Three branches

• shells (zsh, elvish)
• options
  • then multiple options
• hidden https://github.com/clap-rs/clap/issues/3951
  • then https://github.com/clap-rs/clap/issues/5058

2024-07-05

• Adding of shells needs feature comparison with static completion shell support and either not close out issue or create separate issues for things not done in PRs
• Added documentation task to tracking issue
• For https://github.com/clap-rs/clap/pull/5539
  • Suggested holding off on extra ways of doing values so we can close out the PR

2024-07-12

2024-07-19

• powershell
  • https://github.com/clap-rs/clap/pull/5564
  • move forward without tests
  • having tests is better than the static completions
  • better to crowdsource with powershell users
• Start asking for testing
  • https://github.com/clap-rs/clap/pull/5539
  • https://github.com/clap-rs/clap/pull/5564
  • hidden stuff not required but nice as it shows the value
  • won't wait for users, handled async
• Focus:
  • option-values
  • hidden
  • powershell
• Next:
  • multiple values
  • =?
  • Correctly handle appending a space?
    • epage: break this out into an issue

2024-07-26

• Next:
  • https://github.com/clap-rs/clap/issues/1232
• epage:
  • Put up unstable-ext PR
  • Audit completion issues

2024-08-02

• Back to school Aug 9th
• Next:
  • Custom completers
  • Test it out in Cargo

trait CustomCompleter {
    fn completions(&self) -> Vec<CompletionCandidate>;
}

impl<F> CustomCompleter for F 
where F: Fn() -> Vec<CompletionCandidate> {
    fn completions(&self) -> Vec<CompletionCandidate> {
        (self)()
    }
}

2024-08-16

• cargo <cmd>

  • Complete built-ins, third-party subcommand, aliases (https://doc.rust-lang.org/cargo/reference/config.html#alias)
  • cargo <cmd> <args> is separate and needs https://github.com/clap-rs/clap/issues/5653

• cargo <cmd> <args>

  • Not feature parity?

• switch to env variable-driven completions

  • decide what shells are supported / documented
  • shell support
    • option: only what we do today
    • option: only document what we do today
    • option: support all
    • explain why we chose what we did

• test plan

  • completest for autoamted tests
  • end-user acceptance testing / call-for-testing
    • Switch to env variables
    • Don't replace manual scripts until stabilization
    • Make it only available on nightly: https://docs.rs/cargo/latest/cargo/util/context/struct.GlobalContext.html#structfield.nightly_features_allowed
      • https://docs.rs/cargo/latest/cargo/core/features/fn.channel.html
    • call-for-testing: https://doc.crates.io/contrib/process/unstable.html#pre-stabilization

• Initial cargo PR

• uses env variables

• only works on nightly

• doesn't use argvaluecompleter yet

• unstable.md documentation

• Open question: unstable feature of clap

• Tracking issue tasks

  • Each argvaluecompleter
  • Replacing the manual completion files

2024-08-26

• cargo PR
  • completest timeout override
  • Between these lines use CompleteEnv:
    • https://github.com/rust-lang/cargo/blob/f2d1e37b56529f5200c3861be8b3d1c24f62c135/src/bin/cargo/main.rs#L21-L23
  • Check nightly like: https://docs.rs/cargo/latest/src/cargo/util/context/mod.rs.html#325
  • env var name: CARGO_COMPLETE

2024-08-30

• timeout PR has one issue in it
• Does cargo need timeout when using CompleteEnv
  • Action item: create draft PR against rust-lang/cargo with where you are at
• Welcome to https://github.com/rust-lang/cargo/wiki/Office-Hours

2024-09-09

• Testing in cargo
  • CompleteEnv, needs end to end
  • Maybe needs all shells for registration command?
  • Otherwise, only needs one shell and one end-to-end test
  • If only 1-5 tests, don't need a file per sub-feature or shell