Struct CompletionResult 

pub struct CompletionResult {
    pub values: Vec<String>,
    pub descriptions: Vec<String>,
    pub active_help: Vec<ActiveHelp>,
}

Result returned by completion functions

CompletionResult contains completion suggestions along with optional descriptions for each suggestion. This is used by the shell completion system to provide helpful hints to users.

Examples

use flag_rs::completion::CompletionResult;

let completions = CompletionResult::new()
    .add("create")
    .add_with_description("delete", "Remove a resource")
    .add_with_description("list", "Show all resources")
    .extend(vec!["get".to_string(), "update".to_string()]);

assert_eq!(completions.values.len(), 5);
assert_eq!(completions.values[1], "delete");
assert_eq!(completions.descriptions[1], "Remove a resource");

Fields

values: Vec<String>

The completion values to suggest

descriptions: Vec<String>

Optional descriptions for each value

active_help: Vec<ActiveHelp>

ActiveHelp messages to display

Implementations

impl CompletionResult

pub fn new() -> Self

Creates a new empty completion result

Examples found in repository

examples/kubectl.rs (line 32)

fn build_kubectl() -> Command {
    CommandBuilder::new("kubectl")
        .short("Kubernetes command-line tool")
        .long("kubectl controls the Kubernetes cluster manager")
        .subcommand(build_get_command())
        .subcommand(build_describe_command())
        .subcommand(build_delete_command())
        .subcommand(build_completion_command())
        .flag(
            Flag::new("namespace")
                .short('n')
                .usage("Kubernetes namespace")
                .value_type(FlagType::String)
                .default(FlagValue::String("default".to_string())),
        )
        .flag_completion("namespace", |_ctx, prefix| {
            // In a real kubectl, this would query the API server
            let namespaces = get_namespaces_with_descriptions();
            let mut result = CompletionResult::new();

            for (ns_name, description) in namespaces {
                if ns_name.starts_with(prefix) {
                    result = result.add_with_description(ns_name, description);
                }
            }

            Ok(result)
        })
        .build()
}

fn build_get_command() -> Command {
    CommandBuilder::new("get")
        .short("Display one or many resources")
        .long("Display one or many resources. Prints a table of the most important information about the specified resources.")
        .flag(
            Flag::new("limit")
                .short('l')
                .usage("Maximum number of resources to display")
                .value_type(FlagType::String)
        )
        .flag_completion("limit", |_ctx, prefix| {
            let common_limits = vec![
                ("10", "Display 10 items"),
                ("20", "Display 20 items"),
                ("50", "Display 50 items"),
                ("100", "Display 100 items"),
                ("all", "Display all items (no limit)"),
            ];

            let mut result = CompletionResult::new();
            for (limit, description) in common_limits {
                if limit.starts_with(prefix) {
                    result = result.add_with_description(limit.to_string(), description.to_string());
                }
            }

            Ok(result)
        })
        .subcommand(build_get_pods())
        .subcommand(build_get_services())
        .subcommand(build_get_deployments())
        .build()
}

fn build_get_pods() -> Command {
    CommandBuilder::new("pods")
        .aliases(vec!["po", "pod"])
        .short("List pods")
        .arg_completion(|ctx, prefix| {
            // This is the key feature - dynamic completion based on runtime state!
            let namespace = ctx
                .flag("namespace")
                .map(String::as_str)
                .unwrap_or("default");

            // In real kubectl, this would query the K8s API
            let pods = get_pods_with_status(namespace);
            let mut result = CompletionResult::new();

            for (pod_name, status) in pods {
                if pod_name.starts_with(prefix) {
                    result = result.add_with_description(pod_name, status);
                }
            }

            Ok(result)
        })
        .run(|ctx| {
            let namespace = ctx
                .flag("namespace")
                .map(String::as_str)
                .unwrap_or("default");

            println!("Listing pods in namespace: {namespace}");

            if let Some(pod_name) = ctx.args().first() {
                println!("Getting specific pod: {pod_name}");
            } else {
                for pod in get_pods_in_namespace(namespace) {
                    println!("pod/{}", pod);
                }
            }

            Ok(())
        })
        .build()
}

fn build_get_services() -> Command {
    CommandBuilder::new("services")
        .aliases(vec!["svc", "service"])
        .short("List services")
        .arg_completion(|ctx, prefix| {
            let namespace = ctx
                .flag("namespace")
                .map(String::as_str)
                .unwrap_or("default");

            let services = get_services_in_namespace(namespace);
            Ok(CompletionResult::new()
                .extend(services.into_iter().filter(|svc| svc.starts_with(prefix))))
        })
        .run(|ctx| {
            let namespace = ctx
                .flag("namespace")
                .map(String::as_str)
                .unwrap_or("default");

            println!("Listing services in namespace: {namespace}");
            Ok(())
        })
        .build()
}

fn build_get_deployments() -> Command {
    CommandBuilder::new("deployments")
        .aliases(vec!["deploy", "deployment"])
        .short("List deployments")
        .run(|ctx| {
            let namespace = ctx
                .flag("namespace")
                .map(String::as_str)
                .unwrap_or("default");

            println!("Listing deployments in namespace: {namespace}");
            Ok(())
        })
        .build()
}

fn build_describe_command() -> Command {
    CommandBuilder::new("describe")
        .short("Show details of a specific resource")
        .flag(
            Flag::new("output")
                .short('o')
                .usage("Output format")
                .value_type(FlagType::String),
        )
        .run(|_ctx| {
            println!("Describe command - add resource type subcommands");
            Ok(())
        })
        .build()
}

fn build_delete_command() -> Command {
    CommandBuilder::new("delete")
        .short("Delete resources")
        .run(|_ctx| {
            println!("Delete command - add resource type subcommands");
            Ok(())
        })
        .build()
}

// Mock functions that would normally query the Kubernetes API
fn get_namespaces_with_descriptions() -> Vec<(String, String)> {
    vec![
        (
            "default".to_string(),
            "Default namespace for user workloads".to_string(),
        ),
        (
            "kube-system".to_string(),
            "Kubernetes system components".to_string(),
        ),
        (
            "kube-public".to_string(),
            "Public resources accessible to all users".to_string(),
        ),
        (
            "development".to_string(),
            "Development environment".to_string(),
        ),
        (
            "staging".to_string(),
            "Staging environment for pre-production testing".to_string(),
        ),
        (
            "production".to_string(),
            "Production environment (CAUTION)".to_string(),
        ),
    ]
}

fn get_pods_with_status(namespace: &str) -> Vec<(String, String)> {
    use std::time::{SystemTime, UNIX_EPOCH};

    // Generate random suffix based on current time
    let timestamp = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap()
        .as_secs();

    // Simple pseudo-random generation
    let rand1 = ((timestamp * 1_103_515_245 + 12345) / 65536) % 100_000;
    let rand2 = ((rand1 * 1_103_515_245 + 12345) / 65536) % 100_000;
    let rand3 = ((rand2 * 1_103_515_245 + 12345) / 65536) % 100_000;

    match namespace {
        "default" => vec![
            (
                format!("nginx-deployment-7fb96c846b-{:05x}", rand1),
                "Running (2/2 containers)".to_string(),
            ),
            (
                format!("nginx-deployment-7fb96c846b-{:05x}", rand2),
                "Running (2/2 containers)".to_string(),
            ),
            (
                "redis-master-0".to_string(),
                "Running (1/1 containers)".to_string(),
            ),
            (
                "redis-slave-0".to_string(),
                "Running (1/1 containers)".to_string(),
            ),
            ("redis-slave-1".to_string(), "Pending".to_string()),
        ],
        "kube-system" => vec![
            (
                format!("coredns-5d78c9869d-{:05x}", rand1),
                "Running (1/1 containers)".to_string(),
            ),
            (
                format!("coredns-5d78c9869d-{:05x}", rand2),
                "Running (1/1 containers)".to_string(),
            ),
            ("etcd-minikube".to_string(), "Running".to_string()),
            ("kube-apiserver-minikube".to_string(), "Running".to_string()),
            (
                "kube-controller-manager-minikube".to_string(),
                "Running".to_string(),
            ),
            (format!("kube-proxy-{:05x}", rand3), "Running".to_string()),
            ("kube-scheduler-minikube".to_string(), "Running".to_string()),
        ],
        _ => vec![],
    }
}

fn get_pods_in_namespace(namespace: &str) -> Vec<String> {
    use std::time::{SystemTime, UNIX_EPOCH};

    // Generate random suffix based on current time
    let timestamp = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap()
        .as_secs();

    // Simple pseudo-random generation
    let rand1 = ((timestamp * 1_103_515_245 + 12345) / 65536) % 100_000;
    let rand2 = ((rand1 * 1_103_515_245 + 12345) / 65536) % 100_000;
    let rand3 = ((rand2 * 1_103_515_245 + 12345) / 65536) % 100_000;

    match namespace {
        "default" => vec![
            format!("nginx-deployment-7fb96c846b-{:05x}", rand1),
            format!("nginx-deployment-7fb96c846b-{:05x}", rand2),
            format!("redis-master-0"),
            format!("redis-slave-0"),
            format!("redis-slave-1"),
        ],
        "kube-system" => vec![
            format!("coredns-5d78c9869d-{:05x}", rand1),
            format!("coredns-5d78c9869d-{:05x}", rand2),
            format!("etcd-minikube"),
            format!("kube-apiserver-minikube"),
            format!("kube-controller-manager-minikube"),
            format!("kube-proxy-{:05x}", rand3),
            format!("kube-scheduler-minikube"),
        ],
        _ => vec![],
    }
}

fn get_services_in_namespace(namespace: &str) -> Vec<String> {
    match namespace {
        "default" => vec![
            "kubernetes".to_string(),
            "nginx-service".to_string(),
            "redis-master".to_string(),
            "redis-slave".to_string(),
        ],
        "kube-system" => vec!["kube-dns".to_string()],
        _ => vec![],
    }
}

fn build_completion_command() -> Command {
    CommandBuilder::new("completion")
        .short("Generate shell completion scripts")
        .long("Generate shell completion scripts for kubectl")
        .arg_completion(|_ctx, prefix| {
            let shells = vec![
                ("bash", "Bash shell completion"),
                ("zsh", "Zsh shell completion"),
                ("fish", "Fish shell completion"),
            ];

            let mut result = CompletionResult::new();
            for (shell, description) in shells {
                if shell.starts_with(prefix) {
                    result =
                        result.add_with_description(shell.to_string(), description.to_string());
                }
            }

            Ok(result)
        })
        .run(|ctx| {
            let shell_name = ctx.args().first().ok_or_else(|| {
                flag_rs::Error::ArgumentParsing(
                    "shell name required (bash, zsh, or fish)".to_string(),
                )
            })?;

            let shell = match shell_name.as_str() {
                "bash" => Shell::Bash,
                "zsh" => Shell::Zsh,
                "fish" => Shell::Fish,
                _ => {
                    return Err(flag_rs::Error::ArgumentParsing(format!(
                        "unsupported shell: {}",
                        shell_name
                    )));
                }
            };

            // In a real app, you'd get the root command from a shared reference
            // For this example, we'll recreate it
            let root = build_kubectl();
            println!("{}", root.generate_completion(shell));

            Ok(())
        })
        .build()
}

examples/benchmark.rs (line 209)

fn bench_completion() {
    println!("\n=== Completion Benchmarks ===");

    let cli = CommandBuilder::new("comp")
        .arg_completion(|_ctx, prefix| {
            let items: Vec<String> = (0..100)
                .map(|i| format!("item{i:03}"))
                .filter(|item| item.starts_with(prefix))
                .collect();
            Ok(CompletionResult::new().extend(items))
        })
        .build();

    let ctx = flag_rs::Context::new(vec!["comp".to_string()]);

    let bench = Benchmark::new("Complete with empty prefix (100 items)", 1_000);
    let duration = bench.run(|| {
        let _ = cli.get_completions(&ctx, "", None);
    });
    bench.report(duration);

    let bench = Benchmark::new("Complete with prefix (filtered)", 1_000);
    let duration = bench.run(|| {
        let _ = cli.get_completions(&ctx, "item05", None);
    });
    bench.report(duration);

    // Test completion with descriptions
    let cli_desc = CommandBuilder::new("comp_desc")
        .arg_completion(|_ctx, prefix| {
            let mut result = CompletionResult::new();
            for i in 0..50 {
                let item = format!("option{i:02}");
                if item.starts_with(prefix) {
                    result =
                        result.add_with_description(item, format!("Description for option {i}"));
                }
            }
            Ok(result)
        })
        .build();

    let bench = Benchmark::new("Complete with descriptions (50 items)", 1_000);
    let duration = bench.run(|| {
        let _ = cli_desc.get_completions(&ctx, "", None);
    });
    bench.report(duration);
}

