docopt.rs

Docopt for Rust turns the plain-text “Usage:” section you’d already write for a program’s —help output into the argument parser itself, so there is no separate builder API or flag-definition DSL to keep in sync with the docs. It conforms to the official Docopt specification and passes the reference Docopt test suite, matching argv against every usage pattern declared in the string and exposing results either through a raw ArgvMap or, via a serde Deserializer, decoded straight into a typed struct.

The crate ships a small companion binary, docopt-wordlist, along with bash completion scripts that use the same usage-string parsing to drive shell tab-completion. The README explicitly marks the project unmaintained and recommends newer alternatives like clap or structopt for new projects, but it remains a working, spec-compliant reference implementation of the Docopt approach in Rust.

What You Get

• A Docopt::new(USAGE) entry point that parses a plain usage string into an internal pattern grammar
• Argv matching against every usage line declared in that string, including options, positional arguments, and repeated values
• A serde-powered Deserializer that decodes matched arguments straight into a caller-defined struct
• A lower-level ArgvMap with get_bool/get_str/get_vec accessors for callers who prefer not to define a struct
• Typed Error variants (Usage, Argv, NoMatch, Deserialize, Help, Version) with an exit() helper that prints and sets the correct process exit code
• A docopt-wordlist companion binary and bash completion scripts for shell tab-completion of Docopt-style programs

Common Use Cases

• Parsing arguments for a small Rust CLI tool without hand-writing a flag-definition DSL
• Reusing an existing docopt-style usage string (ported from a Python or other-language tool) as the parser spec
• Decoding argv directly into a typed struct via serde instead of manually converting string values
• Providing —help/—version behavior and standard usage-error output with minimal boilerplate
• Adding tab-completion to a Docopt-based CLI via the bundled docopt-wordlist utility

Under The Hood

Architecture Docopt separates concerns into three modules: parse.rs turns the usage-string grammar into an internal pattern tree, dopt.rs exposes the public Docopt/ArgvMap/Error API plus a serde-based Deserializer, and synonym.rs is a small SynonymMap for aliasing short and long flag names to the same key. The flow is a linear three-stage pipeline: Docopt::new parses the USAGE string via the Parser in parse.rs, .argv(…).parse() matches real argv tokens against that pattern to produce an ArgvMap, and .deserialize() feeds the ArgvMap through the custom Deserializer into a caller-defined struct. There is no dependency injection and a single well-defined data path; changing the pattern representation in parse.rs would ripple through both the ArgvMap accessors and the Deserializer, since both read the same Value enum.

Tech Stack docopt is a Rust crate (2018 edition) with a compact dependency set: lazy_static for regex caching, regex (std and unicode features) for tokenizing the usage grammar, serde with the derive feature for the typed-decoding API, and strsim for did-you-mean flag suggestions. It has no async runtime and no I/O framework beyond stdin/stdout for error and help output; the crate builds a companion docopt-wordlist binary declared via a [[bin]] entry in Cargo.toml, and ships bash completion scripts alongside it. Build tooling is plain Cargo with a Makefile wrapper for docs and tests.

Code Quality Tests live in src/test/mod.rs, suggestions.rs, and a substantial testcases.rs that loads a bundled testcases.docopt fixture and asserts against the official Docopt reference test suite, a table-driven approach that goes further than most crates’ unit tests. Error handling is explicit and typed through the Error enum (Usage, Argv, NoMatch, Deserialize, WithProgramUsage, Help, Version), which implements std::error::Error rather than swallowing failures. Naming follows idiomatic Rust conventions, and the crate denies missing_docs at the crate level, forcing every public item to carry documentation. There is no modern CI configuration visible in the repository, and the project has been explicitly unmaintained since 2021.

API Design The defining design choice, inherited from the original Python docopt, is that the human-readable Usage: section of a program’s —help text is the parser specification itself, with no separate builder API or flag-definition macros to keep in sync. A serde Deserializer then decodes matched values straight into a plain struct, keeping call-site boilerplate to a handful of lines. It is a distinctive approach next to macro- or builder-based Rust CLI parsers, but the README itself candidly recommends clap or structopt for new projects and flags real limitations, including missing OsStr support and performance problems on some inputs, alongside the project’s unmaintained status.