Struct Context 

pub struct Context { /* private fields */ }

Context passed to command handlers

Context provides access to:

• Command arguments
• Parsed flag values
• Arbitrary typed values for sharing state between commands

Examples

use flag_rs::context::Context;
use std::collections::HashMap;

// Create a context with arguments
let mut ctx = Context::new(vec!["file1.txt".to_string(), "file2.txt".to_string()]);

// Access arguments
assert_eq!(ctx.args(), &["file1.txt", "file2.txt"]);

// Set and retrieve flags
ctx.set_flag("verbose".to_string(), "true".to_string());
assert_eq!(ctx.flag("verbose"), Some(&"true".to_string()));

// Store typed values
#[derive(Debug, PartialEq)]
struct Config {
    api_key: String,
}

ctx.set(Config { api_key: "secret".to_string() });
let config = ctx.get::<Config>().unwrap();
assert_eq!(config.api_key, "secret");

Implementations

impl Context

pub fn new(args: Vec<String>) -> Self

Creates a new context with the given arguments

Arguments

• args - The command-line arguments (without the command path)

Examples found in repository

examples/benchmark.rs (line 213)

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);
}

pub fn args(&self) -> &[String]

Returns a slice of the command arguments

Examples

use flag_rs::context::Context;

let ctx = Context::new(vec!["file.txt".to_string()]);
assert_eq!(ctx.args(), &["file.txt"]);

Examples found in repository

examples/kubectl.rs (line 110)

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")
        .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/validator_demo.rs (line 12)

fn main() {
    let app = CommandBuilder::new("validator-demo")
        .short("Demonstrates argument validation")
        .subcommand(
            CommandBuilder::new("copy")
                .short("Copy files (requires exactly 2 arguments)")
                .args(ArgValidator::ExactArgs(2))
                .run(|ctx| {
                    let args = ctx.args();
                    println!("Copying from '{}' to '{}'", args[0], args[1]);
                    Ok(())
                })
                .build(),
        )
        .subcommand(
            CommandBuilder::new("delete")
                .short("Delete files (requires at least 1 argument)")
                .args(ArgValidator::MinimumArgs(1))
                .run(|ctx| {
                    println!("Deleting {} file(s):", ctx.args().len());
                    for file in ctx.args() {
                        println!("  - {}", file);
                    }
                    Ok(())
                })
                .build(),
        )
        .subcommand(
            CommandBuilder::new("list")
                .short("List items (accepts 0-3 arguments)")
                .args(ArgValidator::RangeArgs(0, 3))
                .run(|ctx| {
                    if ctx.args().is_empty() {
                        println!("Listing all items");
                    } else {
                        println!("Listing specific items:");
                        for item in ctx.args() {
                            println!("  - {}", item);
                        }
                    }
                    Ok(())
                })
                .build(),
        )
        .subcommand(
            CommandBuilder::new("action")
                .short("Perform action (only start/stop/restart allowed)")
                .args(ArgValidator::OnlyValidArgs(vec![
                    "start".to_string(),
                    "stop".to_string(),
                    "restart".to_string(),
                ]))
                .run(|ctx| {
                    let action = ctx.args().first().map(String::as_str).unwrap_or("start");
                    println!("Performing action: {}", action);
                    Ok(())
                })
                .build(),
        )
        .subcommand(
            CommandBuilder::new("numbers")
                .short("Process numbers (custom validator for integers)")
                .args(ArgValidator::Custom(std::sync::Arc::new(|args| {
                    if args.is_empty() {
                        return Err(Error::ArgumentValidation {
                            message: "at least one number required".to_string(),
                            expected: "numbers".to_string(),
                            received: 0,
                        });
                    }

                    for (i, arg) in args.iter().enumerate() {
                        if arg.parse::<i32>().is_err() {
                            return Err(Error::ArgumentValidation {
                                message: format!(
                                    "argument {} ('{}') must be an integer",
                                    i + 1,
                                    arg
                                ),
                                expected: "integer".to_string(),
                                received: args.len(),
                            });
                        }
                    }
                    Ok(())
                })))
                .run(|ctx| {
                    let numbers: Vec<i32> = ctx.args().iter().map(|s| s.parse().unwrap()).collect();
                    let sum: i32 = numbers.iter().sum();
                    println!("Sum of {} numbers: {}", numbers.len(), sum);
                    Ok(())
                })
                .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);
    }
}

