vecli 0.1.0

(this guide can also be found at the documentation)

A zero-dependency, minimal CLI framework that's genuinely readable, the tool you've been looking for.

# Getting Started

## Installation

To install `vecli` as a dependency, run:

```bash
cargo add vecli
```

which is the same as including it in your `Cargo.toml` file:

```toml
[dependencies]
vecli = "0.1"
```

## Building Your First App

Let's build your first app with `vecli`. This will be a simple "hello world" app that prints "hello" when run.
After adding `vecli` to your dependencies, we can start by making a new `App`.

```rust
use vecli::*;

fn main() {
    App::new("my-app")
        .run();
}
```

When you run the app, you should see something like:

```
error: No command provided. Try 'my-app --help'.
```

And when you run `--help` (or `cargo run -- --help`), you should see a usage message like this:

```
Usage: my-app <command> [options]

No commands available. Add some using .add_command()!
```

## Configuring Your App

There's a handful of configuration options available for your app to further customize and to make your app look professional, listed:

* **`.name("My App")`**: The human readable name for your app
* **`.description("the most awesome app ever")`**: The description for your app
* **`.version("0.1.0")`**: The version of your app
* `.print_help_if_no_args(true)`: Prints the help screen when no command is specified.
* `.print_help_on_fail(true)`: Prints help when no command found.

## Adding Commands

Now let's make the app print "Hello" when the user passes in `hello` as a command. We'll want this:

```bash
cargo run hello # would print:
# Hello!
```

Vecli makes this awfully simple. Use `add_command()` that takes a `Command`, and you can construct them like this:

```rust
app.add_command(
    Command::new("hello" /* The command the user would pass */, function /* The function that handles the command */)
)
```

And our `hello()` function:

```rust
fn hello(_ctx: &CommandContext) {
    println!("Hello!");
}
```

### Configuring Commands

Like you can configure an App, you can also configure your command to make it professional.

- **`.description("Prints hello and exit.")`**: The description of the command, what it does.
- **`.usage("[none]")`**: The usage for the command, will print alongside `my-app hello`.
- `.flag(Flag::new("silent"))`: Add a flag to the command, input is without the `--` prefix.
- `.strict_flags(true)`: If toggled, unknown flags will abort the program.

## Adding Flags

Adding flags like `--silent` and `--dry-run` is also (kind of) simplified. To add a flag to your command, use the
previously mentioned `.flag()` method.

To construct a flag, only the name is needed, but you can customize them with an alias and description:
- **`.alias("s")`**: An alias for the flag, in this case, `-s` will resolve to `--silent`. **CAUTION: Aliases will always return boolean!**
- **`.description("Not say hello.")`**: The description for the flag.

## CommandContext

Saw that CommandContext class earlier? Good eye. Vecli gives the handler the context of the command, including:

- `ctx.subcommand`: The command that comes after `hello`
- `ctx.positionals`: A vector of everything that comes after `subcommand`.
- `ctx.flags`: A `HashMap` of passed flags.

It's completely up to the function to check and act based on what context was given by Vecli. Keep this in mind!

---

And that's all you need to make a simple hello app using *vecli*! `--help` (even help for commands!) and `--version` is fully built-in to vecli.

Here's all of them combined:

```rust
use vecli::*;

fn hello(ctx: &CommandContext) {
    if !ctx.flags.contains_key("silent") {
        println!("Hello!")
    }
}

fn main() {
    App::new("my-app")
        .name("My App")
        .description("a very informative description")
        .print_help_if_no_args(true)
        .print_help_on_fail(true)
        .version("0.0.1")
        .add_command(
            Command::new("hello", hello)
                .description("prints hello and exit.")
                .usage("[none]")
                .flag(Flag::new("silent").alias("s").description("Not say hello."))
                .strict_flags(true),
        )
        .run();
}
```

If you want a feature added, please submit an issue to the [GitHub repository](https://github.com/razkar-studio/vecli.git)! 
This project is still very experimental, so expect bugs. When you *do* find one, also submit an issue! 
Feel free to read the rest of the documentation if you are a developer.

Cheers, RazkarStudio.