immargs 0.1.0

No-hassle, on-the-spot, command line argument parser
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

# immargs - Immediate Arguments

[![Crates.io](https://img.shields.io/crates/v/immargs?logo=rust&label=Crates.io&labelColor=black)](https://crates.io/crates/immargs)
[![Docs.rs](https://img.shields.io/docsrs/immargs?logo=rust&label=Docs.rs&labelColor=black)](https://docs.rs/immargs/)
[![Built & Test](https://img.shields.io/github/actions/workflow/status/pliden/immargs/build-test.yaml?logo=github&label=Build%20%26%20Test&labelColor=black)](https://github.com/pliden/immargs/actions/workflows/build-test.yaml)

__No-hassle, on-the-spot, command line argument parsing for Rust__

Highlights:

* Straightforward declaration of arguments with proc-macro.
* Supports [POSIX](https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap12.html)/[GNU](https://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html) argument syntax conventions.
* Supports arguments of any type that implements `FromStr` + `Debug`.
* Supports (sub)commands, with aliases.
* Supports declaration of conflicting arguments.
* Supports automatic `--version` and `--help` handling, with possibility to opt-out.
* Tested on Linux, macOS and Windows.
* No run-time dependencies.

[Full documentation](https://docs.rs/immargs/)

## Example

```rust
use immargs::immargs_from_env;

let args = immargs_from_env! {
    --force               "overwrite destination",
    -l --log <level> u8   "set log level",
    -h --help             "print help message",
    <src>... String       "source(s)",
    <dest> String         "destination",
};

// Assuming this program was executed with "myprog -l 3 Src0 Src1 Dest"
assert!(!args.force);
assert!(args.log == Some(3));
assert!(args.src.len() == 2);
assert!(args.src[0] == "Src0");
assert!(args.src[1] == "Src1");
assert!(args.dest == "Dest");
```

## Command Line Argument Syntax

The following [POSIX/GNU](https://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html)
argument syntax conventions are supported:
* Short option, `-` followed by a single character, e.g. `-f`.
* Long option, `--` followed by two or more characters, e.g. `--foo`.
* Short/Long option with separate value, e.g. `-f 100` or `--foo 100`.
* Short/Long option with attached value delimited by `=`, e.g. `-f=100` or `--foo=100`.
* Short option with attached value without delimiter, e.g. `-f100`.
* Combined short options, e.g. `-abc` is equivalent to `-a -b -c`.
* Short/Long options may appear in any order, but before any non-option arguments.
* Short/Long options may appear multiple times, the last appearance takes precedence unless
  it's a _variadic_ (repeatable) option, where the number of times the option appears has
  meaning, e.g. `-vvv` where each `-v` increases the verbosity level.
* The order of non-option arguments carries meaning.
* A standalone `-` argument is treated as a non-option argument.
* A standalone `--` argument marks the end of options. Any following arguments are treated
  as non-option arguments.

## License

Licensed under either of

 * Apache License, Version 2.0
   ([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
 * MIT license
   ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)

at your option.

## Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.