examples/test_completion.rs (line 13)

fn main() {
    let cmd = CommandBuilder::new("test")
        .short("Test completion with descriptions")
        .flag(
            Flag::new("environment")
                .short('e')
                .usage("Target environment")
                .value_type(FlagType::String),
        )
        .flag_completion("environment", |_ctx, prefix| {
            let mut result = CompletionResult::new();
            let envs = vec![
                ("dev", "Development environment - safe for testing"),
                ("staging", "Staging environment - mirror of production"),
                ("production", "Production environment - BE CAREFUL!"),
            ];

            for (env, desc) in envs {
                if env.starts_with(prefix) {
                    result = result.add_with_description(env, desc);
                }
            }

            Ok(result)
        })
        .subcommand(
            CommandBuilder::new("deploy")
                .short("Deploy the application")
                .long("Deploy the application to the specified environment")
                .build(),
        )
        .subcommand(
            CommandBuilder::new("rollback")
                .short("Rollback to previous version")
                .long("Rollback the application to the previous deployed version")
                .build(),
        )
        .build();

    // Test completion output
    if let Ok(shell_type) = std::env::var("TEST_COMPLETE") {
        // For testing, override shell type to "display" to see formatted output
        let display_mode = std::env::var("DISPLAY_MODE").is_ok();
        let args: Vec<String> = std::env::args().skip(1).collect();

        if display_mode {
            // This is a hack for testing - normally shells would handle this
            println!("Display mode - showing formatted completions:");
            match cmd.handle_completion_request(&args) {
                Ok(completions) => {
                    for completion in completions {
                        println!("{}", completion);
                    }
                }
                Err(e) => eprintln!("Completion error: {}", e),
            }
        } else {
            match cmd.handle_completion_request(&args) {
                Ok(completions) => {
                    println!("Shell type: {}", shell_type);
                    println!("Completions:");
                    for completion in completions {
                        println!("{}", completion);
                    }
                }
                Err(e) => eprintln!("Completion error: {}", e),
            }
        }
    } else {
        let args: Vec<String> = std::env::args().skip(1).collect();
        if let Err(e) = cmd.execute(args) {
            eprintln!("Error: {}", e);
            std::process::exit(1);
        }
    }
}

examples/timeout_completion_demo.rs (line 57)

