- Notifications
You must be signed in to change notification settings - Fork82
Docopt for Rust (command line argument parser).
License
Unlicense and 2 other licenses found
Licenses found
docopt/docopt.rs
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
This crate is unlikely to see significant future evolution. The primary reasonto choose this crate for a new project is if you're specifically interested inusingdocopt syntax for your project. However, the widerdocopt project is mostly unmaintained at this point.
Consider usingclap or possiblystructopt instead.
Note that this crate has some significant bugs. The two biggest ones are thelack ofOsStr support and some severe performance problems in not-uncommonedge cases.
Docopt for Rust with automatic type based decoding (i.e., data validation).This implementation conforms to theofficial description of Docopt andpasses its test suite.
Dual-licensed under MIT or theUNLICENSE.
This crate is fully compatible with Cargo. Just add it to yourCargo.toml:
[dependencies]docopt ="1"serde = {version ="1",features = ["derive"] }
Here is a full working example. Notice that you can specify the types of eachof the named values in the Docopt usage string. Values will be automaticallyconverted to those types (or an error will be reported).
use docopt::Docopt;use serde::Deserialize;constUSAGE:&'staticstr ="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 --versionOptions: -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)]structArgs{flag_speed:isize,flag_drifting:bool,arg_name:Vec<String>,arg_x:Option<i32>,arg_y:Option<i32>,cmd_ship:bool,cmd_mine:bool,}fnmain(){let args:Args =Docopt::new(USAGE).and_then(|d| d.deserialize()).unwrap_or_else(|e| e.exit());println!("{:?}", args);}
The field names of the struct map like this:
-g => flag_g--group => flag_group--group <arg> => flag_groupFILE => arg_FILE<file> => arg_filebuild => cmd_buildThe reference implementation of Docopt returns a Python dictionary with nameslike<arg> or--flag. If you prefer this access pattern, then you can usedocopt::ArgvMap. The disadvantage is that you have to do all of your typeconversion manually. Here's the canonical Docopt example with a hash table:
use docopt::Docopt;constUSAGE:&'staticstr ="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 --versionOptions: -h --help Show this screen. --version Show version. --speed=<kn> Speed in knots [default: 10]. --moored Moored (anchored) mine. --drifting Drifting mine.";fnmain(){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>"));}
This particular implementation bundles a command calleddocopt-wordlist thatcan be used to automate tab completion. This repository also collects somebasic completion support for various shells (currently only bash) in thecompletions directory.
You can use them to setup tab completion on your system. It should work withany program that uses Docopt (or rather, any program that outputs usagemessages that look like Docopt). For example, to get tab completion support forCargo, you'll have to installdocopt-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
MyCSV 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 improvementsthat I'd like to make:
- Take context into account when completing. For example, it should bepossible 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 doubtI'll venture outside of bash any time soon.)
- Make tab completion support more seamless. The way it works right now ispretty hacky by intermingling file/directory completion.
About
Docopt for Rust (command line argument parser).
Resources
License
Unlicense and 2 other licenses found
Licenses found
Uh oh!
There was an error while loading.Please reload this page.