clap-version-flag 1.0.7

# Quick Start Guide - clap-version-flag


Get up and running with colorful version output in **less than 5 minutes**! 🚀

---

## ⚡ 30-Second Setup


### Step 1: Add to Your Project


```toml
# Cargo.toml

[dependencies]
clap = { version = "4.5", features = ["derive"] }
clap-version-flag = "1.0.5"
```

### Step 2: Use in Your Code


```rust
// main.rs
use clap::Parser;
use clap_version_flag::colorful_version;

#[derive(Parser)]

struct Cli {
    #[arg(short, long)]
    name: String,
}

fn main() {
    let version = colorful_version!();
    let cli = Cli::parse();
    
    println!("Hello, {}!", cli.name);
}
```

### Step 3: Test It!


```bash
cargo run -- --version
```

**Output:**
```
myapp v1.0.0 by Your Name
```
*(But in beautiful colors!)* 🌈

---

## 🎨 Common Use Cases


### 1. Basic CLI App


The simplest way to add colorful version:

```rust
use clap::Parser;
use clap_version_flag::colorful_version;

#[derive(Parser)]

#[command(name = "myapp", about = "My awesome CLI tool")]

struct Cli {
    /// Input file
    input: String,
}

fn main() {
    let version = colorful_version!();
    let cli = Cli::parse();
    
    println!("Processing: {}", cli.input);
}
```

**Usage:**
```bash
$ myapp file.txt         # Normal usage
$ myapp --version        # Shows colored version
$ myapp --help          # Shows help (clap's default)
```

---

### 2. Custom Brand Colors


Match your brand identity:

```rust
use clap_version_flag::colorful_version;

fn main() {
    // Your brand colors
    let version = colorful_version!(
        "#FFFFFF",  // White text
        "#FF6B6B",  // Your brand red background
        "#4ECDC4",  // Your brand teal for version
        "#FFE66D"   // Your brand yellow for author
    );
    
    version.print();
}
```

---

### 3. Multiple Color Schemes


Different themes for different users:

```rust
use clap_version_flag::{colorful_version, ColorfulVersion};
use std::env;

fn main() {
    let version = if env::var("DARK_MODE").is_ok() {
        // Dark theme
        colorful_version!("#E0E0E0", "#1A1A1A", "#FFA500", "#87CEEB")
    } else {
        // Light theme (default)
        colorful_version!("#000000", "#FFFFFF", "#0066CC", "#CC0066")
    };
    
    version.print();
}
```

---

### 4. With Automatic Version Handling


Let the library handle version checking:

```rust
use clap::{Parser, CommandFactory};
use clap_version_flag::{colorful_version, parse_with_version};

#[derive(Parser)]

struct Cli {
    #[arg(short, long)]
    output: String,
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let version = colorful_version!();
    
    // This automatically handles --version flag
    let cli: Cli = parse_with_version(Cli::command(), &version)?;
    
    println!("Output to: {}", cli.output);
    Ok(())
}
```

---

### 5. Builder Pattern (No Derive)


If you prefer the builder pattern:

```rust
use clap::{Arg, Command};
use clap_version_flag::{colorful_version, ColorfulVersionExt};

fn main() {
    let version = colorful_version!();
    
    let matches = Command::new("myapp")
        .with_colorful_version(&version)
        .arg(Arg::new("input")
            .short('i')
            .long("input")
            .required(true))
        .get_matches();
    
    // Check version flag manually
    version.check_and_exit(&matches);
    
    // Continue with your app logic
    let input = matches.get_one::<String>("input").unwrap();
    println!("Input: {}", input);
}
```

---

### 6. RGB Colors


If you prefer RGB tuples:

```rust
use clap_version_flag::ColorfulVersion;

fn main() {
    let version = ColorfulVersion::new("myapp", "1.0.0", "Your Name")
        .with_rgb_colors(
            (255, 255, 255),  // White foreground
            (170, 0, 255),    // Purple background
            (255, 255, 0),    // Yellow version
            (0, 255, 255)     // Cyan author
        );
    
    version.print();
}
```

---

### 7. Dynamic Values


Use runtime values instead of Cargo.toml:

```rust
use clap_version_flag::ColorfulVersion;

fn main() {
    // Load from config file or database
    let app_name = load_app_name_from_config();
    let version_num = load_version();
    
    let version = ColorfulVersion::new(app_name, version_num, "Your Name");
    version.print();
}

fn load_app_name_from_config() -> String {
    // Your config loading logic
    String::from("myapp")
}

fn load_version() -> String {
    String::from("1.0.0")
}
```

---

## 🎯 Pro Tips


### Tip 1: Add as a Feature Flag


```toml
# Cargo.toml

[features]
colorful = ["clap-version-flag"]

[dependencies]
clap-version-flag = { version = "1.0.5", optional = true }
```

```rust
// main.rs
#[cfg(feature = "colorful")]

use clap_version_flag::colorful_version;

fn main() {
    #[cfg(feature = "colorful")]
    {
        let version = colorful_version!();
        version.print();
    }
    
    #[cfg(not(feature = "colorful"))]
    {
        println!("{} v{}", env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));
    }
}
```