examples/error_handling_demo.rs (line 21)

fn main() {
    let app = CommandBuilder::new("error-demo")
        .short("Demonstrates error handling")
        .long("This example shows various error scenarios and how flag-rs handles them")
        .subcommand(
            CommandBuilder::new("deploy")
                .short("Deploy the application")
                .args(ArgValidator::ExactArgs(1))
                .run(|ctx| {
                    let env = ctx.args().first().unwrap();
                    if !["dev", "staging", "production"].contains(&env.as_str()) {
                        return Err(Error::Validation(format!(
                            "invalid environment '{}', must be one of: dev, staging, production",
                            env
                        )));
                    }
                    println!("Deploying to {}", env);
                    Ok(())
                })
                .build(),
        )
        .subcommand(
            CommandBuilder::new("serve")
                .short("Start the server")
                .flag(
                    Flag::new("port")
                        .short('p')
                        .usage("Port to listen on")
                        .value_type(FlagType::Int)
                        .required(),
                )
                .run(|ctx| {
                    let port = ctx.flag("port").unwrap();
                    println!("Server starting on port {}", port);
                    Ok(())
                })
                .build(),
        )
        .subcommand(
            CommandBuilder::new("migrate")
                .short("Run database migrations")
                .subcommand(
                    CommandBuilder::new("up")
                        .short("Run pending migrations")
                        .run(|_| {
                            println!("Running migrations...");
                            Ok(())
                        })
                        .build(),
                )
                .subcommand(
                    CommandBuilder::new("down")
                        .short("Rollback migrations")
                        .args(ArgValidator::MaximumArgs(1))
                        .run(|ctx| {
                            let steps = ctx
                                .args()
                                .first()
                                .and_then(|s| s.parse::<u32>().ok())
                                .unwrap_or(1);
                            println!(
                                "Rolling back {} migration{}",
                                steps,
                                if steps == 1 { "" } else { "s" }
                            );
                            Ok(())
                        })
                        .build(),
                )
                .build(),
        )
        .subcommand(
            CommandBuilder::new("config")
                .short("Manage configuration")
                .aliases(vec!["cfg", "conf"])
                .run(|_| {
                    println!("Configuration management");
                    Ok(())
                })
                .build(),
        )
        .build();

    println!("=== Error Handling Demo ===\n");
    println!("This demo shows how flag-rs handles various error scenarios.\n");
    println!("Try these commands to see different error types:\n");
    println!(
        "1. {} deploi              (typo - will show suggestions)",
        std::env::args().next().unwrap_or_default()
    );
    println!(
        "2. {} deploy              (missing required argument)",
        std::env::args().next().unwrap_or_default()
    );
    println!(
        "3. {} deploy dev staging  (too many arguments)",
        std::env::args().next().unwrap_or_default()
    );
    println!(
        "4. {} deploy test         (invalid environment)",
        std::env::args().next().unwrap_or_default()
    );
    println!(
        "5. {} serve               (missing required flag)",
        std::env::args().next().unwrap_or_default()
    );
    println!(
        "6. {} serve -p abc        (invalid flag value)",
        std::env::args().next().unwrap_or_default()
    );
    println!(
        "7. {} migrate             (subcommand required)",
        std::env::args().next().unwrap_or_default()
    );
    println!(
        "8. {} confi               (typo - will suggest 'config')",
        std::env::args().next().unwrap_or_default()
    );
    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/active_help_demo.rs (line 96)

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 args_mut(&mut self) -> &mut Vec<String>

Returns a mutable reference to the command arguments

Examples

use flag_rs::context::Context;

let mut ctx = Context::new(vec!["file.txt".to_string()]);
ctx.args_mut().push("another.txt".to_string());
assert_eq!(ctx.args().len(), 2);

pub fn flag(&self, name: &str) -> Option<&String>

Gets the value of a flag by name

Arguments

• name - The name of the flag

Returns

Returns Some(&String) if the flag exists, None otherwise

Examples found in repository

examples/kubectl.rs (line 86)

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()
}

examples/error_handling_demo.rs (line 44)

