# docopt — CLI Argument Parser from Help Messages

> A command-line argument parser that generates itself from a usage message written in a human-readable format, available for Python, JavaScript, Rust, Go, and many other languages.

## Install

Save in your project root:

# docopt — CLI Argument Parser from Help Messages

## Quick Use
```bash
# Install (Python)
pip install docopt

# Example script (naval_fate.py)
python3 -c "
"""Naval Fate.

Usage:
  naval_fate ship new <name>...
  naval_fate ship shoot <x> <y>
  naval_fate -h | --help
  naval_fate --version

Options:
  -h --help     Show this screen.
  --version     Show version.
"""
from docopt import docopt
args = docopt(__doc__, version='Naval Fate 2.0', argv=['ship', 'new', 'Titanic'])
print(args)
"
```

## Introduction
docopt takes a different approach to CLI argument parsing: you write the help message first, and docopt parses it to build the argument parser automatically. This means your usage documentation is always in sync with your actual argument handling. The idea originated in Python and has been ported to over 20 programming languages, making it a universal pattern for CLI design.

## What docopt Does
- Parses command-line arguments based on a POSIX-style usage message you write as a docstring
- Supports commands, positional arguments, required and optional flags, and repeating elements
- Returns a simple dictionary mapping argument names to their parsed values
- Validates user input against the usage pattern and prints help on mismatch
- Works across 20+ languages including Python, JavaScript, Ruby, Go, Rust, C, and Bash

## Architecture Overview
docopt works in two phases. First, it parses the usage message string using a formal grammar that recognizes POSIX conventions: uppercase WORDS are positional args, `--flags` are options, `[brackets]` denote optional elements, and `(parens)` denote required groups. Second, it matches the actual argv against the parsed pattern tree, extracting values and setting boolean flags. The result is a flat dictionary. There is no code generation or class hierarchy involved, keeping the implementation under 500 lines in most language ports.

## Self-Hosting & Configuration
- Install for your language: `pip install docopt` (Python), `npm install docopt` (JS), `cargo add docopt` (Rust)
- Write your usage message following POSIX conventions as a module docstring or string constant
- Call `docopt(doc)` with the usage string to get a dictionary of parsed arguments
- Use `--` in your usage pattern to separate options from positional arguments
- Set `version=` to enable automatic `--version` flag handling

## Key Features
- Usage message IS the parser: documentation and parsing logic never drift apart
- Zero boilerplate: no argument builder chains, decorators, or configuration objects
- Language-agnostic pattern implemented in 20+ languages with identical behavior
- Supports complex CLI grammars including subcommands, mutually exclusive groups, and repeating args
- Tiny implementation (under 500 lines in Python) with no external dependencies

## Comparison with Similar Tools
- **argparse** — Python stdlib; requires imperative code to define each argument; docopt uses a declarative usage string
- **Click** — decorator-based Python CLI framework with more features (prompts, colors); docopt is simpler and language-agnostic
- **Typer** — builds CLIs from type hints; docopt builds them from documentation strings
- **Cobra** — Go CLI framework with code generation; docopt's Go port uses the same doc-first approach
- **Clap** — Rust's dominant CLI parser with derive macros; docopt's Rust port trades features for simplicity

## FAQ
**Q: Is docopt still maintained?**
A: The original Python implementation is stable and feature-complete. Community ports in other languages are maintained independently.

**Q: Can I use subcommands with docopt?**
A: Yes. List subcommands in your usage pattern and docopt will set the matching command to True in the result dictionary.

**Q: How does docopt handle type conversion?**
A: docopt returns all values as strings (or booleans for flags). You handle conversion yourself, which keeps the library focused on parsing.

**Q: What happens if the user provides invalid arguments?**
A: docopt prints the usage message and exits with a non-zero status code, following standard CLI conventions.

## Sources
- https://github.com/docopt/docopt
- http://docopt.org/

---
Source: https://tokrepo.com/en/workflows/asset-f475c8e4
Author: AI Open Source