Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
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.
Licensed under the UNLICENSE.
Current status
Fully functional but the design of the API is up for debate. I am seeking feedback.
Documentation
http://burntsushi.net/rustdoc/docopt
Installation
This crate is fully compatible with Cargo. Just add it to your Cargo.toml
:
[]
= "git://github.com/docopt/docopt.rs"
If you don't want to use the macro, then you can change your entry to
dependencies.docopt
.
Quick example
Here is a full working example:
extern crate serialize;
extern crate docopt;
use Docopt;
// Write the Docopt usage string.
static USAGE: &'static str = "
Usage: cp [-a] <source> <dest>
cp [-a] <source>... <dir>
Options:
-a, --archive Copy everything.
";
Here is the same example, but with the use of the docopt!
macro, which will
generate a struct for you:
extern crate serialize;
extern crate docopt;
extern crate docopt_macros;
docopt!
The field names of the struct map like this:
-g => flag_g
--group => flag_group
FILE => arg_FILE
<file> => arg_file
build => cmd_build
The Args
struct has one static method defined for it: docopt
. The method
returns a normal Docopt
value, which can be used to set configuration
options, argv
and parse or decode command line arguments.
Data validation example
Here's another example that shows how to specify the types of your arguments:
extern crate serialize;
extern crate docopt;
extern crate docopt_macros;
docopt!
In this example, specific type annotations were added. They will be
automatically inserted into the generated struct. You can override as many (or
as few) fields as you want. If you don't specify a type, then one of bool
,
uint
, String
or Vec<String>
will be chosen depending on the type of
argument. In this case, both arg_x
and arg_y
would have been String
.
If any value cannot be decoded into a value with the right type, then an error will be shown to the user.
And of course, you don't need the macro to do this. You can do the same thing with a manually written struct too.
Modeling rustc
Here's a selected subset for some of rustc
's options. This also shows how to
restrict values to a list of choices via an enum
type and demonstrates more
Docopt features.
extern crate serialize;
extern crate docopt;
extern crate docopt_macros;
docopt!
Viewing the generated struct
Generating a struct is pretty magical, but if you want, you can look at it by
expanding all macros. Say you wrote the above example for Usage: add <x> <y>
into a file called add.rs
. Then running:
rustc -L path/containing/docopt/lib --pretty expanded add.rs
Will show all macros expanded. In the generated code, you should be able to find the generated struct:
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:
extern crate docopt;
use Docopt;
static 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.
";