fn main() {
    let app = CommandBuilder::new("error-demo")
        .short("Demonstrates error handling")
        .long("This example shows various error scenarios and how flag-rs handles them")
        .subcommand(
            CommandBuilder::new("deploy")
                .short("Deploy the application")
                .args(ArgValidator::ExactArgs(1))
                .run(|ctx| {
                    let env = ctx.args().first().unwrap();
                    if !["dev", "staging", "production"].contains(&env.as_str()) {
                        return Err(Error::Validation(format!(
                            "invalid environment '{}', must be one of: dev, staging, production",
                            env
                        )));
                    }
                    println!("Deploying to {}", env);
                    Ok(())
                })
                .build(),
        )
        .subcommand(
            CommandBuilder::new("serve")
                .short("Start the server")
                .flag(
                    Flag::new("port")
                        .short('p')
                        .usage("Port to listen on")
                        .value_type(FlagType::Int)
                        .required(),
                )
                .run(|ctx| {
                    let port = ctx.flag("port").unwrap();
                    println!("Server starting on port {}", port);
                    Ok(())
                })
                .build(),
        )
        .subcommand(
            CommandBuilder::new("migrate")
                .short("Run database migrations")
                .subcommand(
                    CommandBuilder::new("up")
                        .short("Run pending migrations")
                        .run(|_| {
                            println!("Running migrations...");
                            Ok(())
                        })
                        .build(),
                )
                .subcommand(
                    CommandBuilder::new("down")
                        .short("Rollback migrations")
                        .args(ArgValidator::MaximumArgs(1))
                        .run(|ctx| {
                            let steps = ctx
                                .args()
                                .first()
                                .and_then(|s| s.parse::<u32>().ok())
                                .unwrap_or(1);
                            println!(
                                "Rolling back {} migration{}",
                                steps,
                                if steps == 1 { "" } else { "s" }
                            );
                            Ok(())
                        })
                        .build(),
                )
                .build(),
        )
        .subcommand(
            CommandBuilder::new("config")
                .short("Manage configuration")
                .aliases(vec!["cfg", "conf"])
                .run(|_| {
                    println!("Configuration management");
                    Ok(())
                })
                .build(),
        )
        .build();

    println!("=== Error Handling Demo ===\n");
    println!("This demo shows how flag-rs handles various error scenarios.\n");
    println!("Try these commands to see different error types:\n");
    println!(
        "1. {} deploi              (typo - will show suggestions)",
        std::env::args().next().unwrap_or_default()
    );
    println!(
        "2. {} deploy              (missing required argument)",
        std::env::args().next().unwrap_or_default()
    );
    println!(
        "3. {} deploy dev staging  (too many arguments)",
        std::env::args().next().unwrap_or_default()
    );
    println!(
        "4. {} deploy test         (invalid environment)",
        std::env::args().next().unwrap_or_default()
    );
    println!(
        "5. {} serve               (missing required flag)",
        std::env::args().next().unwrap_or_default()
    );
    println!(
        "6. {} serve -p abc        (invalid flag value)",
        std::env::args().next().unwrap_or_default()
    );
    println!(
        "7. {} migrate             (subcommand required)",
        std::env::args().next().unwrap_or_default()
    );
    println!(
        "8. {} confi               (typo - will suggest 'config')",
        std::env::args().next().unwrap_or_default()
    );
    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/timeout_completion_demo.rs (line 85)

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 130)

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 86)

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/lifecycle_hooks_demo.rs (line 30)

