Mirrors/clap
2
0
Fork 0
mirror of https://github.com/clap-rs/clap synced 2024-11-10 06:44:16 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request #5680 from epage/unstable

Browse source 
docs(complete): Specify the compatibility guarentees
This commit is contained in:
Ed Page 2024-08-16 09:53:35 -05:00 committed by GitHub
commit 17d6d24232
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 22 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
clap_complete/src/dynamic/command/mod.rs
View file

@ -5,6 +5,13 @@
//!
//! To source your completions:
//!
//! **WARNING:** We recommend re-sourcing your completions on upgrade.
//! These completions work by generating shell code that calls into `your_program` while completing.
//! That interface is unstable and a mismatch between the shell code and `your_program` may result
//! in either invalid completions or no completions being generated.
//! For this reason, we recommend generating the shell code anew on shell startup so that it is
//! "self-correcting" on shell launch, rather than writing the generated completions to a file.
//!
//! Bash
//! ```bash
//! echo "source <(your_program complete bash)" >> ~/.bashrc
@ -207,6 +214,10 @@ pub trait CommandCompleter {
///
/// Write the `buf` the logic needed for calling into `<cmd> complete`, passing needed
/// arguments to [`CommandCompleter::write_complete`] through the environment.
///
/// **WARNING:** There are no stability guarantees between the call to
/// [`CommandCompleter::write_complete`] that this generates and actually calling [`CommandCompleter::write_complete`].
/// Caching the results of this call may result in invalid or no completions to be generated.
fn write_registration(
&self,
name: &str,

11
clap_complete/src/dynamic/env/mod.rs vendored
View file

@ -18,6 +18,13 @@
//!
//! To source your completions:
//!
//! **WARNING:** We recommend re-sourcing your completions on upgrade.
//! These completions work by generating shell code that calls into `your_program` while completing.
//! That interface is unstable and a mismatch between the shell code and `your_program` may result
//! in either invalid completions or no completions being generated.
//! For this reason, we recommend generating the shell code anew on shell startup so that it is
//! "self-correcting" on shell launch, rather than writing the generated completions to a file.
//!
//! Bash
//! ```bash
//! echo "source <(COMPLETE=bash your_program)" >> ~/.bashrc
@ -276,6 +283,10 @@ pub trait EnvCompleter {
///
/// Write the `buf` the logic needed for calling into `<VAR>=<shell> <cmd> --`, passing needed
/// arguments to [`EnvCompleter::write_complete`] through the environment.
///
/// **WARNING:** There are no stability guarantees between the call to
/// [`EnvCompleter::write_complete`] that this generates and actually calling [`EnvCompleter::write_complete`].
/// Caching the results of this call may result in invalid or no completions to be generated.
fn write_registration(
&self,
var: &str,