fn main() {
    let app = CommandBuilder::new("cloud-cli")
        .short("Cloud CLI with timeout-protected completions")
        .flag(
            Flag::new("region")
                .short('r')
                .usage("Cloud region")
                .value_type(FlagType::String)
                .default(flag_rs::FlagValue::String("us-east-1".to_string())),
        )
        .subcommand(
            CommandBuilder::new("instances")
                .short("Manage cloud instances")
                .subcommand(
                    CommandBuilder::new("list")
                        .short("List instances (fast completion)")
                        .arg_completion(|_ctx, prefix| {
                            // Fast completion - no timeout needed
                            let instances = vec![
                                "web-server-001",
                                "web-server-002",
                                "db-primary",
                                "db-replica",
                                "cache-node-1",
                                "cache-node-2",
                            ];

                            Ok(CompletionResult::new().extend(
                                instances
                                    .into_iter()
                                    .filter(|i| i.starts_with(prefix))
                                    .map(String::from),
                            ))
                        })
                        .build(),
                )
                .subcommand(
                    CommandBuilder::new("describe")
                        .short("Describe instance (slow completion with timeout)")
                        .arg_completion({
                            // Wrap slow completion with timeout
                            make_timeout_completion(
                                Duration::from_millis(500), // 500ms timeout
                                |ctx, prefix| {
                                    eprintln!("Fetching instance details from API...");

                                    // Simulate slow API call (1 second)
                                    let instances = slow_completion(prefix, 1000);

                                    let mut result = CompletionResult::new();
                                    for instance in instances {
                                        result = result.add_with_description(
                                            instance.clone(),
                                            format!(
                                                "Instance in region {}",
                                                ctx.flag("region")
                                                    .unwrap_or(&"us-east-1".to_string())
                                            ),
                                        );
                                    }

                                    if prefix.is_empty() {
                                        result = result.add_help_text(
                                            "Fetching live instance data from cloud API...",
                                        );
                                    }

                                    Ok(result)
                                },
                            )
                        })
                        .build(),
                )
                .subcommand(
                    CommandBuilder::new("create")
                        .short("Create instance (very slow completion)")
                        .arg_completion({
                            // Use default timeout (2 seconds)
                            make_timeout_completion(DEFAULT_COMPLETION_TIMEOUT, |_ctx, prefix| {
                                eprintln!("Checking available instance types...");

                                // Simulate very slow operation (3 seconds)
                                let types = slow_completion(prefix, 3000);

                                Ok(CompletionResult::new()
                                    .extend(types)
                                    .add_help_text("Available instance types"))
                            })
                        })
                        .build(),
                )
                .build(),
        )
        .build();

    println!("=== Timeout Completion Demo ===\n");
    println!("This demo shows how timeouts protect against slow completion operations.\n");
    println!("To test timeout handling:");
    println!("1. Set up bash completion:");
    println!(
        "   source <({} completion bash)",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("2. Test different completion speeds:");
    println!();
    println!("   Fast (no timeout needed):");
    println!(
        "   {} instances list <TAB>",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("   Slow (500ms timeout, 1s operation - will timeout):");
    println!(
        "   {} instances describe <TAB>",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("   Very slow (2s timeout, 3s operation - will timeout):");
    println!(
        "   {} instances create <TAB>",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("When a timeout occurs, you'll see:");
    println!("- A warning message about the timeout");
    println!("- Any partial results that were available");
    println!("- Suggestion to use a more specific prefix");
    println!("\n---\n");

    let args: Vec<String> = std::env::args().skip(1).collect();
    if let Err(e) = app.execute(args) {
        eprintln!("{}", e);
        std::process::exit(1);
    }
}

examples/flag_completion_demo.rs (line 20)

fn main() {
    let app = CommandBuilder::new("deploy")
        .short("Deploy application to various environments")
        .flag(
            Flag::choice("environment", &["dev", "staging", "prod"])
                .short('e')
                .usage("Target environment")
                .required()
                .completion(|_ctx, prefix| {
                    // Dynamic completion - could check available environments
                    let environments = vec![
                        ("dev", "Development environment"),
                        ("staging", "Staging environment (pre-production)"),
                        ("prod", "Production environment"),
                    ];

                    let mut result = CompletionResult::new();
                    for (env, desc) in environments {
                        if env.starts_with(prefix) {
                            result = result.add_with_description(env.to_string(), desc.to_string());
                        }
                    }

                    // Add active help if no prefix
                    if prefix.is_empty() {
                        result = result.add_help_text("Available environments: dev, staging, prod");
                    }

                    Ok(result)
                }),
        )
        .flag(
            Flag::file("config")
                .short('c')
                .usage("Configuration file")
                .default_str("config.yaml")
                .completion(|_ctx, prefix| {
                    // In a real app, you might list files in the config directory
                    let configs = vec![
                        "config.yaml",
                        "config.dev.yaml",
                        "config.staging.yaml",
                        "config.prod.yaml",
                        "secrets.yaml",
                    ];

                    Ok(CompletionResult::new().extend(
                        configs
                            .into_iter()
                            .filter(|c| c.starts_with(prefix))
                            .map(String::from),
                    ))
                }),
        )
        .flag(
            Flag::directory("output")
                .short('o')
                .usage("Output directory for deployment artifacts")
                .completion(|_ctx, prefix| {
                    // In a real app, you might list actual directories
                    let dirs = vec!["./build", "./dist", "./output", "/tmp/deploy"];

                    Ok(CompletionResult::new().extend(
                        dirs.into_iter()
                            .filter(|d| d.starts_with(prefix))
                            .map(String::from),
                    ))
                }),
        )
        .flag(
            Flag::string_slice("service")
                .short('s')
                .usage("Services to deploy (can be specified multiple times)")
                .completion(|ctx, prefix| {
                    // Context-aware completion based on environment
                    let env = ctx.flag_str_or("environment", "dev");

                    let services = match env {
                        "dev" => vec!["api", "web", "worker", "scheduler", "debug-panel"],
                        "staging" => vec!["api", "web", "worker", "scheduler"],
                        "prod" => vec!["api", "web", "worker"],
                        _ => vec!["api", "web"],
                    };

                    let mut result = CompletionResult::new().extend(
                        services
                            .into_iter()
                            .filter(|s| s.starts_with(prefix))
                            .map(String::from),
                    );

                    // Add context-aware help
                    if prefix.is_empty() {
                        result = result
                            .add_help_text(format!("Available services for {} environment", env));
                    }

                    Ok(result)
                }),
        )
        .flag(
            Flag::range("replicas", 1, 10)
                .short('r')
                .usage("Number of replicas to deploy")
                .default_int(2)
                .completion(|_ctx, _prefix| {
                    // Suggest common replica counts
                    Ok(CompletionResult::new()
                        .add_with_description(
                            "1".to_string(),
                            "Single instance (dev/test)".to_string(),
                        )
                        .add_with_description("2".to_string(), "Basic redundancy".to_string())
                        .add_with_description("3".to_string(), "Standard production".to_string())
                        .add_with_description("5".to_string(), "High availability".to_string()))
                }),
        )
        .run(|ctx| {
            let env = ctx.flag_str_or("environment", "dev");
            let config = ctx.flag_str_or("config", "config.yaml");
            let replicas = ctx.flag_int_or("replicas", 2);

            println!("Deploying to {} environment", env);
            println!("Using configuration: {}", config);
            println!("Replica count: {}", replicas);

            if let Some(output) = ctx.flag("output") {
                println!("Output directory: {}", output);
            }

            if let Some(services) = ctx.flag("service") {
                println!("Deploying services: {}", services);
            } else {
                println!("Deploying all services");
            }

            Ok(())
        })
        .build();

    let args: Vec<String> = std::env::args().skip(1).collect();
    if let Err(e) = app.execute(args) {
        eprintln!("Error: {}", e);
        std::process::exit(1);
    }
}

examples/cached_completion_demo.rs (line 79)

fn main() {
    // Create a shared cache with 10-second TTL
    let cache = Arc::new(CompletionCache::new(Duration::from_secs(10)));

    let app = CommandBuilder::new("kubectl")
        .short("Kubernetes command-line tool with cached completions")
        .flag(
            Flag::new("namespace")
                .short('n')
                .usage("The namespace scope for this CLI request")
                .value_type(FlagType::String)
                .default(flag_rs::FlagValue::String("default".to_string())),
        )
        .subcommand({
            let cache_clone = Arc::clone(&cache);
            CommandBuilder::new("get")
                .short("Display one or many resources")
                .subcommand({
                    let cache_for_pods = Arc::clone(&cache_clone);
                    CommandBuilder::new("pods")
                        .short("List pods with cached completion")
                        .arg_completion(move |ctx, prefix| {
                            let start = Instant::now();

                            // Generate cache key
                            let cache_key = CompletionCache::make_key(
                                &["kubectl".to_string(), "get".to_string(), "pods".to_string()],
                                prefix,
                                ctx.flags(),
                            );

                            // Try to get from cache first
                            if let Some(cached_result) = cache_for_pods.get(&cache_key) {
                                eprintln!("✓ Cache hit! Completed in {:?}", start.elapsed());
                                return Ok(cached_result);
                            }

                            eprintln!("✗ Cache miss - fetching completions...");

                            // Perform expensive operation
                            let items = expensive_completion(prefix);
                            let mut result = CompletionResult::new();

                            for item in items {
                                result = result.add_with_description(
                                    item.clone(),
                                    format!(
                                        "Pod in namespace {}",
                                        ctx.flag("namespace").unwrap_or(&"default".to_string())
                                    ),
                                );
                            }

                            // Add contextual help
                            if prefix.is_empty() {
                                result =
                                    result.add_help_text("Tip: Start typing to filter pod names");
                            }

                            // Cache the result
                            cache_for_pods.put(cache_key, result.clone());

                            eprintln!(
                                "✓ Completed in {:?} (cached for future use)",
                                start.elapsed()
                            );
                            Ok(result)
                        })
                        .build()
                })
                .subcommand({
                    let cache_for_services = Arc::clone(&cache_clone);
                    CommandBuilder::new("services")
                        .short("List services with cached completion")
                        .arg_completion(move |ctx, prefix| {
                            let cache_key = CompletionCache::make_key(
                                &[
                                    "kubectl".to_string(),
                                    "get".to_string(),
                                    "services".to_string(),
                                ],
                                prefix,
                                ctx.flags(),
                            );

                            if let Some(cached) = cache_for_services.get(&cache_key) {
                                eprintln!("✓ Using cached service completions");
                                return Ok(cached);
                            }

                            // Simulate expensive operation
                            let services = expensive_completion(prefix);
                            let result = CompletionResult::new().extend(services);

                            cache_for_services.put(cache_key, result.clone());
                            Ok(result)
                        })
                        .build()
                })
                .build()
        })
        .build();

    println!("=== Cached Completion Demo ===\n");
    println!("This demo shows how completion caching improves performance.\n");
    println!("To test completions with caching:");
    println!("1. Set up bash completion:");
    println!(
        "   source <({} completion bash)",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("2. Try tab completion multiple times:");
    println!(
        "   {} get pods n<TAB>     # First time: ~500ms (cache miss)",
        std::env::args().next().unwrap_or_default()
    );
    println!(
        "   {} get pods n<TAB>     # Second time: <1ms (cache hit!)",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("3. Different prefixes have separate cache entries:");
    println!(
        "   {} get pods r<TAB>     # Different prefix = cache miss",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("4. Flags affect the cache key:");
    println!(
        "   {} -n prod get pods n<TAB>  # Different namespace = different cache",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("Note: Cache entries expire after 10 seconds in this demo.\n");
    println!("---\n");

    let args: Vec<String> = std::env::args().skip(1).collect();

    // Handle completion requests
    if std::env::var("KUBECTL_COMPLETE").is_ok() {
        // When testing completions, show cache status
        eprintln!("Cache size: {} entries", cache.size());
    }

    if let Err(e) = app.execute(args) {
        eprintln!("{}", e);
        std::process::exit(1);
    }
}

Additional examples can be found in:

• examples/builder_api_demo.rs
• examples/active_help_demo.rs

pub fn add(self, value: impl Into<String>) -> Self

Adds a completion value without a description

Arguments

• value - The completion value to add

Examples

use flag_rs::completion::CompletionResult;

let result = CompletionResult::new()
    .add("option1")
    .add("option2");

pub fn add_with_description( self, value: impl Into<String>, desc: impl Into<String>, ) -> Self

Adds a completion value with a description

Arguments

• value - The completion value to add
• desc - A description of what this value represents

Examples

use flag_rs::completion::CompletionResult;

let result = CompletionResult::new()
    .add_with_description("--verbose", "Enable verbose output")
    .add_with_description("--quiet", "Suppress output");

Examples found in repository

examples/kubectl.rs (line 36)

fn build_kubectl() -> Command {
    CommandBuilder::new("kubectl")
        .short("Kubernetes command-line tool")
        .long("kubectl controls the Kubernetes cluster manager")
        .subcommand(build_get_command())
        .subcommand(build_describe_command())
        .subcommand(build_delete_command())
        .subcommand(build_completion_command())
        .flag(
            Flag::new("namespace")
                .short('n')
                .usage("Kubernetes namespace")
                .value_type(FlagType::String)
                .default(FlagValue::String("default".to_string())),
        )
        .flag_completion("namespace", |_ctx, prefix| {
            // In a real kubectl, this would query the API server
            let namespaces = get_namespaces_with_descriptions();
            let mut result = CompletionResult::new();

            for (ns_name, description) in namespaces {
                if ns_name.starts_with(prefix) {
                    result = result.add_with_description(ns_name, description);
                }
            }

            Ok(result)
        })
        .build()
}

fn build_get_command() -> Command {
    CommandBuilder::new("get")
        .short("Display one or many resources")
        .long("Display one or many resources. Prints a table of the most important information about the specified resources.")
        .flag(
            Flag::new("limit")
                .short('l')
                .usage("Maximum number of resources to display")
                .value_type(FlagType::String)
        )
        .flag_completion("limit", |_ctx, prefix| {
            let common_limits = vec![
                ("10", "Display 10 items"),
                ("20", "Display 20 items"),
                ("50", "Display 50 items"),
                ("100", "Display 100 items"),
                ("all", "Display all items (no limit)"),
            ];

            let mut result = CompletionResult::new();
            for (limit, description) in common_limits {
                if limit.starts_with(prefix) {
                    result = result.add_with_description(limit.to_string(), description.to_string());
                }
            }

            Ok(result)
        })
        .subcommand(build_get_pods())
        .subcommand(build_get_services())
        .subcommand(build_get_deployments())
        .build()
}

fn build_get_pods() -> Command {
    CommandBuilder::new("pods")
        .aliases(vec!["po", "pod"])
        .short("List pods")
        .arg_completion(|ctx, prefix| {
            // This is the key feature - dynamic completion based on runtime state!
            let namespace = ctx
                .flag("namespace")
                .map(String::as_str)
                .unwrap_or("default");

            // In real kubectl, this would query the K8s API
            let pods = get_pods_with_status(namespace);
            let mut result = CompletionResult::new();

            for (pod_name, status) in pods {
                if pod_name.starts_with(prefix) {
                    result = result.add_with_description(pod_name, status);
                }
            }

            Ok(result)
        })
        .run(|ctx| {
            let namespace = ctx
                .flag("namespace")
                .map(String::as_str)
                .unwrap_or("default");

            println!("Listing pods in namespace: {namespace}");

            if let Some(pod_name) = ctx.args().first() {
                println!("Getting specific pod: {pod_name}");
            } else {
                for pod in get_pods_in_namespace(namespace) {
                    println!("pod/{}", pod);
                }
            }

            Ok(())
        })
        .build()
}

fn build_get_services() -> Command {
    CommandBuilder::new("services")
        .aliases(vec!["svc", "service"])
        .short("List services")
        .arg_completion(|ctx, prefix| {
            let namespace = ctx
                .flag("namespace")
                .map(String::as_str)
                .unwrap_or("default");

            let services = get_services_in_namespace(namespace);
            Ok(CompletionResult::new()
                .extend(services.into_iter().filter(|svc| svc.starts_with(prefix))))
        })
        .run(|ctx| {
            let namespace = ctx
                .flag("namespace")
                .map(String::as_str)
                .unwrap_or("default");

            println!("Listing services in namespace: {namespace}");
            Ok(())
        })
        .build()
}

fn build_get_deployments() -> Command {
    CommandBuilder::new("deployments")
        .aliases(vec!["deploy", "deployment"])
        .short("List deployments")
        .run(|ctx| {
            let namespace = ctx
                .flag("namespace")
                .map(String::as_str)
                .unwrap_or("default");

            println!("Listing deployments in namespace: {namespace}");
            Ok(())
        })
        .build()
}

fn build_describe_command() -> Command {
    CommandBuilder::new("describe")
        .short("Show details of a specific resource")
        .flag(
            Flag::new("output")
                .short('o')
                .usage("Output format")
                .value_type(FlagType::String),
        )
        .run(|_ctx| {
            println!("Describe command - add resource type subcommands");
            Ok(())
        })
        .build()
}

fn build_delete_command() -> Command {
    CommandBuilder::new("delete")
        .short("Delete resources")
        .run(|_ctx| {
            println!("Delete command - add resource type subcommands");
            Ok(())
        })
        .build()
}

// Mock functions that would normally query the Kubernetes API
fn get_namespaces_with_descriptions() -> Vec<(String, String)> {
    vec![
        (
            "default".to_string(),
            "Default namespace for user workloads".to_string(),
        ),
        (
            "kube-system".to_string(),
            "Kubernetes system components".to_string(),
        ),
        (
            "kube-public".to_string(),
            "Public resources accessible to all users".to_string(),
        ),
        (
            "development".to_string(),
            "Development environment".to_string(),
        ),
        (
            "staging".to_string(),
            "Staging environment for pre-production testing".to_string(),
        ),
        (
            "production".to_string(),
            "Production environment (CAUTION)".to_string(),
        ),
    ]
}

fn get_pods_with_status(namespace: &str) -> Vec<(String, String)> {
    use std::time::{SystemTime, UNIX_EPOCH};

    // Generate random suffix based on current time
    let timestamp = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap()
        .as_secs();

    // Simple pseudo-random generation
    let rand1 = ((timestamp * 1_103_515_245 + 12345) / 65536) % 100_000;
    let rand2 = ((rand1 * 1_103_515_245 + 12345) / 65536) % 100_000;
    let rand3 = ((rand2 * 1_103_515_245 + 12345) / 65536) % 100_000;

    match namespace {
        "default" => vec![
            (
                format!("nginx-deployment-7fb96c846b-{:05x}", rand1),
                "Running (2/2 containers)".to_string(),
            ),
            (
                format!("nginx-deployment-7fb96c846b-{:05x}", rand2),
                "Running (2/2 containers)".to_string(),
            ),
            (
                "redis-master-0".to_string(),
                "Running (1/1 containers)".to_string(),
            ),
            (
                "redis-slave-0".to_string(),
                "Running (1/1 containers)".to_string(),
            ),
            ("redis-slave-1".to_string(), "Pending".to_string()),
        ],
        "kube-system" => vec![
            (
                format!("coredns-5d78c9869d-{:05x}", rand1),
                "Running (1/1 containers)".to_string(),
            ),
            (
                format!("coredns-5d78c9869d-{:05x}", rand2),
                "Running (1/1 containers)".to_string(),
            ),
            ("etcd-minikube".to_string(), "Running".to_string()),
            ("kube-apiserver-minikube".to_string(), "Running".to_string()),
            (
                "kube-controller-manager-minikube".to_string(),
                "Running".to_string(),
            ),
            (format!("kube-proxy-{:05x}", rand3), "Running".to_string()),
            ("kube-scheduler-minikube".to_string(), "Running".to_string()),
        ],
        _ => vec![],
    }
}

fn get_pods_in_namespace(namespace: &str) -> Vec<String> {
    use std::time::{SystemTime, UNIX_EPOCH};

    // Generate random suffix based on current time
    let timestamp = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap()
        .as_secs();

    // Simple pseudo-random generation
    let rand1 = ((timestamp * 1_103_515_245 + 12345) / 65536) % 100_000;
    let rand2 = ((rand1 * 1_103_515_245 + 12345) / 65536) % 100_000;
    let rand3 = ((rand2 * 1_103_515_245 + 12345) / 65536) % 100_000;

    match namespace {
        "default" => vec![
            format!("nginx-deployment-7fb96c846b-{:05x}", rand1),
            format!("nginx-deployment-7fb96c846b-{:05x}", rand2),
            format!("redis-master-0"),
            format!("redis-slave-0"),
            format!("redis-slave-1"),
        ],
        "kube-system" => vec![
            format!("coredns-5d78c9869d-{:05x}", rand1),
            format!("coredns-5d78c9869d-{:05x}", rand2),
            format!("etcd-minikube"),
            format!("kube-apiserver-minikube"),
            format!("kube-controller-manager-minikube"),
            format!("kube-proxy-{:05x}", rand3),
            format!("kube-scheduler-minikube"),
        ],
        _ => vec![],
    }
}

fn get_services_in_namespace(namespace: &str) -> Vec<String> {
    match namespace {
        "default" => vec![
            "kubernetes".to_string(),
            "nginx-service".to_string(),
            "redis-master".to_string(),
            "redis-slave".to_string(),
        ],
        "kube-system" => vec!["kube-dns".to_string()],
        _ => vec![],
    }
}

fn build_completion_command() -> Command {
    CommandBuilder::new("completion")
        .short("Generate shell completion scripts")
        .long("Generate shell completion scripts for kubectl")
        .arg_completion(|_ctx, prefix| {
            let shells = vec![
                ("bash", "Bash shell completion"),
                ("zsh", "Zsh shell completion"),
                ("fish", "Fish shell completion"),
            ];

            let mut result = CompletionResult::new();
            for (shell, description) in shells {
                if shell.starts_with(prefix) {
                    result =
                        result.add_with_description(shell.to_string(), description.to_string());
                }
            }

            Ok(result)
        })
        .run(|ctx| {
            let shell_name = ctx.args().first().ok_or_else(|| {
                flag_rs::Error::ArgumentParsing(
                    "shell name required (bash, zsh, or fish)".to_string(),
                )
            })?;

            let shell = match shell_name.as_str() {
                "bash" => Shell::Bash,
                "zsh" => Shell::Zsh,
                "fish" => Shell::Fish,
                _ => {
                    return Err(flag_rs::Error::ArgumentParsing(format!(
                        "unsupported shell: {}",
                        shell_name
                    )));
                }
            };

            // In a real app, you'd get the root command from a shared reference
            // For this example, we'll recreate it
            let root = build_kubectl();
            println!("{}", root.generate_completion(shell));

            Ok(())
        })
        .build()
}

examples/benchmark.rs (line 235)

fn bench_completion() {
    println!("\n=== Completion Benchmarks ===");

    let cli = CommandBuilder::new("comp")
        .arg_completion(|_ctx, prefix| {
            let items: Vec<String> = (0..100)
                .map(|i| format!("item{i:03}"))
                .filter(|item| item.starts_with(prefix))
                .collect();
            Ok(CompletionResult::new().extend(items))
        })
        .build();

    let ctx = flag_rs::Context::new(vec!["comp".to_string()]);

    let bench = Benchmark::new("Complete with empty prefix (100 items)", 1_000);
    let duration = bench.run(|| {
        let _ = cli.get_completions(&ctx, "", None);
    });
    bench.report(duration);

    let bench = Benchmark::new("Complete with prefix (filtered)", 1_000);
    let duration = bench.run(|| {
        let _ = cli.get_completions(&ctx, "item05", None);
    });
    bench.report(duration);

    // Test completion with descriptions
    let cli_desc = CommandBuilder::new("comp_desc")
        .arg_completion(|_ctx, prefix| {
            let mut result = CompletionResult::new();
            for i in 0..50 {
                let item = format!("option{i:02}");
                if item.starts_with(prefix) {
                    result =
                        result.add_with_description(item, format!("Description for option {i}"));
                }
            }
            Ok(result)
        })
        .build();

    let bench = Benchmark::new("Complete with descriptions (50 items)", 1_000);
    let duration = bench.run(|| {
        let _ = cli_desc.get_completions(&ctx, "", None);
    });
    bench.report(duration);
}

examples/test_completion.rs (line 22)

fn main() {
    let cmd = CommandBuilder::new("test")
        .short("Test completion with descriptions")
        .flag(
            Flag::new("environment")
                .short('e')
                .usage("Target environment")
                .value_type(FlagType::String),
        )
        .flag_completion("environment", |_ctx, prefix| {
            let mut result = CompletionResult::new();
            let envs = vec![
                ("dev", "Development environment - safe for testing"),
                ("staging", "Staging environment - mirror of production"),
                ("production", "Production environment - BE CAREFUL!"),
            ];

            for (env, desc) in envs {
                if env.starts_with(prefix) {
                    result = result.add_with_description(env, desc);
                }
            }

            Ok(result)
        })
        .subcommand(
            CommandBuilder::new("deploy")
                .short("Deploy the application")
                .long("Deploy the application to the specified environment")
                .build(),
        )
        .subcommand(
            CommandBuilder::new("rollback")
                .short("Rollback to previous version")
                .long("Rollback the application to the previous deployed version")
                .build(),
        )
        .build();

    // Test completion output
    if let Ok(shell_type) = std::env::var("TEST_COMPLETE") {
        // For testing, override shell type to "display" to see formatted output
        let display_mode = std::env::var("DISPLAY_MODE").is_ok();
        let args: Vec<String> = std::env::args().skip(1).collect();

        if display_mode {
            // This is a hack for testing - normally shells would handle this
            println!("Display mode - showing formatted completions:");
            match cmd.handle_completion_request(&args) {
                Ok(completions) => {
                    for completion in completions {
                        println!("{}", completion);
                    }
                }
                Err(e) => eprintln!("Completion error: {}", e),
            }
        } else {
            match cmd.handle_completion_request(&args) {
                Ok(completions) => {
                    println!("Shell type: {}", shell_type);
                    println!("Completions:");
                    for completion in completions {
                        println!("{}", completion);
                    }
                }
                Err(e) => eprintln!("Completion error: {}", e),
            }
        }
    } else {
        let args: Vec<String> = std::env::args().skip(1).collect();
        if let Err(e) = cmd.execute(args) {
            eprintln!("Error: {}", e);
            std::process::exit(1);
        }
    }
}

examples/timeout_completion_demo.rs (lines 81-88)

fn main() {
    let app = CommandBuilder::new("cloud-cli")
        .short("Cloud CLI with timeout-protected completions")
        .flag(
            Flag::new("region")
                .short('r')
                .usage("Cloud region")
                .value_type(FlagType::String)
                .default(flag_rs::FlagValue::String("us-east-1".to_string())),
        )
        .subcommand(
            CommandBuilder::new("instances")
                .short("Manage cloud instances")
                .subcommand(
                    CommandBuilder::new("list")
                        .short("List instances (fast completion)")
                        .arg_completion(|_ctx, prefix| {
                            // Fast completion - no timeout needed
                            let instances = vec![
                                "web-server-001",
                                "web-server-002",
                                "db-primary",
                                "db-replica",
                                "cache-node-1",
                                "cache-node-2",
                            ];

                            Ok(CompletionResult::new().extend(
                                instances
                                    .into_iter()
                                    .filter(|i| i.starts_with(prefix))
                                    .map(String::from),
                            ))
                        })
                        .build(),
                )
                .subcommand(
                    CommandBuilder::new("describe")
                        .short("Describe instance (slow completion with timeout)")
                        .arg_completion({
                            // Wrap slow completion with timeout
                            make_timeout_completion(
                                Duration::from_millis(500), // 500ms timeout
                                |ctx, prefix| {
                                    eprintln!("Fetching instance details from API...");

                                    // Simulate slow API call (1 second)
                                    let instances = slow_completion(prefix, 1000);

                                    let mut result = CompletionResult::new();
                                    for instance in instances {
                                        result = result.add_with_description(
                                            instance.clone(),
                                            format!(
                                                "Instance in region {}",
                                                ctx.flag("region")
                                                    .unwrap_or(&"us-east-1".to_string())
                                            ),
                                        );
                                    }

                                    if prefix.is_empty() {
                                        result = result.add_help_text(
                                            "Fetching live instance data from cloud API...",
                                        );
                                    }

                                    Ok(result)
                                },
                            )
                        })
                        .build(),
                )
                .subcommand(
                    CommandBuilder::new("create")
                        .short("Create instance (very slow completion)")
                        .arg_completion({
                            // Use default timeout (2 seconds)
                            make_timeout_completion(DEFAULT_COMPLETION_TIMEOUT, |_ctx, prefix| {
                                eprintln!("Checking available instance types...");

                                // Simulate very slow operation (3 seconds)
                                let types = slow_completion(prefix, 3000);

                                Ok(CompletionResult::new()
                                    .extend(types)
                                    .add_help_text("Available instance types"))
                            })
                        })
                        .build(),
                )
                .build(),
        )
        .build();

    println!("=== Timeout Completion Demo ===\n");
    println!("This demo shows how timeouts protect against slow completion operations.\n");
    println!("To test timeout handling:");
    println!("1. Set up bash completion:");
    println!(
        "   source <({} completion bash)",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("2. Test different completion speeds:");
    println!();
    println!("   Fast (no timeout needed):");
    println!(
        "   {} instances list <TAB>",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("   Slow (500ms timeout, 1s operation - will timeout):");
    println!(
        "   {} instances describe <TAB>",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("   Very slow (2s timeout, 3s operation - will timeout):");
    println!(
        "   {} instances create <TAB>",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("When a timeout occurs, you'll see:");
    println!("- A warning message about the timeout");
    println!("- Any partial results that were available");
    println!("- Suggestion to use a more specific prefix");
    println!("\n---\n");

    let args: Vec<String> = std::env::args().skip(1).collect();
    if let Err(e) = app.execute(args) {
        eprintln!("{}", e);
        std::process::exit(1);
    }
}

examples/flag_completion_demo.rs (line 23)

fn main() {
    let app = CommandBuilder::new("deploy")
        .short("Deploy application to various environments")
        .flag(
            Flag::choice("environment", &["dev", "staging", "prod"])
                .short('e')
                .usage("Target environment")
                .required()
                .completion(|_ctx, prefix| {
                    // Dynamic completion - could check available environments
                    let environments = vec![
                        ("dev", "Development environment"),
                        ("staging", "Staging environment (pre-production)"),
                        ("prod", "Production environment"),
                    ];

                    let mut result = CompletionResult::new();
                    for (env, desc) in environments {
                        if env.starts_with(prefix) {
                            result = result.add_with_description(env.to_string(), desc.to_string());
                        }
                    }

                    // Add active help if no prefix
                    if prefix.is_empty() {
                        result = result.add_help_text("Available environments: dev, staging, prod");
                    }

                    Ok(result)
                }),
        )
        .flag(
            Flag::file("config")
                .short('c')
                .usage("Configuration file")
                .default_str("config.yaml")
                .completion(|_ctx, prefix| {
                    // In a real app, you might list files in the config directory
                    let configs = vec![
                        "config.yaml",
                        "config.dev.yaml",
                        "config.staging.yaml",
                        "config.prod.yaml",
                        "secrets.yaml",
                    ];

                    Ok(CompletionResult::new().extend(
                        configs
                            .into_iter()
                            .filter(|c| c.starts_with(prefix))
                            .map(String::from),
                    ))
                }),
        )
        .flag(
            Flag::directory("output")
                .short('o')
                .usage("Output directory for deployment artifacts")
                .completion(|_ctx, prefix| {
                    // In a real app, you might list actual directories
                    let dirs = vec!["./build", "./dist", "./output", "/tmp/deploy"];

                    Ok(CompletionResult::new().extend(
                        dirs.into_iter()
                            .filter(|d| d.starts_with(prefix))
                            .map(String::from),
                    ))
                }),
        )
        .flag(
            Flag::string_slice("service")
                .short('s')
                .usage("Services to deploy (can be specified multiple times)")
                .completion(|ctx, prefix| {
                    // Context-aware completion based on environment
                    let env = ctx.flag_str_or("environment", "dev");

                    let services = match env {
                        "dev" => vec!["api", "web", "worker", "scheduler", "debug-panel"],
                        "staging" => vec!["api", "web", "worker", "scheduler"],
                        "prod" => vec!["api", "web", "worker"],
                        _ => vec!["api", "web"],
                    };

                    let mut result = CompletionResult::new().extend(
                        services
                            .into_iter()
                            .filter(|s| s.starts_with(prefix))
                            .map(String::from),
                    );

                    // Add context-aware help
                    if prefix.is_empty() {
                        result = result
                            .add_help_text(format!("Available services for {} environment", env));
                    }

                    Ok(result)
                }),
        )
        .flag(
            Flag::range("replicas", 1, 10)
                .short('r')
                .usage("Number of replicas to deploy")
                .default_int(2)
                .completion(|_ctx, _prefix| {
                    // Suggest common replica counts
                    Ok(CompletionResult::new()
                        .add_with_description(
                            "1".to_string(),
                            "Single instance (dev/test)".to_string(),
                        )
                        .add_with_description("2".to_string(), "Basic redundancy".to_string())
                        .add_with_description("3".to_string(), "Standard production".to_string())
                        .add_with_description("5".to_string(), "High availability".to_string()))
                }),
        )
        .run(|ctx| {
            let env = ctx.flag_str_or("environment", "dev");
            let config = ctx.flag_str_or("config", "config.yaml");
            let replicas = ctx.flag_int_or("replicas", 2);

            println!("Deploying to {} environment", env);
            println!("Using configuration: {}", config);
            println!("Replica count: {}", replicas);

            if let Some(output) = ctx.flag("output") {
                println!("Output directory: {}", output);
            }

            if let Some(services) = ctx.flag("service") {
                println!("Deploying services: {}", services);
            } else {
                println!("Deploying all services");
            }

            Ok(())
        })
        .build();

    let args: Vec<String> = std::env::args().skip(1).collect();
    if let Err(e) = app.execute(args) {
        eprintln!("Error: {}", e);
        std::process::exit(1);
    }
}

examples/cached_completion_demo.rs (lines 82-88)

fn main() {
    // Create a shared cache with 10-second TTL
    let cache = Arc::new(CompletionCache::new(Duration::from_secs(10)));

    let app = CommandBuilder::new("kubectl")
        .short("Kubernetes command-line tool with cached completions")
        .flag(
            Flag::new("namespace")
                .short('n')
                .usage("The namespace scope for this CLI request")
                .value_type(FlagType::String)
                .default(flag_rs::FlagValue::String("default".to_string())),
        )
        .subcommand({
            let cache_clone = Arc::clone(&cache);
            CommandBuilder::new("get")
                .short("Display one or many resources")
                .subcommand({
                    let cache_for_pods = Arc::clone(&cache_clone);
                    CommandBuilder::new("pods")
                        .short("List pods with cached completion")
                        .arg_completion(move |ctx, prefix| {
                            let start = Instant::now();

                            // Generate cache key
                            let cache_key = CompletionCache::make_key(
                                &["kubectl".to_string(), "get".to_string(), "pods".to_string()],
                                prefix,
                                ctx.flags(),
                            );

                            // Try to get from cache first
                            if let Some(cached_result) = cache_for_pods.get(&cache_key) {
                                eprintln!("✓ Cache hit! Completed in {:?}", start.elapsed());
                                return Ok(cached_result);
                            }

                            eprintln!("✗ Cache miss - fetching completions...");

                            // Perform expensive operation
                            let items = expensive_completion(prefix);
                            let mut result = CompletionResult::new();

                            for item in items {
                                result = result.add_with_description(
                                    item.clone(),
                                    format!(
                                        "Pod in namespace {}",
                                        ctx.flag("namespace").unwrap_or(&"default".to_string())
                                    ),
                                );
                            }

                            // Add contextual help
                            if prefix.is_empty() {
                                result =
                                    result.add_help_text("Tip: Start typing to filter pod names");
                            }

                            // Cache the result
                            cache_for_pods.put(cache_key, result.clone());

                            eprintln!(
                                "✓ Completed in {:?} (cached for future use)",
                                start.elapsed()
                            );
                            Ok(result)
                        })
                        .build()
                })
                .subcommand({
                    let cache_for_services = Arc::clone(&cache_clone);
                    CommandBuilder::new("services")
                        .short("List services with cached completion")
                        .arg_completion(move |ctx, prefix| {
                            let cache_key = CompletionCache::make_key(
                                &[
                                    "kubectl".to_string(),
                                    "get".to_string(),
                                    "services".to_string(),
                                ],
                                prefix,
                                ctx.flags(),
                            );

                            if let Some(cached) = cache_for_services.get(&cache_key) {
                                eprintln!("✓ Using cached service completions");
                                return Ok(cached);
                            }

                            // Simulate expensive operation
                            let services = expensive_completion(prefix);
                            let result = CompletionResult::new().extend(services);

                            cache_for_services.put(cache_key, result.clone());
                            Ok(result)
                        })
                        .build()
                })
                .build()
        })
        .build();

    println!("=== Cached Completion Demo ===\n");
    println!("This demo shows how completion caching improves performance.\n");
    println!("To test completions with caching:");
    println!("1. Set up bash completion:");
    println!(
        "   source <({} completion bash)",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("2. Try tab completion multiple times:");
    println!(
        "   {} get pods n<TAB>     # First time: ~500ms (cache miss)",
        std::env::args().next().unwrap_or_default()
    );
    println!(
        "   {} get pods n<TAB>     # Second time: <1ms (cache hit!)",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("3. Different prefixes have separate cache entries:");
    println!(
        "   {} get pods r<TAB>     # Different prefix = cache miss",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("4. Flags affect the cache key:");
    println!(
        "   {} -n prod get pods n<TAB>  # Different namespace = different cache",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("Note: Cache entries expire after 10 seconds in this demo.\n");
    println!("---\n");

    let args: Vec<String> = std::env::args().skip(1).collect();

    // Handle completion requests
    if std::env::var("KUBECTL_COMPLETE").is_ok() {
        // When testing completions, show cache status
        eprintln!("Cache size: {} entries", cache.size());
    }

    if let Err(e) = app.execute(args) {
        eprintln!("{}", e);
        std::process::exit(1);
    }
}

Additional examples can be found in:

• examples/builder_api_demo.rs
• examples/active_help_demo.rs

pub fn extend<I: IntoIterator<Item = String>>(self, values: I) -> Self

Adds multiple completion values without descriptions

Arguments

• values - An iterator of completion values

Examples

use flag_rs::completion::CompletionResult;

let options = vec!["opt1".to_string(), "opt2".to_string()];
let result = CompletionResult::new().extend(options);

Examples found in repository

examples/kubectl.rs (line 135)

fn build_get_services() -> Command {
    CommandBuilder::new("services")
        .aliases(vec!["svc", "service"])
        .short("List services")
        .arg_completion(|ctx, prefix| {
            let namespace = ctx
                .flag("namespace")
                .map(String::as_str)
                .unwrap_or("default");

            let services = get_services_in_namespace(namespace);
            Ok(CompletionResult::new()
                .extend(services.into_iter().filter(|svc| svc.starts_with(prefix))))
        })
        .run(|ctx| {
            let namespace = ctx
                .flag("namespace")
                .map(String::as_str)
                .unwrap_or("default");

            println!("Listing services in namespace: {namespace}");
            Ok(())
        })
        .build()
}

examples/benchmark.rs (line 209)

fn bench_completion() {
    println!("\n=== Completion Benchmarks ===");

    let cli = CommandBuilder::new("comp")
        .arg_completion(|_ctx, prefix| {
            let items: Vec<String> = (0..100)
                .map(|i| format!("item{i:03}"))
                .filter(|item| item.starts_with(prefix))
                .collect();
            Ok(CompletionResult::new().extend(items))
        })
        .build();

    let ctx = flag_rs::Context::new(vec!["comp".to_string()]);

    let bench = Benchmark::new("Complete with empty prefix (100 items)", 1_000);
    let duration = bench.run(|| {
        let _ = cli.get_completions(&ctx, "", None);
    });
    bench.report(duration);

    let bench = Benchmark::new("Complete with prefix (filtered)", 1_000);
    let duration = bench.run(|| {
        let _ = cli.get_completions(&ctx, "item05", None);
    });
    bench.report(duration);

    // Test completion with descriptions
    let cli_desc = CommandBuilder::new("comp_desc")
        .arg_completion(|_ctx, prefix| {
            let mut result = CompletionResult::new();
            for i in 0..50 {
                let item = format!("option{i:02}");
                if item.starts_with(prefix) {
                    result =
                        result.add_with_description(item, format!("Description for option {i}"));
                }
            }
            Ok(result)
        })
        .build();

    let bench = Benchmark::new("Complete with descriptions (50 items)", 1_000);
    let duration = bench.run(|| {
        let _ = cli_desc.get_completions(&ctx, "", None);
    });
    bench.report(duration);
}

examples/timeout_completion_demo.rs (lines 57-62)

fn main() {
    let app = CommandBuilder::new("cloud-cli")
        .short("Cloud CLI with timeout-protected completions")
        .flag(
            Flag::new("region")
                .short('r')
                .usage("Cloud region")
                .value_type(FlagType::String)
                .default(flag_rs::FlagValue::String("us-east-1".to_string())),
        )
        .subcommand(
            CommandBuilder::new("instances")
                .short("Manage cloud instances")
                .subcommand(
                    CommandBuilder::new("list")
                        .short("List instances (fast completion)")
                        .arg_completion(|_ctx, prefix| {
                            // Fast completion - no timeout needed
                            let instances = vec![
                                "web-server-001",
                                "web-server-002",
                                "db-primary",
                                "db-replica",
                                "cache-node-1",
                                "cache-node-2",
                            ];

                            Ok(CompletionResult::new().extend(
                                instances
                                    .into_iter()
                                    .filter(|i| i.starts_with(prefix))
                                    .map(String::from),
                            ))
                        })
                        .build(),
                )
                .subcommand(
                    CommandBuilder::new("describe")
                        .short("Describe instance (slow completion with timeout)")
                        .arg_completion({
                            // Wrap slow completion with timeout
                            make_timeout_completion(
                                Duration::from_millis(500), // 500ms timeout
                                |ctx, prefix| {
                                    eprintln!("Fetching instance details from API...");

                                    // Simulate slow API call (1 second)
                                    let instances = slow_completion(prefix, 1000);

                                    let mut result = CompletionResult::new();
                                    for instance in instances {
                                        result = result.add_with_description(
                                            instance.clone(),
                                            format!(
                                                "Instance in region {}",
                                                ctx.flag("region")
                                                    .unwrap_or(&"us-east-1".to_string())
                                            ),
                                        );
                                    }

                                    if prefix.is_empty() {
                                        result = result.add_help_text(
                                            "Fetching live instance data from cloud API...",
                                        );
                                    }

                                    Ok(result)
                                },
                            )
                        })
                        .build(),
                )
                .subcommand(
                    CommandBuilder::new("create")
                        .short("Create instance (very slow completion)")
                        .arg_completion({
                            // Use default timeout (2 seconds)
                            make_timeout_completion(DEFAULT_COMPLETION_TIMEOUT, |_ctx, prefix| {
                                eprintln!("Checking available instance types...");

                                // Simulate very slow operation (3 seconds)
                                let types = slow_completion(prefix, 3000);

                                Ok(CompletionResult::new()
                                    .extend(types)
                                    .add_help_text("Available instance types"))
                            })
                        })
                        .build(),
                )
                .build(),
        )
        .build();

    println!("=== Timeout Completion Demo ===\n");
    println!("This demo shows how timeouts protect against slow completion operations.\n");
    println!("To test timeout handling:");
    println!("1. Set up bash completion:");
    println!(
        "   source <({} completion bash)",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("2. Test different completion speeds:");
    println!();
    println!("   Fast (no timeout needed):");
    println!(
        "   {} instances list <TAB>",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("   Slow (500ms timeout, 1s operation - will timeout):");
    println!(
        "   {} instances describe <TAB>",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("   Very slow (2s timeout, 3s operation - will timeout):");
    println!(
        "   {} instances create <TAB>",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("When a timeout occurs, you'll see:");
    println!("- A warning message about the timeout");
    println!("- Any partial results that were available");
    println!("- Suggestion to use a more specific prefix");
    println!("\n---\n");

    let args: Vec<String> = std::env::args().skip(1).collect();
    if let Err(e) = app.execute(args) {
        eprintln!("{}", e);
        std::process::exit(1);
    }
}

examples/flag_completion_demo.rs (lines 50-55)

fn main() {
    let app = CommandBuilder::new("deploy")
        .short("Deploy application to various environments")
        .flag(
            Flag::choice("environment", &["dev", "staging", "prod"])
                .short('e')
                .usage("Target environment")
                .required()
                .completion(|_ctx, prefix| {
                    // Dynamic completion - could check available environments
                    let environments = vec![
                        ("dev", "Development environment"),
                        ("staging", "Staging environment (pre-production)"),
                        ("prod", "Production environment"),
                    ];

                    let mut result = CompletionResult::new();
                    for (env, desc) in environments {
                        if env.starts_with(prefix) {
                            result = result.add_with_description(env.to_string(), desc.to_string());
                        }
                    }

                    // Add active help if no prefix
                    if prefix.is_empty() {
                        result = result.add_help_text("Available environments: dev, staging, prod");
                    }

                    Ok(result)
                }),
        )
        .flag(
            Flag::file("config")
                .short('c')
                .usage("Configuration file")
                .default_str("config.yaml")
                .completion(|_ctx, prefix| {
                    // In a real app, you might list files in the config directory
                    let configs = vec![
                        "config.yaml",
                        "config.dev.yaml",
                        "config.staging.yaml",
                        "config.prod.yaml",
                        "secrets.yaml",
                    ];

                    Ok(CompletionResult::new().extend(
                        configs
                            .into_iter()
                            .filter(|c| c.starts_with(prefix))
                            .map(String::from),
                    ))
                }),
        )
        .flag(
            Flag::directory("output")
                .short('o')
                .usage("Output directory for deployment artifacts")
                .completion(|_ctx, prefix| {
                    // In a real app, you might list actual directories
                    let dirs = vec!["./build", "./dist", "./output", "/tmp/deploy"];

                    Ok(CompletionResult::new().extend(
                        dirs.into_iter()
                            .filter(|d| d.starts_with(prefix))
                            .map(String::from),
                    ))
                }),
        )
        .flag(
            Flag::string_slice("service")
                .short('s')
                .usage("Services to deploy (can be specified multiple times)")
                .completion(|ctx, prefix| {
                    // Context-aware completion based on environment
                    let env = ctx.flag_str_or("environment", "dev");

                    let services = match env {
                        "dev" => vec!["api", "web", "worker", "scheduler", "debug-panel"],
                        "staging" => vec!["api", "web", "worker", "scheduler"],
                        "prod" => vec!["api", "web", "worker"],
                        _ => vec!["api", "web"],
                    };

                    let mut result = CompletionResult::new().extend(
                        services
                            .into_iter()
                            .filter(|s| s.starts_with(prefix))
                            .map(String::from),
                    );

                    // Add context-aware help
                    if prefix.is_empty() {
                        result = result
                            .add_help_text(format!("Available services for {} environment", env));
                    }

                    Ok(result)
                }),
        )
        .flag(
            Flag::range("replicas", 1, 10)
                .short('r')
                .usage("Number of replicas to deploy")
                .default_int(2)
                .completion(|_ctx, _prefix| {
                    // Suggest common replica counts
                    Ok(CompletionResult::new()
                        .add_with_description(
                            "1".to_string(),
                            "Single instance (dev/test)".to_string(),
                        )
                        .add_with_description("2".to_string(), "Basic redundancy".to_string())
                        .add_with_description("3".to_string(), "Standard production".to_string())
                        .add_with_description("5".to_string(), "High availability".to_string()))
                }),
        )
        .run(|ctx| {
            let env = ctx.flag_str_or("environment", "dev");
            let config = ctx.flag_str_or("config", "config.yaml");
            let replicas = ctx.flag_int_or("replicas", 2);

            println!("Deploying to {} environment", env);
            println!("Using configuration: {}", config);
            println!("Replica count: {}", replicas);

            if let Some(output) = ctx.flag("output") {
                println!("Output directory: {}", output);
            }

            if let Some(services) = ctx.flag("service") {
                println!("Deploying services: {}", services);
            } else {
                println!("Deploying all services");
            }

            Ok(())
        })
        .build();

    let args: Vec<String> = std::env::args().skip(1).collect();
    if let Err(e) = app.execute(args) {
        eprintln!("Error: {}", e);
        std::process::exit(1);
    }
}

examples/cached_completion_demo.rs (line 130)

fn main() {
    // Create a shared cache with 10-second TTL
    let cache = Arc::new(CompletionCache::new(Duration::from_secs(10)));

    let app = CommandBuilder::new("kubectl")
        .short("Kubernetes command-line tool with cached completions")
        .flag(
            Flag::new("namespace")
                .short('n')
                .usage("The namespace scope for this CLI request")
                .value_type(FlagType::String)
                .default(flag_rs::FlagValue::String("default".to_string())),
        )
        .subcommand({
            let cache_clone = Arc::clone(&cache);
            CommandBuilder::new("get")
                .short("Display one or many resources")
                .subcommand({
                    let cache_for_pods = Arc::clone(&cache_clone);
                    CommandBuilder::new("pods")
                        .short("List pods with cached completion")
                        .arg_completion(move |ctx, prefix| {
                            let start = Instant::now();

                            // Generate cache key
                            let cache_key = CompletionCache::make_key(
                                &["kubectl".to_string(), "get".to_string(), "pods".to_string()],
                                prefix,
                                ctx.flags(),
                            );

                            // Try to get from cache first
                            if let Some(cached_result) = cache_for_pods.get(&cache_key) {
                                eprintln!("✓ Cache hit! Completed in {:?}", start.elapsed());
                                return Ok(cached_result);
                            }

                            eprintln!("✗ Cache miss - fetching completions...");

                            // Perform expensive operation
                            let items = expensive_completion(prefix);
                            let mut result = CompletionResult::new();

                            for item in items {
                                result = result.add_with_description(
                                    item.clone(),
                                    format!(
                                        "Pod in namespace {}",
                                        ctx.flag("namespace").unwrap_or(&"default".to_string())
                                    ),
                                );
                            }

                            // Add contextual help
                            if prefix.is_empty() {
                                result =
                                    result.add_help_text("Tip: Start typing to filter pod names");
                            }

                            // Cache the result
                            cache_for_pods.put(cache_key, result.clone());

                            eprintln!(
                                "✓ Completed in {:?} (cached for future use)",
                                start.elapsed()
                            );
                            Ok(result)
                        })
                        .build()
                })
                .subcommand({
                    let cache_for_services = Arc::clone(&cache_clone);
                    CommandBuilder::new("services")
                        .short("List services with cached completion")
                        .arg_completion(move |ctx, prefix| {
                            let cache_key = CompletionCache::make_key(
                                &[
                                    "kubectl".to_string(),
                                    "get".to_string(),
                                    "services".to_string(),
                                ],
                                prefix,
                                ctx.flags(),
                            );

                            if let Some(cached) = cache_for_services.get(&cache_key) {
                                eprintln!("✓ Using cached service completions");
                                return Ok(cached);
                            }

                            // Simulate expensive operation
                            let services = expensive_completion(prefix);
                            let result = CompletionResult::new().extend(services);

                            cache_for_services.put(cache_key, result.clone());
                            Ok(result)
                        })
                        .build()
                })
                .build()
        })
        .build();

    println!("=== Cached Completion Demo ===\n");
    println!("This demo shows how completion caching improves performance.\n");
    println!("To test completions with caching:");
    println!("1. Set up bash completion:");
    println!(
        "   source <({} completion bash)",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("2. Try tab completion multiple times:");
    println!(
        "   {} get pods n<TAB>     # First time: ~500ms (cache miss)",
        std::env::args().next().unwrap_or_default()
    );
    println!(
        "   {} get pods n<TAB>     # Second time: <1ms (cache hit!)",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("3. Different prefixes have separate cache entries:");
    println!(
        "   {} get pods r<TAB>     # Different prefix = cache miss",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("4. Flags affect the cache key:");
    println!(
        "   {} -n prod get pods n<TAB>  # Different namespace = different cache",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("Note: Cache entries expire after 10 seconds in this demo.\n");
    println!("---\n");

    let args: Vec<String> = std::env::args().skip(1).collect();

    // Handle completion requests
    if std::env::var("KUBECTL_COMPLETE").is_ok() {
        // When testing completions, show cache status
        eprintln!("Cache size: {} entries", cache.size());
    }

    if let Err(e) = app.execute(args) {
        eprintln!("{}", e);
        std::process::exit(1);
    }
}

examples/builder_api_demo.rs (lines 67-71)

fn main() {
    // Demonstrates all the new builder API improvements
    let app = CommandBuilder::new("app")
        .short("Modern CLI app with improved API")
        .long(
            "This example showcases the builder API improvements including:\n\
               - Type-specific flag constructors\n\
               - Inline flag completions\n\
               - Bulk flag/subcommand methods\n\
               - Type-safe context access",
        )
        // Bulk flag addition
        .flags(vec![
            // Type-specific constructors
            Flag::bool("verbose")
                .short('v')
                .usage("Enable verbose output")
                .default_bool(false),
            Flag::bool("quiet").short('q').usage("Suppress all output"),
            Flag::int("threads")
                .short('t')
                .usage("Number of worker threads")
                .default_int(4),
            Flag::choice("log-level", &["debug", "info", "warn", "error"])
                .usage("Set the logging level")
                .default_str("info")
                .completion(|_ctx, prefix| {
                    // Inline completion with descriptions
                    let levels = vec![
                        ("debug", "Show all messages including debug"),
                        ("info", "Show informational messages and above"),
                        ("warn", "Show warnings and errors only"),
                        ("error", "Show errors only"),
                    ];

                    let mut result = flag_rs::CompletionResult::new();
                    for (level, desc) in levels {
                        if level.starts_with(prefix) {
                            result =
                                result.add_with_description(level.to_string(), desc.to_string());
                        }
                    }
                    Ok(result)
                }),
        ])
        // Bulk subcommand addition
        .subcommands(vec![
            CommandBuilder::new("init")
                .short("Initialize a new project")
                .flags(vec![
                    Flag::string("name")
                        .short('n')
                        .usage("Project name")
                        .required(),
                    Flag::choice("template", &["basic", "web", "api", "full"])
                        .usage("Project template to use")
                        .default_str("basic"),
                    Flag::directory("path")
                        .short('p')
                        .usage("Directory to create project in")
                        .completion(|_ctx, prefix| {
                            // In a real app, list actual directories
                            let dirs = vec!["./", "../", "/tmp/", "~/projects/"];
                            Ok(flag_rs::CompletionResult::new().extend(
                                dirs.into_iter()
                                    .filter(|d| d.starts_with(prefix))
                                    .map(String::from),
                            ))
                        }),
                ])
                .run(|ctx| {
                    // Type-safe flag access
                    let name = ctx.flag_str_or("name", "my-project");
                    let template = ctx.flag_str_or("template", "basic");
                    let path = ctx.flag_str_or("path", ".");
                    let verbose = ctx.flag_bool_or("verbose", false);

                    if verbose {
                        println!("Initializing {} project '{}' in {}", template, name, path);
                    } else {
                        println!("Creating project '{}'...", name);
                    }

                    Ok(())
                })
                .build(),
            CommandBuilder::new("build")
                .short("Build the project")
                .flags(vec![
                    Flag::bool("release")
                        .short('r')
                        .usage("Build in release mode"),
                    Flag::string_slice("features")
                        .short('f')
                        .usage("Enable features (can be specified multiple times)")
                        .completion(|_ctx, prefix| {
                            let features = vec!["async", "tls", "compression", "metrics"];
                            Ok(flag_rs::CompletionResult::new().extend(
                                features
                                    .into_iter()
                                    .filter(|f| f.starts_with(prefix))
                                    .map(String::from),
                            ))
                        }),
                    Flag::range("jobs", 1, 32)
                        .short('j')
                        .usage("Number of parallel jobs")
                        .default_int(i64::try_from(num_cpus()).unwrap_or(4)),
                ])
                .run(|ctx| {
                    let release = ctx.flag_bool_or("release", false);
                    let jobs = ctx.flag_int_or("jobs", i64::try_from(num_cpus()).unwrap_or(4));
                    let quiet = ctx.flag_bool_or("quiet", false);

                    if !quiet {
                        println!(
                            "Building in {} mode with {} jobs",
                            if release { "release" } else { "debug" },
                            jobs
                        );

                        if let Some(features) = ctx.flag("features") {
                            println!("Features: {}", features);
                        }
                    }

                    Ok(())
                })
                .build(),
            CommandBuilder::new("test")
                .short("Run tests")
                .flags(vec![
                    Flag::string("filter").usage("Only run tests matching this pattern"),
                    Flag::bool("nocapture").usage("Don't capture test output"),
                    Flag::int("test-threads")
                        .usage("Number of threads to use for running tests")
                        .default_int(1),
                ])
                .run(|ctx| {
                    let threads = ctx.flag_int_or("test-threads", 1);
                    let nocapture = ctx.flag_bool_or("nocapture", false);
                    let verbose = ctx.flag_bool_or("verbose", false);

                    if verbose {
                        println!("Running tests with {} thread(s)", threads);
                        if nocapture {
                            println!("Output capture disabled");
                        }

                        if let Some(filter) = ctx.flag("filter") {
                            println!("Filter: {}", filter);
                        }
                    }

                    println!("Running tests...");
                    Ok(())
                })
                .build(),
        ])
        .run(|_ctx| {
            // Root command - show help by default
            println!("Use --help for usage information");
            Ok(())
        })
        .build();

    let args: Vec<String> = std::env::args().skip(1).collect();
    if let Err(e) = app.execute(args) {
        eprintln!("Error: {}", e);
        std::process::exit(1);
    }
}

pub fn add_help(self, help: ActiveHelp) -> Self

Adds an ActiveHelp message

Arguments

• help - The ActiveHelp message to add

Examples

use flag_rs::completion::CompletionResult;
use flag_rs::active_help::ActiveHelp;

let result = CompletionResult::new()
    .add_help(ActiveHelp::new("Press TAB to see available options"));

pub fn add_help_text<S: Into<String>>(self, message: S) -> Self

Adds an ActiveHelp message from a string

Arguments

• message - The help message text

Examples

use flag_rs::completion::CompletionResult;

let result = CompletionResult::new()
    .add_help_text("Use -n <namespace> to filter results");

Examples found in repository

examples/timeout_completion_demo.rs (lines 92-94)

fn main() {
    let app = CommandBuilder::new("cloud-cli")
        .short("Cloud CLI with timeout-protected completions")
        .flag(
            Flag::new("region")
                .short('r')
                .usage("Cloud region")
                .value_type(FlagType::String)
                .default(flag_rs::FlagValue::String("us-east-1".to_string())),
        )
        .subcommand(
            CommandBuilder::new("instances")
                .short("Manage cloud instances")
                .subcommand(
                    CommandBuilder::new("list")
                        .short("List instances (fast completion)")
                        .arg_completion(|_ctx, prefix| {
                            // Fast completion - no timeout needed
                            let instances = vec![
                                "web-server-001",
                                "web-server-002",
                                "db-primary",
                                "db-replica",
                                "cache-node-1",
                                "cache-node-2",
                            ];

                            Ok(CompletionResult::new().extend(
                                instances
                                    .into_iter()
                                    .filter(|i| i.starts_with(prefix))
                                    .map(String::from),
                            ))
                        })
                        .build(),
                )
                .subcommand(
                    CommandBuilder::new("describe")
                        .short("Describe instance (slow completion with timeout)")
                        .arg_completion({
                            // Wrap slow completion with timeout
                            make_timeout_completion(
                                Duration::from_millis(500), // 500ms timeout
                                |ctx, prefix| {
                                    eprintln!("Fetching instance details from API...");

                                    // Simulate slow API call (1 second)
                                    let instances = slow_completion(prefix, 1000);

                                    let mut result = CompletionResult::new();
                                    for instance in instances {
                                        result = result.add_with_description(
                                            instance.clone(),
                                            format!(
                                                "Instance in region {}",
                                                ctx.flag("region")
                                                    .unwrap_or(&"us-east-1".to_string())
                                            ),
                                        );
                                    }

                                    if prefix.is_empty() {
                                        result = result.add_help_text(
                                            "Fetching live instance data from cloud API...",
                                        );
                                    }

                                    Ok(result)
                                },
                            )
                        })
                        .build(),
                )
                .subcommand(
                    CommandBuilder::new("create")
                        .short("Create instance (very slow completion)")
                        .arg_completion({
                            // Use default timeout (2 seconds)
                            make_timeout_completion(DEFAULT_COMPLETION_TIMEOUT, |_ctx, prefix| {
                                eprintln!("Checking available instance types...");

                                // Simulate very slow operation (3 seconds)
                                let types = slow_completion(prefix, 3000);

                                Ok(CompletionResult::new()
                                    .extend(types)
                                    .add_help_text("Available instance types"))
                            })
                        })
                        .build(),
                )
                .build(),
        )
        .build();

    println!("=== Timeout Completion Demo ===\n");
    println!("This demo shows how timeouts protect against slow completion operations.\n");
    println!("To test timeout handling:");
    println!("1. Set up bash completion:");
    println!(
        "   source <({} completion bash)",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("2. Test different completion speeds:");
    println!();
    println!("   Fast (no timeout needed):");
    println!(
        "   {} instances list <TAB>",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("   Slow (500ms timeout, 1s operation - will timeout):");
    println!(
        "   {} instances describe <TAB>",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("   Very slow (2s timeout, 3s operation - will timeout):");
    println!(
        "   {} instances create <TAB>",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("When a timeout occurs, you'll see:");
    println!("- A warning message about the timeout");
    println!("- Any partial results that were available");
    println!("- Suggestion to use a more specific prefix");
    println!("\n---\n");

    let args: Vec<String> = std::env::args().skip(1).collect();
    if let Err(e) = app.execute(args) {
        eprintln!("{}", e);
        std::process::exit(1);
    }
}

examples/flag_completion_demo.rs (line 29)

fn main() {
    let app = CommandBuilder::new("deploy")
        .short("Deploy application to various environments")
        .flag(
            Flag::choice("environment", &["dev", "staging", "prod"])
                .short('e')
                .usage("Target environment")
                .required()
                .completion(|_ctx, prefix| {
                    // Dynamic completion - could check available environments
                    let environments = vec![
                        ("dev", "Development environment"),
                        ("staging", "Staging environment (pre-production)"),
                        ("prod", "Production environment"),
                    ];

                    let mut result = CompletionResult::new();
                    for (env, desc) in environments {
                        if env.starts_with(prefix) {
                            result = result.add_with_description(env.to_string(), desc.to_string());
                        }
                    }

                    // Add active help if no prefix
                    if prefix.is_empty() {
                        result = result.add_help_text("Available environments: dev, staging, prod");
                    }

                    Ok(result)
                }),
        )
        .flag(
            Flag::file("config")
                .short('c')
                .usage("Configuration file")
                .default_str("config.yaml")
                .completion(|_ctx, prefix| {
                    // In a real app, you might list files in the config directory
                    let configs = vec![
                        "config.yaml",
                        "config.dev.yaml",
                        "config.staging.yaml",
                        "config.prod.yaml",
                        "secrets.yaml",
                    ];

                    Ok(CompletionResult::new().extend(
                        configs
                            .into_iter()
                            .filter(|c| c.starts_with(prefix))
                            .map(String::from),
                    ))
                }),
        )
        .flag(
            Flag::directory("output")
                .short('o')
                .usage("Output directory for deployment artifacts")
                .completion(|_ctx, prefix| {
                    // In a real app, you might list actual directories
                    let dirs = vec!["./build", "./dist", "./output", "/tmp/deploy"];

                    Ok(CompletionResult::new().extend(
                        dirs.into_iter()
                            .filter(|d| d.starts_with(prefix))
                            .map(String::from),
                    ))
                }),
        )
        .flag(
            Flag::string_slice("service")
                .short('s')
                .usage("Services to deploy (can be specified multiple times)")
                .completion(|ctx, prefix| {
                    // Context-aware completion based on environment
                    let env = ctx.flag_str_or("environment", "dev");

                    let services = match env {
                        "dev" => vec!["api", "web", "worker", "scheduler", "debug-panel"],
                        "staging" => vec!["api", "web", "worker", "scheduler"],
                        "prod" => vec!["api", "web", "worker"],
                        _ => vec!["api", "web"],
                    };

                    let mut result = CompletionResult::new().extend(
                        services
                            .into_iter()
                            .filter(|s| s.starts_with(prefix))
                            .map(String::from),
                    );

                    // Add context-aware help
                    if prefix.is_empty() {
                        result = result
                            .add_help_text(format!("Available services for {} environment", env));
                    }

                    Ok(result)
                }),
        )
        .flag(
            Flag::range("replicas", 1, 10)
                .short('r')
                .usage("Number of replicas to deploy")
                .default_int(2)
                .completion(|_ctx, _prefix| {
                    // Suggest common replica counts
                    Ok(CompletionResult::new()
                        .add_with_description(
                            "1".to_string(),
                            "Single instance (dev/test)".to_string(),
                        )
                        .add_with_description("2".to_string(), "Basic redundancy".to_string())
                        .add_with_description("3".to_string(), "Standard production".to_string())
                        .add_with_description("5".to_string(), "High availability".to_string()))
                }),
        )
        .run(|ctx| {
            let env = ctx.flag_str_or("environment", "dev");
            let config = ctx.flag_str_or("config", "config.yaml");
            let replicas = ctx.flag_int_or("replicas", 2);

            println!("Deploying to {} environment", env);
            println!("Using configuration: {}", config);
            println!("Replica count: {}", replicas);

            if let Some(output) = ctx.flag("output") {
                println!("Output directory: {}", output);
            }

            if let Some(services) = ctx.flag("service") {
                println!("Deploying services: {}", services);
            } else {
                println!("Deploying all services");
            }

            Ok(())
        })
        .build();

    let args: Vec<String> = std::env::args().skip(1).collect();
    if let Err(e) = app.execute(args) {
        eprintln!("Error: {}", e);
        std::process::exit(1);
    }
}

examples/cached_completion_demo.rs (line 94)

fn main() {
    // Create a shared cache with 10-second TTL
    let cache = Arc::new(CompletionCache::new(Duration::from_secs(10)));

    let app = CommandBuilder::new("kubectl")
        .short("Kubernetes command-line tool with cached completions")
        .flag(
            Flag::new("namespace")
                .short('n')
                .usage("The namespace scope for this CLI request")
                .value_type(FlagType::String)
                .default(flag_rs::FlagValue::String("default".to_string())),
        )
        .subcommand({
            let cache_clone = Arc::clone(&cache);
            CommandBuilder::new("get")
                .short("Display one or many resources")
                .subcommand({
                    let cache_for_pods = Arc::clone(&cache_clone);
                    CommandBuilder::new("pods")
                        .short("List pods with cached completion")
                        .arg_completion(move |ctx, prefix| {
                            let start = Instant::now();

                            // Generate cache key
                            let cache_key = CompletionCache::make_key(
                                &["kubectl".to_string(), "get".to_string(), "pods".to_string()],
                                prefix,
                                ctx.flags(),
                            );

                            // Try to get from cache first
                            if let Some(cached_result) = cache_for_pods.get(&cache_key) {
                                eprintln!("✓ Cache hit! Completed in {:?}", start.elapsed());
                                return Ok(cached_result);
                            }

                            eprintln!("✗ Cache miss - fetching completions...");

                            // Perform expensive operation
                            let items = expensive_completion(prefix);
                            let mut result = CompletionResult::new();

                            for item in items {
                                result = result.add_with_description(
                                    item.clone(),
                                    format!(
                                        "Pod in namespace {}",
                                        ctx.flag("namespace").unwrap_or(&"default".to_string())
                                    ),
                                );
                            }

                            // Add contextual help
                            if prefix.is_empty() {
                                result =
                                    result.add_help_text("Tip: Start typing to filter pod names");
                            }

                            // Cache the result
                            cache_for_pods.put(cache_key, result.clone());

                            eprintln!(
                                "✓ Completed in {:?} (cached for future use)",
                                start.elapsed()
                            );
                            Ok(result)
                        })
                        .build()
                })
                .subcommand({
                    let cache_for_services = Arc::clone(&cache_clone);
                    CommandBuilder::new("services")
                        .short("List services with cached completion")
                        .arg_completion(move |ctx, prefix| {
                            let cache_key = CompletionCache::make_key(
                                &[
                                    "kubectl".to_string(),
                                    "get".to_string(),
                                    "services".to_string(),
                                ],
                                prefix,
                                ctx.flags(),
                            );

                            if let Some(cached) = cache_for_services.get(&cache_key) {
                                eprintln!("✓ Using cached service completions");
                                return Ok(cached);
                            }

                            // Simulate expensive operation
                            let services = expensive_completion(prefix);
                            let result = CompletionResult::new().extend(services);

                            cache_for_services.put(cache_key, result.clone());
                            Ok(result)
                        })
                        .build()
                })
                .build()
        })
        .build();

    println!("=== Cached Completion Demo ===\n");
    println!("This demo shows how completion caching improves performance.\n");
    println!("To test completions with caching:");
    println!("1. Set up bash completion:");
    println!(
        "   source <({} completion bash)",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("2. Try tab completion multiple times:");
    println!(
        "   {} get pods n<TAB>     # First time: ~500ms (cache miss)",
        std::env::args().next().unwrap_or_default()
    );
    println!(
        "   {} get pods n<TAB>     # Second time: <1ms (cache hit!)",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("3. Different prefixes have separate cache entries:");
    println!(
        "   {} get pods r<TAB>     # Different prefix = cache miss",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("4. Flags affect the cache key:");
    println!(
        "   {} -n prod get pods n<TAB>  # Different namespace = different cache",
        std::env::args().next().unwrap_or_default()
    );
    println!();
    println!("Note: Cache entries expire after 10 seconds in this demo.\n");
    println!("---\n");

    let args: Vec<String> = std::env::args().skip(1).collect();

    // Handle completion requests
    if std::env::var("KUBECTL_COMPLETE").is_ok() {
        // When testing completions, show cache status
        eprintln!("Cache size: {} entries", cache.size());
    }

    if let Err(e) = app.execute(args) {
        eprintln!("{}", e);
        std::process::exit(1);
    }
}

examples/active_help_demo.rs (lines 35-37)

fn main() {
    let app = CommandBuilder::new("active-help-demo")
        .short("Demonstrates ActiveHelp system")
        .long("This example shows how ActiveHelp provides contextual hints during tab completion")
        .flag(
            Flag::new("namespace")
                .short('n')
                .usage("Kubernetes namespace")
                .value_type(FlagType::String),
        )
        .flag(
            Flag::new("output")
                .short('o')
                .usage("Output format")
                .value_type(FlagType::String),
        )
        .subcommand(
            CommandBuilder::new("get")
                .short("Get resources")
                .subcommand(
                    CommandBuilder::new("pods")
                        .short("Get pods")
                        .arg_completion(|ctx, prefix| {
                            let mut result = CompletionResult::new();

                            // Add contextual help based on current state
                            if ctx.flag("namespace").is_none() {
                                result = result.add_help_text(
                                    "Tip: Use -n <namespace> to list pods from a specific namespace",
                                );
                            }

                            if ctx.flag("output").is_none() {
                                result = result.add_conditional_help(
                                    "Use -o json for machine-readable output",
                                    |_| true, // Always show this tip
                                );
                            }

                            // Simulate pod completions
                            let namespace = ctx
                                .flag("namespace")
                                .map(String::as_str)
                                .unwrap_or("default");

                            let pods = match namespace {
                                "default" => vec![
                                    ("nginx-abc123", "Running"),
                                    ("redis-def456", "Running"),
                                    ("postgres-ghi789", "CrashLoopBackOff"),
                                ],
                                "kube-system" => vec![
                                    ("coredns-xyz789", "Running"),
                                    ("kube-proxy-abc123", "Running"),
                                    ("etcd-master", "Running"),
                                ],
                                _ => vec![],
                            };

                            // Add pods with status descriptions
                            for (pod, status) in &pods {
                                if pod.starts_with(prefix) {
                                    result = result.add_with_description(
                                        *pod,
                                        format!("Status: {status}"),
                                    );
                                }
                            }

                            // Add help if there's a problematic pod
                            if pods.iter().any(|(_, status)| status == &"CrashLoopBackOff") {
                                result = result.add_help_text(
                                    "Warning: Some pods are in CrashLoopBackOff state. Use 'describe' to investigate.",
                                );
                            }

                            Ok(result)
                        })
                        .run(|ctx| {
                            let namespace = ctx
                                .flag("namespace")
                                .map(String::as_str)
                                .unwrap_or("default");
                            let output = ctx.flag("output").map(String::as_str).unwrap_or("table");

                            println!("Getting pods from namespace: {namespace}");
                            println!("Output format: {output}");

                            if let Some(pod) = ctx.args().first() {
                                println!("Getting specific pod: {pod}");
                            } else {
                                println!("Listing all pods");
                            }
                            Ok(())
                        })
                        .build(),
                )
                .subcommand(
                    CommandBuilder::new("services")
                        .short("Get services")
                        .arg_completion(|_ctx, _prefix| {
                            let mut result = CompletionResult::new()
                                .add_with_description("nginx-service", "Type: LoadBalancer")
                                .add_with_description("redis-service", "Type: ClusterIP")
                                .add_with_description("postgres-service", "Type: NodePort");

                            // Add conditional help based on flags
                            result = result.add_conditional_help(
                                "Tip: Use -o wide to see more details about services",
                                |ctx| {
                                    ctx.flag("output")
                                        .map(|o| o != "wide")
                                        .unwrap_or(true)
                                },
                            );

                            Ok(result)
                        })
                        .build(),
                )
                .build(),
        )
        .subcommand(
            CommandBuilder::new("create")
                .short("Create resources")
                .flag(
                    Flag::new("file")
                        .short('f')
                        .usage("Filename to use to create the resource")
                        .value_type(FlagType::String)
                        .required(),
                )
                .flag_completion("file", |_ctx, prefix| {
                    let mut result = CompletionResult::new();

                    // Simulate file completions
                    let files = vec![
                        ("deployment.yaml", "Deployment configuration"),
                        ("service.yaml", "Service configuration"),
                        ("configmap.yaml", "ConfigMap configuration"),
                        ("secret.yaml", "Secret configuration"),
                        ("pod.yaml", "Pod configuration"),
                    ];

                    for (file, desc) in files {
                        if file.starts_with(prefix) {
                            result = result.add_with_description(file, desc);
                        }
                    }

                    // Add contextual help
                    result = result.add_help_text(
                        "Files should be valid Kubernetes manifests in YAML or JSON format",
                    );

                    if std::path::Path::new(prefix)
                        .extension()
                        .is_some_and(|ext| ext.eq_ignore_ascii_case("json"))
                    {
                        result = result.add_help_text(
                            "Note: JSON format is supported but YAML is more common in Kubernetes",
                        );
                    }

                    Ok(result)
                })
                .run(|ctx| {
                    let file = ctx.flag("file").expect("File is required");
                    println!("Creating resources from file: {file}");
                    Ok(())
                })
                .build(),
        )
        .subcommand(
            CommandBuilder::new("debug")
                .short("Debug and troubleshoot resources")
                .arg_completion(|_ctx, _prefix| {
                    Ok(CompletionResult::new()
                        .add_with_description("pod/nginx-abc123", "Debug a specific pod")
                        .add_with_description("node/worker-1", "Debug a node")
                        .add_with_description("deployment/nginx", "Debug a deployment")
                        .add_help_text("Debug creates an interactive debugging session")
                        .add_help_text("Common debugging commands: kubectl logs, kubectl exec, kubectl describe")
                        .add_conditional_help(
                            "Tip: Use 'kubectl logs -f' to follow log output in real-time",
                            |ctx| ctx.args().is_empty(),
                        ))
                })
                .build(),
        )
        .build();

    let args: Vec<String> = std::env::args().skip(1).collect();
    if let Err(e) = app.execute(args) {
        eprintln!("Error: {e}");
        std::process::exit(1);
    }
}

pub fn add_conditional_help<S, F>(self, message: S, condition: F) -> Self

where S: Into<String>, F: Fn(&Context) -> bool + Send + Sync + 'static,

Adds a conditional ActiveHelp message

Arguments

• message - The help message text
• condition - Function that determines if help should be shown

Examples

use flag_rs::completion::CompletionResult;

let result = CompletionResult::new()
    .add_conditional_help(
        "Tip: Use --format json for machine-readable output",
        |ctx| ctx.flag("format").is_none()
    );

Examples found in repository

examples/active_help_demo.rs (lines 41-44)

fn main() {
    let app = CommandBuilder::new("active-help-demo")
        .short("Demonstrates ActiveHelp system")
        .long("This example shows how ActiveHelp provides contextual hints during tab completion")
        .flag(
            Flag::new("namespace")
                .short('n')
                .usage("Kubernetes namespace")
                .value_type(FlagType::String),
        )
        .flag(
            Flag::new("output")
                .short('o')
                .usage("Output format")
                .value_type(FlagType::String),
        )
        .subcommand(
            CommandBuilder::new("get")
                .short("Get resources")
                .subcommand(
                    CommandBuilder::new("pods")
                        .short("Get pods")
                        .arg_completion(|ctx, prefix| {
                            let mut result = CompletionResult::new();

                            // Add contextual help based on current state
                            if ctx.flag("namespace").is_none() {
                                result = result.add_help_text(
                                    "Tip: Use -n <namespace> to list pods from a specific namespace",
                                );
                            }

                            if ctx.flag("output").is_none() {
                                result = result.add_conditional_help(
                                    "Use -o json for machine-readable output",
                                    |_| true, // Always show this tip
                                );
                            }

                            // Simulate pod completions
                            let namespace = ctx
                                .flag("namespace")
                                .map(String::as_str)
                                .unwrap_or("default");

                            let pods = match namespace {
                                "default" => vec![
                                    ("nginx-abc123", "Running"),
                                    ("redis-def456", "Running"),
                                    ("postgres-ghi789", "CrashLoopBackOff"),
                                ],
                                "kube-system" => vec![
                                    ("coredns-xyz789", "Running"),
                                    ("kube-proxy-abc123", "Running"),
                                    ("etcd-master", "Running"),
                                ],
                                _ => vec![],
                            };

                            // Add pods with status descriptions
                            for (pod, status) in &pods {
                                if pod.starts_with(prefix) {
                                    result = result.add_with_description(
                                        *pod,
                                        format!("Status: {status}"),
                                    );
                                }
                            }

                            // Add help if there's a problematic pod
                            if pods.iter().any(|(_, status)| status == &"CrashLoopBackOff") {
                                result = result.add_help_text(
                                    "Warning: Some pods are in CrashLoopBackOff state. Use 'describe' to investigate.",
                                );
                            }

                            Ok(result)
                        })
                        .run(|ctx| {
                            let namespace = ctx
                                .flag("namespace")
                                .map(String::as_str)
                                .unwrap_or("default");
                            let output = ctx.flag("output").map(String::as_str).unwrap_or("table");

                            println!("Getting pods from namespace: {namespace}");
                            println!("Output format: {output}");

                            if let Some(pod) = ctx.args().first() {
                                println!("Getting specific pod: {pod}");
                            } else {
                                println!("Listing all pods");
                            }
                            Ok(())
                        })
                        .build(),
                )
                .subcommand(
                    CommandBuilder::new("services")
                        .short("Get services")
                        .arg_completion(|_ctx, _prefix| {
                            let mut result = CompletionResult::new()
                                .add_with_description("nginx-service", "Type: LoadBalancer")
                                .add_with_description("redis-service", "Type: ClusterIP")
                                .add_with_description("postgres-service", "Type: NodePort");

                            // Add conditional help based on flags
                            result = result.add_conditional_help(
                                "Tip: Use -o wide to see more details about services",
                                |ctx| {
                                    ctx.flag("output")
                                        .map(|o| o != "wide")
                                        .unwrap_or(true)
                                },
                            );

                            Ok(result)
                        })
                        .build(),
                )
                .build(),
        )
        .subcommand(
            CommandBuilder::new("create")
                .short("Create resources")
                .flag(
                    Flag::new("file")
                        .short('f')
                        .usage("Filename to use to create the resource")
                        .value_type(FlagType::String)
                        .required(),
                )
                .flag_completion("file", |_ctx, prefix| {
                    let mut result = CompletionResult::new();

                    // Simulate file completions
                    let files = vec![
                        ("deployment.yaml", "Deployment configuration"),
                        ("service.yaml", "Service configuration"),
                        ("configmap.yaml", "ConfigMap configuration"),
                        ("secret.yaml", "Secret configuration"),
                        ("pod.yaml", "Pod configuration"),
                    ];

                    for (file, desc) in files {
                        if file.starts_with(prefix) {
                            result = result.add_with_description(file, desc);
                        }
                    }

                    // Add contextual help
                    result = result.add_help_text(
                        "Files should be valid Kubernetes manifests in YAML or JSON format",
                    );

                    if std::path::Path::new(prefix)
                        .extension()
                        .is_some_and(|ext| ext.eq_ignore_ascii_case("json"))
                    {
                        result = result.add_help_text(
                            "Note: JSON format is supported but YAML is more common in Kubernetes",
                        );
                    }

                    Ok(result)
                })
                .run(|ctx| {
                    let file = ctx.flag("file").expect("File is required");
                    println!("Creating resources from file: {file}");
                    Ok(())
                })
                .build(),
        )
        .subcommand(
            CommandBuilder::new("debug")
                .short("Debug and troubleshoot resources")
                .arg_completion(|_ctx, _prefix| {
                    Ok(CompletionResult::new()
                        .add_with_description("pod/nginx-abc123", "Debug a specific pod")
                        .add_with_description("node/worker-1", "Debug a node")
                        .add_with_description("deployment/nginx", "Debug a deployment")
                        .add_help_text("Debug creates an interactive debugging session")
                        .add_help_text("Common debugging commands: kubectl logs, kubectl exec, kubectl describe")
                        .add_conditional_help(
                            "Tip: Use 'kubectl logs -f' to follow log output in real-time",
                            |ctx| ctx.args().is_empty(),
                        ))
                })
                .build(),
        )
        .build();

    let args: Vec<String> = std::env::args().skip(1).collect();
    if let Err(e) = app.execute(args) {
        eprintln!("Error: {e}");
        std::process::exit(1);
    }
}

impl CompletionResult

pub fn merge(self, other: Self) -> Self

Merges two completion results, combining their values and help messages

Trait Implementations

impl Clone for CompletionResult

fn clone(&self) -> CompletionResult

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CompletionResult

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for CompletionResult

fn default() -> Self

Returns the “default value” for a type.