fn main() {
    let app = CommandBuilder::new("lifecycle-demo")
        .short("Demonstrates lifecycle hooks")
        .long("This example shows how lifecycle hooks execute in the proper order")
        .flag(
            Flag::new("verbose")
                .short('v')
                .usage("Enable verbose output")
                .value_type(FlagType::Bool),
        )
        // Persistent hooks run for this command and all subcommands
        .persistent_pre_run(|ctx| {
            log_hook("Root PersistentPreRun");
            if ctx.flag("verbose").is_some() {
                println!("     -> Verbose mode enabled globally");
            }
            Ok(())
        })
        .persistent_post_run(|ctx| {
            log_hook("Root PersistentPostRun");
            if ctx.flag("verbose").is_some() {
                println!("     -> Cleaning up verbose logging");
            }
            Ok(())
        })
        .subcommand(
            CommandBuilder::new("server")
                .short("Server management commands")
                .persistent_pre_run(|_ctx| {
                    log_hook("Server PersistentPreRun");
                    println!("     -> Initializing server module");
                    Ok(())
                })
                .persistent_post_run(|_ctx| {
                    log_hook("Server PersistentPostRun");
                    println!("     -> Cleaning up server module");
                    Ok(())
                })
                .subcommand(
                    CommandBuilder::new("start")
                        .short("Start the server")
                        .flag(
                            Flag::new("port")
                                .short('p')
                                .usage("Port to listen on")
                                .value_type(FlagType::Int),
                        )
                        .pre_run(|ctx| {
                            log_hook("Start PreRun");
                            let port = ctx
                                .flag("port")
                                .and_then(|s| s.parse::<u16>().ok())
                                .unwrap_or(8080);
                            println!("     -> Validating port {}", port);
                            Ok(())
                        })
                        .run(|ctx| {
                            log_hook("Start Run");
                            let port = ctx
                                .flag("port")
                                .and_then(|s| s.parse::<u16>().ok())
                                .unwrap_or(8080);
                            println!("     -> Starting server on port {}", port);
                            Ok(())
                        })
                        .post_run(|_ctx| {
                            log_hook("Start PostRun");
                            println!("     -> Server started successfully");
                            Ok(())
                        })
                        .build(),
                )
                .subcommand(
                    CommandBuilder::new("stop")
                        .short("Stop the server")
                        .pre_run(|_ctx| {
                            log_hook("Stop PreRun");
                            println!("     -> Checking if server is running");
                            Ok(())
                        })
                        .run(|_ctx| {
                            log_hook("Stop Run");
                            println!("     -> Stopping server");
                            Ok(())
                        })
                        .post_run(|_ctx| {
                            log_hook("Stop PostRun");
                            println!("     -> Server stopped");
                            Ok(())
                        })
                        .build(),
                )
                .build(),
        )
        .subcommand(
            CommandBuilder::new("database")
                .short("Database management commands")
                .persistent_pre_run(|_ctx| {
                    log_hook("Database PersistentPreRun");
                    println!("     -> Connecting to database");
                    Ok(())
                })
                .persistent_post_run(|_ctx| {
                    log_hook("Database PersistentPostRun");
                    println!("     -> Closing database connection");
                    Ok(())
                })
                .subcommand(
                    CommandBuilder::new("migrate")
                        .short("Run database migrations")
                        .pre_run(|_ctx| {
                            log_hook("Migrate PreRun");
                            println!("     -> Checking migration status");
                            Ok(())
                        })
                        .run(|_ctx| {
                            log_hook("Migrate Run");
                            println!("     -> Running migrations");
                            Ok(())
                        })
                        .post_run(|_ctx| {
                            log_hook("Migrate PostRun");
                            println!("     -> Migrations completed");
                            Ok(())
                        })
                        .build(),
                )
                .build(),
        )
        .build();

    println!("=== Lifecycle Hooks Demo ===\n");
    println!("This demo shows the execution order of lifecycle hooks.");
    println!("Try these commands to see different hook patterns:\n");
    println!(
        "1. {} server start",
        std::env::args().next().unwrap_or_default()
    );
    println!(
        "2. {} -v server start -p 3000",
        std::env::args().next().unwrap_or_default()
    );
    println!(
        "3. {} database migrate",
        std::env::args().next().unwrap_or_default()
    );
    println!("\n---\n");

    // Reset counter before execution
    COUNTER.store(0, Ordering::SeqCst);

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

    println!("\n=== Hook Execution Summary ===");
    println!("Total hooks executed: {}", COUNTER.load(Ordering::SeqCst));
    println!("\nExecution order:");
    println!("1. Parent PersistentPreRun (root → child)");
    println!("2. Command PreRun");
    println!("3. Command Run");
    println!("4. Command PostRun");
    println!("5. Parent PersistentPostRun (child → root)");
}

Additional examples can be found in:

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

pub fn set_flag(&mut self, name: String, value: String)

Sets a flag value

Arguments

• name - The name of the flag
• value - The value to set

pub fn flags(&self) -> &HashMap<String, String>

Returns a reference to all flags

Examples found in repository

examples/enhanced_errors_demo.rs (line 77)

