Compare commits
3 commits
Author | SHA1 | Date | |
---|---|---|---|
![]() |
831f65b27e | ||
![]() |
3563377a5e | ||
![]() |
426c0c9ef7 |
1 changed files with 10 additions and 11 deletions
21
README.md
21
README.md
|
@ -6,12 +6,11 @@ A command-line arrrrguments parser, written in Rust.
|
||||||
Synopsis
|
Synopsis
|
||||||
--------
|
--------
|
||||||
|
|
||||||
Most programs that provide a command-line interface use a special-purpose library to make the process easier, such as the GNU Project's `getopt` library. The Rust team provides their own alternative, `getoptions`, which deserves an award for the Most Originally Named Project Ever.
|
Most programs that provide a command-line interface use a special-purpose library to make the process easier, such as the GNU Project's `getopt` library. The Rust team provides their own alternative, `getopts`, which deserves an award for the Most Originally Named Project Ever.
|
||||||
|
|
||||||
In all seriousness, `getoptions` is a fantastic library that gives the developers all of the power necessary to create and interface with command-line arguments. However, with all that power comes complexity. `getoptions` -- while straight forward to use -- is verbose. The developer has to call different functions repeatedly in order to add different command-line options to their programs. While the only victim here is the developer's wrists due to carpal tunnel, I felt that there was a
|
In all seriousness, `getopts` is a fantastic library that gives the developers all of the power necessary to create and interface with command-line arguments. However, with all that power comes complexity. `getopts` -- while straight forward to use -- is verbose. The developer has to call different functions repeatedly in order to add different command-line options to their programs. While the only victim here is the developer's wrists due to carpal tunnel, I felt that there was a better way to do things.
|
||||||
better way to do things.
|
|
||||||
|
|
||||||
Enter Pirate (which should totally usurp `getoptions` for the award of Most Originally Named Project Ever).
|
Enter Pirate (which should totally usurp `getopts` for the award of Most Originally Named Project Ever).
|
||||||
|
|
||||||
Installation
|
Installation
|
||||||
------------
|
------------
|
||||||
|
@ -38,7 +37,7 @@ Using Pirate is simple. First, create a vector defining all of the valid options
|
||||||
let options = vec![
|
let options = vec![
|
||||||
"a/addend#The right side of the addition equation; default=1:",
|
"a/addend#The right side of the addition equation; default=1:",
|
||||||
"#Required Arguments",
|
"#Required Arguments",
|
||||||
":augend#The left side of an addition equation"
|
":/augend#The left side of an addition equation"
|
||||||
];
|
];
|
||||||
```
|
```
|
||||||
|
|
||||||
|
@ -46,7 +45,7 @@ Options are defined in a very specific format:
|
||||||
|
|
||||||
* Options that have an associated argument must be followed by a colon (:). The colon must be the last character of the option (see above for example).
|
* Options that have an associated argument must be followed by a colon (:). The colon must be the last character of the option (see above for example).
|
||||||
* Long-form options are denoted by a preceding slash (/). Options are able to have short- and long-forms. Options which are only long-form still need a preceding slash, e.g. `"/addend"`.
|
* Long-form options are denoted by a preceding slash (/). Options are able to have short- and long-forms. Options which are only long-form still need a preceding slash, e.g. `"/addend"`.
|
||||||
* Required program arguments must have a preceding colon as the first character of the opt, e.g. `":augend"`.
|
* Required program arguments must have a preceding colon as the first character of the opt, e.g. `":/augend"`.
|
||||||
* Option descriptions are denoted by a proceding hash (#). Descriptions are optional and are used to display helpful information about the option when displaying a program's usage information (typically when the `--help` flag is passed). Options with **only** a description (i.e. no short- or long-form name) are called "Groups", and are used to group options together when displaying usage.
|
* Option descriptions are denoted by a proceding hash (#). Descriptions are optional and are used to display helpful information about the option when displaying a program's usage information (typically when the `--help` flag is passed). Options with **only** a description (i.e. no short- or long-form name) are called "Groups", and are used to group options together when displaying usage.
|
||||||
|
|
||||||
Next, create a `Vars` struct, which is responsible for keeping track of all of the options, along with the program's name, defined for the program:
|
Next, create a `Vars` struct, which is responsible for keeping track of all of the options, along with the program's name, defined for the program:
|
||||||
|
@ -61,8 +60,8 @@ let vars: Vars = match pirate::vars("program-name", &options) {
|
||||||
Next, call the `pirate::matches()` function, passing in a vector of the program's environment arguments, along with a mutable reference to the `Vars` struct that you previously defined:
|
Next, call the `pirate::matches()` function, passing in a vector of the program's environment arguments, along with a mutable reference to the `Vars` struct that you previously defined:
|
||||||
|
|
||||||
```rust
|
```rust
|
||||||
let matches: Matches = match pirate::matches(env::args().collect(),
|
let args: Vec<String> = env::args().collect();
|
||||||
&mut vars) {
|
let matches: Matches = match pirate::matches(&args, &mut vars) {
|
||||||
Ok(m) => m,
|
Ok(m) => m,
|
||||||
Err(why) => {
|
Err(why) => {
|
||||||
println!("Error: {}", why);
|
println!("Error: {}", why);
|
||||||
|
@ -91,8 +90,8 @@ Something to remember when using the `get()` function: by default, the `pirate::
|
||||||
```rust
|
```rust
|
||||||
let options = vec!["l/long#An example opt"];
|
let options = vec!["l/long#An example opt"];
|
||||||
let vars = pirate::vars("program-name", &options);
|
let vars = pirate::vars("program-name", &options);
|
||||||
let matches = pirate::matches(&env::args().collect(),
|
let args: Vec<String> = env::args().collect();
|
||||||
&mut vars).unwrap();
|
let matches = pirate::matches(&args, &mut vars).unwrap();
|
||||||
|
|
||||||
let short = matches.get("l").unwrap(); // Error! This won't work!
|
let short = matches.get("l").unwrap(); // Error! This won't work!
|
||||||
let long = matches.get("long").unwrap(); // Success!
|
let long = matches.get("long").unwrap(); // Success!
|
||||||
|
@ -121,7 +120,7 @@ fn main() {
|
||||||
let options = vec![
|
let options = vec![
|
||||||
"a/addend#The right side of the addition equation; default=1:",
|
"a/addend#The right side of the addition equation; default=1:",
|
||||||
"#Required Arguments",
|
"#Required Arguments",
|
||||||
":augend#The left side of an addition equation"
|
":/augend#The left side of an addition equation"
|
||||||
];
|
];
|
||||||
let mut vars = vars("test", &options).unwrap();
|
let mut vars = vars("test", &options).unwrap();
|
||||||
|
|
||||||
|
|
Loading…
Add table
Reference in a new issue