clap/v3_warn_cases.md

These are cases which could be detected by `clap`, and potentially warn at compile time. Maybe even with a nice web URL to more info.

# Abrv. Syntax

First, a little about the syntax to understand the setup of rule. This syntax will make each rule more concise so we don't have to write an entire `clap` definition.

## Arg Types

* `--opt` is an option
* `--flag` is a flag
* `#` (i.e. `1` or `2`) is a positional argument
* `val` is an option value

## Modifiers

Can be used on `val` or Arg types

* `*`: zero or more
* `+`: one or more
* `?`: zero or one
* `{#,#}`: # to # times (i.e. `{1,4}` is one to four times)
* `<>`: required
* `=`: requires equals
* Ends in `,`: requires delimiter
* `(foo,bar)`: values can only be `foo` or `bar`

# --opt val? 1

## Ambiguous Uses

```
$ prog --opt foo
# is foo option val or positional?
```

## Non-Ambiguous Uses

```
$ prog 1 --opt
$ prog --opt -- 1
```

## Fixes

### Require equals on `--opt`

```
$ prog --opt foo
# foo is positional

$ prog --opt=val foo
```

# --opt val+ 1

## Ambiguous Uses

```
$ prog --opt foo bar
# is bar option val or positional?
```

## Non-Ambiguous Uses

```
$ prog 1 --opt val
$ prog --opt val -- 1
```

## Fixes

### `--opt` only one val per occurrence

```
$ prog --opt foo bar
# bar is positional

$ prog --opt val bar --opt foo
# bar is positional
```