### Tip 2: Combine with `structopt` Migration


If you're migrating from `structopt` to `clap` v4:

```rust
// Old structopt code
// #[derive(StructOpt)]
// struct Cli { ... }

// New clap v4 code
use clap::Parser;
use clap_version_flag::colorful_version;

#[derive(Parser)]

struct Cli {
    // Your fields
}

fn main() {
    let version = colorful_version!();
    let cli = Cli::parse();
    // ...
}
```

### Tip 3: Use with Subcommands


```rust
use clap::{Parser, Subcommand};
use clap_version_flag::colorful_version;

#[derive(Parser)]

#[command(name = "myapp")]

struct Cli {
    #[command(subcommand)]
    command: Commands,
}

#[derive(Subcommand)]

enum Commands {
    /// Add a new item
    Add { name: String },
    /// Remove an item
    Remove { id: u32 },
}

fn main() {
    let version = colorful_version!();
    let cli = Cli::parse();
    
    match cli.command {
        Commands::Add { name } => println!("Adding: {}", name),
        Commands::Remove { id } => println!("Removing: {}", id),
    }
}
```

---

## 🐛 Troubleshooting


### Problem: Shows "clap-version-flag" instead of my app name


**Solution:** Make sure you're using version **1.0.5** or later:

```toml
[dependencies]
clap-version-flag = "1.0.5"  # ← Must be 1.0.5+
```

### Problem: Conflicts with clap's built-in version


**Solution:** Use the `with_colorful_version()` extension (it auto-disables clap's version):

```rust
use clap_version_flag::ColorfulVersionExt;

let cmd = Command::new("app")
    .with_colorful_version(&version);  // ← Handles conflicts
```

### Problem: Colors not showing in terminal


**Check:**
1. Your terminal supports colors (most modern terminals do)
2. Not redirecting to file: `app --version > file.txt` won't show colors
3. Try setting: `export CLICOLOR_FORCE=1`

### Problem: Want to disable colors


**Option 1:** Use plain string:
```rust
let version = colorful_version!();
println!("{}", version.as_plain_string());  // No colors
```

**Option 2:** Use `no-color` feature:
```toml
[dependencies]
clap-version-flag = { version = "1.0.5", features = ["no-color"] }
```

---

## 📚 Next Steps


### Learn More


- **Full Documentation:** [README.md](README.md)
- **API Reference:** [docs.rs/clap-version-flag](https://docs.rs/clap-version-flag)
- **Migration Guide:** [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md)
- **Examples:** Check the [`examples/`](examples/) directory

### Explore Examples


```bash
# Run the basic example

cargo run --example basic -- --version

# Run custom colors example

cargo run --example custom_colors

# Run full integration example

cargo run --example full_integration -- --help
```

### Advanced Features


Once you're comfortable with the basics, explore:
- Custom RGB colors
- Theme switching
- Dynamic color selection
- Integration with logging
- CI/CD color handling

---

## 🎨 Color Palettes


### Ready-to-Use Color Schemes


#### Default (Purple Theme)

```rust
colorful_version!("#FFFFFF", "#AA00FF", "#FFFF00", "#00FFFF")
```

#### GitHub Dark

```rust
colorful_version!("#FFFFFF", "#24292E", "#0366D6", "#6F42C1")
```

#### Dracula

```rust
colorful_version!("#F8F8F2", "#282A36", "#FF79C6", "#8BE9FD")
```

#### Monokai

```rust
colorful_version!("#F8F8F2", "#272822", "#FD971F", "#A6E22E")
```

#### Solarized Dark

```rust
colorful_version!("#FDF6E3", "#002B36", "#B58900", "#2AA198")
```

#### Nord

```rust
colorful_version!("#ECEFF4", "#2E3440", "#88C0D0", "#A3BE8C")
```

#### High Contrast

```rust
colorful_version!("#FFFFFF", "#000000", "#FFFF00", "#00FF00")
```

---

## ⚡ Performance Notes


- **Compile Time:** ~2-3 seconds (no noticeable impact)
- **Runtime:** Negligible (< 1ms for color formatting)
- **Memory:** ~200 bytes per `ColorfulVersion` instance
- **Dependencies:** Only `clap` and `colored` (both lightweight)

---

## 🤝 Contributing


Found a bug or have a feature request?

1. **Issues:** [GitHub Issues](https://github.com/cumulus13/clap-version-flag/issues)
2. **Discussions:** [GitHub Discussions](https://github.com/cumulus13/clap-version-flag/discussions)
3. **Pull Requests:** Always welcome!

---

## 📄 License


Dual licensed under MIT OR Apache-2.0 (your choice)

---

## 🎉 You're All Set!


You now know how to:
- ✅ Add colorful version output to your CLI
- ✅ Customize colors to match your brand
- ✅ Use different integration patterns
- ✅ Handle common issues
- ✅ Explore advanced features

**Happy coding!** 🚀

---

**Questions?** Check the [README.md](README.md) or open an [issue](https://github.com/cumulus13/clap-version-flag/issues).

**Made with ❤️ by Hadi Cahyadi**