Skip to main content

install

shellcomp

Function install 

Source 
pub fn install(request: InstallRequest<'_>) -> Result<InstallReport>
Expand description

Installs a completion script and returns a structured report.

When path_override is None, the script is written into the shell’s managed default location and shellcomp attempts to wire activation automatically. When path_override is set, legacy behavior is to treat non-default custom paths as manual activation, while an override equal to the managed default path still keeps the default activation semantics.

This function is idempotent with respect to the written script contents and managed startup wiring. Re-installing an identical script normally returns crate::FileChange::Unchanged.

§Errors

Returns crate::Error::Failure for structured operational failures such as missing HOME, unwritable target files, or shell profile update failures.

Immediate validation problems such as an invalid program_name are returned as direct crate::Error variants instead of crate::Error::Failure.

§Examples

use shellcomp::{InstallRequest, Shell, install};

let report = install(InstallRequest {
    shell: Shell::Zsh,
    program_name: "demo",
    script: b"#compdef demo\n",
    path_override: None,
})?;

assert_eq!(report.shell, Shell::Zsh);
Examples found in repository?
examples/install_prebuilt.rs (lines 12-17)
5fn main() -> Result<(), Box<dyn std::error::Error>> {
6    let script = br#"_demo_complete() {
7    COMPREPLY=("hello" "world")
8}
9complete -F _demo_complete demo
10"#;
11    let demo_path = env::temp_dir().join(format!("demo-prebuilt-{}.bash", std::process::id()));
12    let report = install(InstallRequest {
13        shell: Shell::Bash,
14        program_name: "demo",
15        script,
16        path_override: Some(demo_path.clone()),
17    })?;
18
19    println!("Installed a prebuilt Bash completion script without touching your shell profile.");
20    println!("Path: {}", demo_path.display());
21    println!("{report:#?}");
22    Ok(())
23}
More examples
Hide additional examples
examples/clap_integration.rs (lines 16-21)
12fn main() -> Result<(), Box<dyn std::error::Error>> {
13    let generator_shell = shellcomp::clap_complete::Shell::Bash;
14    let script = render_clap_completion::<Cli>(generator_shell, "example-cli")?;
15    let demo_path = env::temp_dir().join(format!("example-cli-{}.bash", std::process::id()));
16    let report = install(InstallRequest {
17        shell: generator_shell.into(),
18        program_name: "example-cli",
19        script: &script,
20        path_override: Some(demo_path.clone()),
21    })?;
22
23    println!("Rendered completion from clap and installed it to a temporary path.");
24    println!("Path: {}", demo_path.display());
25    println!("{report:#?}");
26    Ok(())
27}
examples/roundtrip_custom_path.rs (lines 9-14)
5fn main() -> Result<(), Box<dyn std::error::Error>> {
6    let demo_path = env::temp_dir().join(format!("demo-roundtrip-{}.fish", std::process::id()));
7    let script = b"complete -c demo -f\n";
8
9    let install_report = install(InstallRequest {
10        shell: Shell::Fish,
11        program_name: "demo",
12        script,
13        path_override: Some(demo_path.clone()),
14    })?;
15
16    let uninstall_report = uninstall(UninstallRequest {
17        shell: Shell::Fish,
18        program_name: "demo",
19        path_override: Some(demo_path.clone()),
20    })?;
21
22    println!("Installed and removed a custom-path completion file.");
23    println!("Path: {}", demo_path.display());
24    println!("Install report:\n{install_report:#?}");
25    println!("Uninstall report:\n{uninstall_report:#?}");
26    Ok(())
27}