THIS CRATE IS UNMAINTAINED
This crate is unlikely to see significant future evolution. The primary reason to choose this crate for a new project is if you're specifically interested in using docopt syntax for your project. However, the wider docopt project is mostly unmaintained at this point.
Consider using clap or possibly structopt instead.
Note that this crate has some significant bugs. The two biggest ones are the lack of OsStr support and some severe performance problems in not-uncommon edge cases.
docopt
Docopt for Rust with automatic type based decoding (i.e., data validation). This implementation conforms to the official description of Docopt and passes its test suite.
Dual-licensed under MIT or the UNLICENSE.
Documentation
Installation
This crate is fully compatible with Cargo. Just add it to your Cargo.toml:
[dependencies]
docopt = "1"
serde = { version = "1", features = ["derive"] }
Quick example
Here is a full working example. Notice that you can specify the types of each of the named values in the Docopt usage string. Values will be automatically converted to those types (or an error will be reported).
use docopt::Docopt;
use serde::Deserialize;
const USAGE: &'static str = "
Naval Fate.
Usage:
naval_fate.py ship new <name>...
naval_fate.py ship <name> move <x> <y> [--speed=<kn>]
naval_fate.py ship shoot <x> <y>
naval_fate.py mine (set|remove) <x> <y> [--moored | --drifting]
naval_fate.py (-h | --help)
naval_fate.py --version
Options:
-h --help Show this screen.
--version Show version.
--speed=<kn> Speed in knots [default: 10].
--moored Moored (anchored) mine.
--drifting Drifting mine.
";
#[derive(Debug, Deserialize)]
struct Args {
flag_speed: isize,
flag_drifting: bool,
arg_name: Vec<String>,
arg_x: Option<i32>,
arg_y: Option<i32>,
cmd_ship: bool,
cmd_mine: bool,
}
fn main() {
let args: Args = Docopt::new(USAGE)
.and_then(|d| d.deserialize())
.unwrap_or_else(|e| e.exit());
println!("{:?}", args);
}
Struct field name mapping
The field names of the struct map like this:
-g => flag_g
--group => flag_group
--group <arg> => flag_group
FILE => arg_FILE
<file> => arg_file
build => cmd_build
Traditional Docopt API
The reference implementation of Docopt returns a Python dictionary with names like <arg> or --flag. If you prefer this access pattern, then you can use docopt::ArgvMap. The disadvantage is that you have to do all of your type conversion manually. Here's the canonical Docopt example with a hash table:
use docopt::Docopt;
const USAGE: &'static str = "
Naval Fate.
Usage:
naval_fate.py ship new <name>...
naval_fate.py ship <name> move <x> <y> [--speed=<kn>]
naval_fate.py ship shoot <x> <y>
naval_fate.py mine (set|remove) <x> <y> [--moored | --drifting]
naval_fate.py (-h | --help)
naval_fate.py --version
Options:
-h --help Show this screen.
--version Show version.
--speed=<kn> Speed in knots [default: 10].
--moored Moored (anchored) mine.
--drifting Drifting mine.
";
fn main() {
let args = Docopt::new(USAGE)
.and_then(|dopt| dopt.parse())
.unwrap_or_else(|e| e.exit());
println!("{:?}", args);
// You can conveniently access values with `get_{bool,count,str,vec}`
// functions. If the key doesn't exist (or if, e.g., you use `get_str` on
// a switch), then a sensible default value is returned.
println!("\nSome values:");
println!(" Speed: {}", args.get_str("--speed"));
println!(" Drifting? {}", args.get_bool("--drifting"));
println!(" Names: {:?}", args.get_vec("<name>"));
}
Tab completion support
This particular implementation bundles a command called docopt-wordlist that can be used to automate tab completion. This repository also collects some basic completion support for various shells (currently only bash) in the completions directory.
You can use them to setup tab completion on your system. It should work with any program that uses Docopt (or rather, any program that outputs usage messages that look like Docopt). For example, to get tab completion support for Cargo, you'll have to install docopt-wordlist and add some voodoo to your $HOME/.bash_completion file (this may vary for other shells).
Here it is step by step:
# Download and build `docopt-wordlist` (as part of the Docopt package)
$ git clone git://github.com/docopt/docopt.rs
$ cd docopt.rs
$ cargo build --release
# Now setup tab completion (for bash)
$ echo "DOCOPT_WORDLIST_BIN=\"$(pwd)/target/release/docopt-wordlist\"" >> $HOME/.bash_completion
$ echo "source \"$(pwd)/completions/docopt-wordlist.bash\"" >> $HOME/.bash_completion
$ echo "complete -F _docopt_wordlist_commands cargo" >> $HOME/.bash_completion
My CSV toolkit is supported too:
# shameless plug...
$ echo "complete -F _docopt_wordlist_commands xsv" >> $HOME/.bash_completion
Note that this is emphatically a first pass. There are several improvements that I'd like to make:
- Take context into account when completing. For example, it should be possible to only show completions that can lead to a valid Docopt match. This may be hard. (i.e., It may require restructuring Docopt's internals.)
- Support more shells. (I'll happily accept pull requests on this one. I doubt I'll venture outside of bash any time soon.)
- Make tab completion support more seamless. The way it works right now is pretty hacky by intermingling file/directory completion.
![[Issue] Optional arguments in final array](https://avatars.githubusercontent.com/u/1969593?v=4)
0 Jun 16, 2022
20 Nov 12, 2022
12 Nov 5, 2022
3 Sep 30, 2021
22 Nov 20, 2022
1.3k Dec 28, 2022
132 Oct 23, 2022
5 Aug 20, 2022
3 Oct 20, 2021
7 Jan 4, 2023
3 Jan 3, 2023
3 Nov 2, 2023
7 Mar 30, 2023
5 May 2, 2024
4 Dec 4, 2022
3.2k Dec 30, 2022
47 Nov 25, 2022
36 Jan 1, 2023
1.9k Jan 3, 2023