Initial commit

skills/clap-patterns/examples/quick-start.md

@@ -0,0 +1,164 @@
+# Clap Quick Start Guide
+
+This guide will help you build your first Clap CLI application in minutes.
+
+## Prerequisites
+
+- Rust installed (1.70.0 or newer)
+- Cargo (comes with Rust)
+
+## Step 1: Create a New Project
+
+```bash
+cargo new my-cli
+cd my-cli
+```
+
+## Step 2: Add Clap Dependency
+
+Edit `Cargo.toml`:
+
+```toml
+[dependencies]
+clap = { version = "4.5", features = ["derive"] }
+```
+
+## Step 3: Write Your First CLI
+
+Replace `src/main.rs` with:
+
+```rust
+use clap::Parser;
+
+/// Simple program to greet a person
+#[derive(Parser)]
+#[command(author, version, about, long_about = None)]
+struct Args {
+    /// Name of the person to greet
+    #[arg(short, long)]
+    name: String,
+
+    /// Number of times to greet
+    #[arg(short, long, default_value_t = 1)]
+    count: u8,
+}
+
+fn main() {
+    let args = Args::parse();
+
+    for _ in 0..args.count {
+        println!("Hello {}!", args.name)
+    }
+}
+```
+
+## Step 4: Build and Run
+
+```bash
+# Build the project
+cargo build --release
+
+# Run with arguments
+./target/release/my-cli --name Alice --count 3
+
+# Check help output
+./target/release/my-cli --help
+```
+
+## Expected Output
+
+```
+$ ./target/release/my-cli --name Alice --count 3
+Hello Alice!
+Hello Alice!
+Hello Alice!
+```
+
+## Help Output
+
+```
+$ ./target/release/my-cli --help
+Simple program to greet a person
+
+Usage: my-cli --name <NAME> [--count <COUNT>]
+
+Options:
+  -n, --name <NAME>     Name of the person to greet
+  -c, --count <COUNT>   Number of times to greet [default: 1]
+  -h, --help            Print help
+  -V, --version         Print version
+```
+
+## Next Steps
+
+1. **Add Subcommands**: See `subcommands.rs` template
+2. **Add Validation**: See `value-parser.rs` template
+3. **Environment Variables**: See `env-variables.rs` template
+4. **Type-Safe Options**: See `value-enum.rs` template
+
+## Common Patterns
+
+### Optional Arguments
+
+```rust
+#[arg(short, long)]
+output: Option<String>,
+```
+
+### Multiple Values
+
+```rust
+#[arg(short, long, num_args = 1..)]
+files: Vec<PathBuf>,
+```
+
+### Boolean Flags
+
+```rust
+#[arg(short, long)]
+verbose: bool,
+```
+
+### With Default Value
+
+```rust
+#[arg(short, long, default_value = "config.toml")]
+config: String,
+```
+
+### Required Unless Present
+
+```rust
+#[arg(long, required_unless_present = "config")]
+database_url: Option<String>,
+```
+
+## Troubleshooting
+
+### "Parser trait not found"
+
+Add the import:
+```rust
+use clap::Parser;
+```
+
+### "derive feature not enabled"
+
+Update `Cargo.toml`:
+```toml
+clap = { version = "4.5", features = ["derive"] }
+```
+
+### Help text not showing
+
+Add doc comments above fields:
+```rust
+/// This shows up in --help output
+#[arg(short, long)]
+```
+
+## Resources
+
+- Full templates: `skills/clap-patterns/templates/`
+- Helper scripts: `skills/clap-patterns/scripts/`
+- Official docs: https://docs.rs/clap/latest/clap/