fn main() {
    let app = CommandBuilder::new("errordemo")
        .short("Demo of enhanced error messages")
        .flag(
            Flag::new("verbose")
                .short('v')
                .value_type(FlagType::Bool)
                .usage("Enable verbose output"),
        )
        .flag(
            Flag::new("workers")
                .short('w')
                .value_type(FlagType::Range(1, 10))
                .usage("Number of worker threads"),
        )
        .flag(
            Flag::new("format")
                .short('f')
                .value_type(FlagType::Choice(vec![
                    "json".to_string(),
                    "yaml".to_string(),
                    "xml".to_string(),
                    "toml".to_string(),
                ]))
                .usage("Output format"),
        )
        .flag(
            Flag::new("config")
                .short('c')
                .value_type(FlagType::File)
                .usage("Configuration file"),
        )
        .flag(
            Flag::new("outdir")
                .short('o')
                .value_type(FlagType::Directory)
                .usage("Output directory"),
        )
        .flag(
            Flag::new("ssl")
                .value_type(FlagType::Bool)
                .usage("Enable SSL"),
        )
        .flag(
            Flag::new("ssl-cert")
                .value_type(FlagType::File)
                .constraint(FlagConstraint::RequiredIf("ssl".to_string()))
                .usage("SSL certificate file"),
        )
        .flag(
            Flag::new("json")
                .value_type(FlagType::Bool)
                .constraint(FlagConstraint::ConflictsWith(vec!["xml".to_string()]))
                .usage("Output in JSON format"),
        )
        .flag(
            Flag::new("xml")
                .value_type(FlagType::Bool)
                .usage("Output in XML format"),
        )
        .flag(
            Flag::new("required-flag")
                .value_type(FlagType::String)
                .required()
                .usage("This flag is required"),
        )
        .subcommand(
            CommandBuilder::new("process")
                .short("Process data")
                .run(|ctx| {
                    println!("Processing with flags: {:?}", ctx.flags());
                    Ok(())
                })
                .build(),
        )
        .build();

    println!("Try these commands to see enhanced error messages:\n");
    println!("  # Boolean parsing error");
    println!("  cargo run --example enhanced_errors_demo -- --verbose=maybe\n");

    println!("  # Integer parsing error");
    println!("  cargo run --example enhanced_errors_demo -- --workers=abc\n");

    println!("  # Range validation error");
    println!("  cargo run --example enhanced_errors_demo -- --workers=20\n");

    println!("  # Choice validation error");
    println!("  cargo run --example enhanced_errors_demo -- --format=csv\n");

    println!("  # File not found error");
    println!("  cargo run --example enhanced_errors_demo -- --config=/tmp/nonexistent.conf\n");

    println!("  # Directory not found error");
    println!("  cargo run --example enhanced_errors_demo -- --outdir=/tmp/nonexistent_dir\n");

    println!("  # Flag constraint error (RequiredIf)");
    println!("  cargo run --example enhanced_errors_demo -- --ssl --required-flag=test process\n");

    println!("  # Flag constraint error (ConflictsWith)");
    println!(
        "  cargo run --example enhanced_errors_demo -- --json --xml --required-flag=test process\n"
    );

    println!("  # Required flag error");
    println!("  cargo run --example enhanced_errors_demo -- process\n");

    println!("  # Unknown command error");
    println!("  cargo run --example enhanced_errors_demo -- --required-flag=test proces\n");

    let args: Vec<String> = std::env::args().skip(1).collect();
    if !args.is_empty() {
        println!("\n{}", "=".repeat(60));
        println!("Running with args: {:?}\n", args);

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

examples/cached_completion_demo.rs (line 66)

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);
    }
}

pub fn flag_bool(&self, name: &str) -> Option<bool>

Gets a flag value as a boolean

Arguments

• name - The name of the flag

Returns

Returns Some(bool) if the flag exists and can be parsed as a boolean, None otherwise

Examples

use flag_rs::context::Context;

let mut ctx = Context::new(vec![]);
ctx.set_flag("verbose".to_string(), "true".to_string());
ctx.set_flag("debug".to_string(), "false".to_string());

assert_eq!(ctx.flag_bool("verbose"), Some(true));
assert_eq!(ctx.flag_bool("debug"), Some(false));
assert_eq!(ctx.flag_bool("missing"), None);

pub fn flag_int(&self, name: &str) -> Option<i64>

Gets a flag value as an integer

Arguments

• name - The name of the flag

Returns

Returns Some(i64) if the flag exists and can be parsed as an integer, None otherwise

Examples

use flag_rs::context::Context;

let mut ctx = Context::new(vec![]);
ctx.set_flag("port".to_string(), "8080".to_string());

assert_eq!(ctx.flag_int("port"), Some(8080));
assert_eq!(ctx.flag_int("missing"), None);

pub fn flag_float(&self, name: &str) -> Option<f64>

Gets a flag value as a float

Arguments

• name - The name of the flag

Returns

Returns Some(f64) if the flag exists and can be parsed as a float, None otherwise

Examples

use flag_rs::context::Context;

let mut ctx = Context::new(vec![]);
ctx.set_flag("ratio".to_string(), "0.75".to_string());

assert_eq!(ctx.flag_float("ratio"), Some(0.75));
assert_eq!(ctx.flag_float("missing"), None);

pub fn flag_str_or<'a>(&'a self, name: &str, default: &'a str) -> &'a str

Gets a flag value as a string, returning a default if not present

Arguments

• name - The name of the flag
• default - The default value to return if the flag is not set

Returns

Returns the flag value if present, or the default value

Examples

use flag_rs::context::Context;

let mut ctx = Context::new(vec![]);
ctx.set_flag("env".to_string(), "production".to_string());

assert_eq!(ctx.flag_str_or("env", "development"), "production");
assert_eq!(ctx.flag_str_or("missing", "development"), "development");

Examples found in repository

examples/flag_completion_demo.rs (line 79)

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/builder_api_demo.rs (line 76)

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 flag_bool_or(&self, name: &str, default: bool) -> bool

Gets a flag value as a boolean, returning a default if not present

Arguments

• name - The name of the flag
• default - The default value to return if the flag is not set or cannot be parsed

Examples

use flag_rs::context::Context;

let mut ctx = Context::new(vec![]);
ctx.set_flag("verbose".to_string(), "true".to_string());

assert_eq!(ctx.flag_bool_or("verbose", false), true);
assert_eq!(ctx.flag_bool_or("missing", false), false);

Examples found in repository

examples/builder_api_demo.rs (line 79)

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 flag_int_or(&self, name: &str, default: i64) -> i64

Gets a flag value as an integer, returning a default if not present

Arguments

• name - The name of the flag
• default - The default value to return if the flag is not set or cannot be parsed

Examples

use flag_rs::context::Context;

let mut ctx = Context::new(vec![]);
ctx.set_flag("port".to_string(), "8080".to_string());

assert_eq!(ctx.flag_int_or("port", 3000), 8080);
assert_eq!(ctx.flag_int_or("missing", 3000), 3000);

Examples found in repository

examples/flag_completion_demo.rs (line 124)

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/builder_api_demo.rs (line 115)

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 flag_float_or(&self, name: &str, default: f64) -> f64

Gets a flag value as a float, returning a default if not present

Arguments

• name - The name of the flag
• default - The default value to return if the flag is not set or cannot be parsed

Examples

use flag_rs::context::Context;

let mut ctx = Context::new(vec![]);
ctx.set_flag("ratio".to_string(), "0.75".to_string());

assert_eq!(ctx.flag_float_or("ratio", 0.5), 0.75);
assert_eq!(ctx.flag_float_or("missing", 0.5), 0.5);

pub fn set<T: Any + Send + Sync>(&mut self, value: T)

Stores a typed value in the context

Values are stored by their type, so only one value of each type can be stored at a time. Storing a new value of the same type will overwrite the previous value.

Type Parameters

• T - The type of value to store (must be Send + Sync)

Examples

use flag_rs::context::Context;

struct ApiClient {
    endpoint: String,
}

let mut ctx = Context::new(vec![]);
ctx.set(ApiClient { endpoint: "https://api.example.com".to_string() });

pub fn get<T: Any + Send + Sync>(&self) -> Option<&T>

Retrieves a typed value from the context

Type Parameters

• T - The type of value to retrieve

Returns

Returns Some(&T) if a value of that type exists, None otherwise

pub fn get_mut<T: Any + Send + Sync>(&mut self) -> Option<&mut T>

Retrieves a mutable reference to a typed value from the context

Type Parameters

• T - The type of value to retrieve

Returns

Returns Some(&mut T) if a value of that type exists, None otherwise