{"id":13994901,"url":"https://github.com/docopt/docopts","last_synced_at":"2025-06-15T13:09:29.866Z","repository":{"id":4218810,"uuid":"5340352","full_name":"docopt/docopts","owner":"docopt","description":"Shell interpreter for docopt, the command-line interface description language.","archived":false,"fork":false,"pushed_at":"2024-07-02T01:44:27.000Z","size":2209,"stargazers_count":504,"open_issues_count":25,"forks_count":53,"subscribers_count":22,"default_branch":"master","last_synced_at":"2024-11-29T17:38:01.954Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/docopt.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog.md","contributing":null,"funding":null,"license":"LICENSE-MIT","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-08-08T10:35:11.000Z","updated_at":"2024-10-22T09:50:48.000Z","dependencies_parsed_at":"2024-06-18T15:13:48.742Z","dependency_job_id":"d4a8ecf1-ddcf-41bc-89e3-0b21761deadf","html_url":"https://github.com/docopt/docopts","commit_stats":{"total_commits":245,"total_committers":18,"mean_commits":13.61111111111111,"dds":0.4938775510204082,"last_synced_commit":"62aed3d4cb02f36864ace03ecb89f8a200e311ca"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/docopt/docopts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docopt%2Fdocopts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docopt%2Fdocopts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docopt%2Fdocopts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docopt%2Fdocopts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/docopt","download_url":"https://codeload.github.com/docopt/docopts/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docopt%2Fdocopts/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259981475,"owners_count":22941149,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-09T14:03:10.075Z","updated_at":"2025-06-15T13:09:29.845Z","avatar_url":"https://github.com/docopt.png","language":"Shell","funding_links":[],"categories":["Shell","others"],"sub_categories":[],"readme":"# docopts\n\n[docopt](http://docopt.org/) for shell - make beautiful CLI with ease.\n\nStatus: working.\n\n`docopts` : the command line wrapper for bash.\n\nMost concepts are documented in the `docopt` (without S) manual - see [docopt.org](http://docopt.org/).\n\nMany examples use associative arrays in Bash 4+, but there is legacy support for Bash 3.2 on macOS (OS X) or legacy\nGNU/Linux OS.\n\n[make README.md]: # (./docopts --version | get_version \"This is a bug fix release:\")\n\n```\nThis is a bug fix release: v0.6.4-with-no-mangle-double-dash\n```\n\nThis release will be maintained for compatibility, only fixes will be provided. The 0.6.4 version is fully compatible with\nthe previous version of `docopts`. Except for `-` handling in global mode, which produces an error.\n\n## SYNOPSIS\n\n[make README.md]: # (./docopts --help | get_usage)\n\n```\n  docopts [options] -h \u003cmsg\u003e : [\u003cargv\u003e...]\n  docopts [options] [--no-declare] -A \u003cname\u003e   -h \u003cmsg\u003e : [\u003cargv\u003e...]\n  docopts [options] -G \u003cprefix\u003e  -h \u003cmsg\u003e : [\u003cargv\u003e...]\n  docopts [options] --no-mangle  -h \u003cmsg\u003e : [\u003cargv\u003e...]\n```\n\n## DESCRIPTION\n\n`docopts` parses the command line argument vector `\u003cargv\u003e` according to the\n[docopt](http://docopt.org) string `\u003cmsg\u003e` and echoes the results to standard\noutput as a snippet of Bash source code.  Passing this snippet as an argument to\n[`eval(1)`](http://man.cx/eval(1)) is sufficient for handling the CLI needs of\nmost scripts.\n\n### Global mode\n\nGlobal mode, is the default historical output of `docopts`. It will output\nglobals variable for storing parsed result.\n\nIf `\u003cargv\u003e` matches one of the usage patterns defined in `\u003cmsg\u003e`, `docopts`\ngenerates code for storing the parsed arguments as Bash variables. As most\ncommand line argument names are not valid Bash identifiers, some name mangling\nwill take place:\n\n* `\u003cAngle_Brackets\u003e` ==\u003e `Angle_Brackets`\n* `UPPER-CASE` ==\u003e `UPPER_CASE`\n* `--Long-Option` ==\u003e `Long_Option`\n* `-S` ==\u003e `S`\n* `-4` ==\u003e **INVALID** (without `-G`)\n\nIf one of the argument names cannot be mangled into a valid Bash identifier,\nor two argument names map to the same variable name, `docopts` will exit with\nan error, and you should really rethink your CLI, or use `-A` or `-G`.\nIf the double-dash is part of the `\u003cmsg\u003e` the matched item `--` will be skiped.\n\nNote: You can use `--no-mangle` if you still want full input, this wont\nproduce output suitable for bash `eval(1)` but can be parsed by your own\ncode. Double-dash `--` will be kept.\n\n`-G` is a variant of Global mode, which prefixes the globals mangled named with\n`\u003cprefix\u003e` + `_` + `Mangled_name`. In this mode double-dash `--` and single-dash\n`-` will be kept and will be mangled.\n\n* `--Long-Option` ==\u003e `prefix_Long_Option`\n* `--`  ==\u003e `prefix___`\n* `-`  ==\u003e `prefix__`\n\nNote that prefixed invalid mangled names still raise an error, if they resolve to\ninvalid bash identifier.\n\nPrefix gobals variable makes it easy to filter variable with `grep` or such, or to\navoid globals name collision.\n\nHandling `[-]` in global mode is not supported and raises an error when trying to mangle `-`.\nBut works for any other modes including `-G`. This behavior differs from python's version of\n`docopts` which would have skiped the positional `-` without error.\n\n```\n./docopts -h 'Usage: dump [-]' : -\ndocopts:error: Print_bash_global:Mangling not supported for: '-'\n```\n\nSingle-dash can be catch easily by reading it into a `FILENAME` parameter:\n\n```bash\n./docopts  -h 'Usage: prog parse FILENAME' : parse -\nparse=true\nFILENAME='-'\n```\n\nthen in your code:\n\n```bash\nf=\"$FILENAME\"\nif [[ $f == '-' ]] ; then\n\tf=/dev/stdin\nfi\n```\n\nA working example is provided in [examples/legacy_bash/cat-n_wrapper_example.sh](examples/legacy_bash/cat-n_wrapper_example.sh)\n\n### Associative Array mode\n\nAlternatively, `docopts` can be invoked with the `-A \u003cname\u003e` option, which\nstores the parsed arguments as fields of a Bash 4+ associative array called\n`\u003cname\u003e` instead.  However, as Bash does not natively support nested arrays,\nthey are faked for repeatable arguments with the following access syntax:\n\n\n```\n    ${args[ARG,#]} # the number of arguments to ARG\n    ${args[ARG,0]} # the first argument to ARG\n    ${args[ARG,1]} # the second argument to ARG, etc.\n```\n\nAssociative mode don't skip double-dash `--` it will be part of the keys\nas boolean value present or not.\n\n### How arguments are associated to variables\n\nWhat ever output mode has been selected.\n\nThe arguments are stored as follows:\n\n* Non-repeatable, valueless arguments: `true` if found, `false` if not.\n  This include double-dash `--` which must be specified as docopt syntax.\n* Repeatable valueless arguments: the count of their instances in `\u003cargv\u003e`\n* Non-repeatable arguments with values: the value as a string if found,\n  the empty string if not\n* Repeatable arguments with values: a Bash array of the parsed values\n\nUnless the `--no-help` option is given, `docopts` handles the `--help`\nand `--version` options and their possible aliases specially,\ngenerating code for printing the relevant message to standard output and\nterminating successfully if either option is encountered when parsing `\u003cargv\u003e`.\n\nNote however that this also requires listing the relevant option in\n`\u003cmsg\u003e` and, in `--version`'s case, invoking `docopts` with the `--version`\noption.\n\nIf `\u003cargv\u003e` does not match any usage pattern in `\u003cmsg\u003e`, `docopts` will generate\ncode for exiting the program with status 64 [`EX_USAGE` in `sysexits(3)`](http://man.cx/sysexits(3))\nand printing a diagnostic error message.\n\nNote that due to the above, `docopts` can't be used to parse shell function\narguments: [`exit(1)`](http://man.cx/exit(1)) quits the entire interpreter,\nnot just the current function.\n\n## OPTIONS\n\nThis is the verbatim output of the `--help`:\n\n[make README.md]: # (./docopts --help | sed -n '/^Options/,$ p')\n\n```\nOptions:\n  -h \u003cmsg\u003e, --help=\u003cmsg\u003e        The help message in docopt format.\n                                Without argument outputs this help.\n                                If - is given, read the help message from\n                                standard input.\n                                If no argument is given, print docopts's own\n                                help message and quit.\n  -V \u003cmsg\u003e, --version=\u003cmsg\u003e     A version message.\n                                If - is given, read the version message from\n                                standard input.  If the help message is also\n                                read from standard input, it is read first.\n                                If no argument is given, print docopts's own\n                                version message and quit.\n  -s \u003cstr\u003e, --separator=\u003cstr\u003e   The string to use to separate the help message\n                                from the version message when both are given\n                                via standard input. [default: ----]\n  -O, --options-first           Disallow interspersing options and positional\n                                arguments: all arguments starting from the\n                                first one that does not begin with a dash will\n                                be treated as positional arguments.\n  -H, --no-help                 Don't handle --help and --version specially.\n  -A \u003cname\u003e                     Export the arguments as a Bash 4+ associative\n                                array called \u003cname\u003e.\n  -G \u003cprefix\u003e                   Don't use associative array but output\n                                Bash 3.2 compatible GLOBAL variables assignment:\n                                  \u003cprefix\u003e_{mangled_args}={parsed_value}\n                                Can be used with numeric incompatible options\n                                as well.  See also: --no-mangle\n  --no-mangle                   Output parsed option not suitable for bash eval.\n                                Full option names are kept. Rvalue is still\n                                shellquoted. Extra parsing is required.\n  --no-declare                  Don't output 'declare -A \u003cname\u003e', used only\n                                with -A argument.\n  --debug                       Output extra parsing information for debugging.\n                                Output cannot be used in bash eval.\n```\n\n## COMPATIBILITY\n\nBash 4+ and higher is the main target.\n\nIn order to use `docopts` with Bash 3.2 (for macOS and old GNU/Linux versions) by avoiding bash \u003e4.x associative arrays,\nyou can:\n\n* don't use the `-A` option\n* use GLOBAL generated mangled variables\n* use `-G` `\u003cprefix\u003e` option to generate GLOBAL with `prefix_`\n* use `-G` switch with `source docopts.sh --auto -G` (see [example](examples/legacy_bash/sshdiff_with_docopts.sh))\n\nThe [`docopts.sh`](docopts.sh) helper allows the use of `set -u`, which\n[gives an error](https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html#The-Set-Builtin)\non undefined variables in your scripts.\n\n[Unofficial strict mode](http://redsymbol.net/articles/unofficial-bash-strict-mode/) for bash\nshould also work with `docopts.sh`, please report any [issue](https://github.com/docopt/docopts/issues) with examples.\n\n## `docopts.sh` helper\n\nThe helper has its own documentation here [docs/README.md](docs/README.md).\n\n## EXAMPLES\n\nFind more examples in [examples/ folder](examples/). Please report any\nnon working example by creating an [issue](https://github.com/docopt/docopts/issues) with examples.\n\nThe following example reads the help and version messages from standard input (`docopts` found in `$PATH`):\n\n[make README.md]: # (include examples/legacy_bash/rock_hello_world.sh)\n\n[source examples/legacy_bash/rock_hello_world.sh](examples/legacy_bash/rock_hello_world.sh)\n\n```bash\n#!/usr/bin/env bash\n# Example from README.md\n\nPATH=$PATH:../..\neval \"$(docopts -V - -h - : \"$@\" \u003c\u003cEOF\nUsage: rock [options] \u003cargv\u003e...\n\nOptions:\n      --verbose  Generate verbose messages.\n      --help     Show help options.\n      --version  Print program version.\n----\nrock 0.1.0\nCopyright (C) 200X Thomas Light\nLicense RIT (Robot Institute of Technology)\nThis is free software: you are free to change and redistribute it.\nThere is NO WARRANTY, to the extent permitted by law.\nEOF\n)\"\n\nif $verbose ; then\n    echo \"Hello, world!\"\nfi\n```\n\nThe following example, parses the help and version messages from script comments and pass them as\ncommand line arguments:\n\n[make README.md]: # (include examples/legacy_bash/rock_hello_world_with_grep.sh)\n\n[source examples/legacy_bash/rock_hello_world_with_grep.sh](examples/legacy_bash/rock_hello_world_with_grep.sh)\n\n```bash\n#!/usr/bin/env bash\n# Example from README.md\nPATH=$PATH:../..\n\n#? rock 0.1.0\n#? Copyright (C) 200X Thomas Light\n#? License RIT (Robot Institute of Technology)\n#? This is free software: you are free to change and redistribute it.\n#? There is NO WARRANTY, to the extent permitted by law.\n\n##? Usage: rock [options] \u003cargv\u003e...\n##?\n##? Options:\n##?       --help     Show help options.\n##?       --version  Print program version.\n\nhelp=$(grep \"^##?\" \"$0\" | cut -c 5-)\nversion=$(grep \"^#?\"  \"$0\" | cut -c 4-)\neval \"$(docopts -h \"$help\" -V \"$version\" : \"$@\")\"\n\nfor arg in \"${argv[@]}\"; do\n    echo \"$arg\"\ndone\n```\n\nThe next example shows how using the Bash 4+ associative array with `-A`:\n\n```bash\nhelp=\"\nUsage: example [--long-option-with-argument=value] \u003cargument-with-multiple-values\u003e...\n\"\neval \"$(docopts -A args -h \"$help\" : \"$@\")\"\n\nif ${args[subcommand]} ; then\n    echo \"subcommand was given\"\nfi\n\nif [ -n \"${args[--long-option-with-argument]}\" ] ; then\n    echo \"${args[--long-option-with-argument]}\"\nelse\n    echo \"--long-option-with-argument was not given\"\nfi\n\ni=0\nwhile [[ $i -lt ${args[\u003cargument-with-multiple-values\u003e,#]} ]] ; do\n    echo \"$i: ${args[\u003cargument-with-multiple-values\u003e,$i]}\"\n    i=$[$i+1]\ndone\n```\n\n## Docopts History\n\n`docopts` was first developed by Lari Rasku \u003crasku@lavabit.com\u003e and was written in Python based on the\n[docopt Python parser](https://github.com/docopt/docopt).\n\nThe current version is written in [go](https://golang.org/) and is almost 100% compatible with previous Python-based `docopts`.\nSee section `Global mode` for incompatibly details and provided work around.\n\nPlease report any non working code with [issue](https://github.com/docopt/docopts/issues) and examples.\n\n## Roadmap: A new shell API is proposed\n\nStarting at release: 0.7.0 a new lib API based on JSON will be introduced:\n\nSee and contribute on the [docopts Wiki](https://github.com/docopt/docopts/wiki).\n\n## Install\n\nYou only have to drop the binary, and optionally also the `docopts.sh` lib helper, in a directory on your PATH.\nThe binary is standalone and statically linked, so it runs everywhere.\n\nSee build section.\n\nWith root privileges you could do:\n\n```\ncp docopts docopts.sh /usr/local/bin\n```\n\n### Pre-built binaries\n\nPre-built Go binaries for some OS (32 and 64 bits) are attached to [releases](https://github.com/docopt/docopts/releases).\n\nWe provide a download helper:\n\n```bash\ngit clone https://github.com/docopt/docopts.git\ncd docopts\n./get_docopts.sh\n```\n\nYou should get a renamed `docopts` in the current folder.\nPut it in your `PATH`:\n\n```bash\nsudo cp docopts docopts.sh /usr/local/bin\n```\n\nThe cloned repository is no more used at this stage, but still contains a lot of bash examples.\n\nLearn more about [pre-built binaries](docs/pre_built_binaries.md).\n\n## Compiling\n\nWe encourage you to build your own binary, which is easy once\nyou have Go installed. Or find a local golang developer that you\ntrust and ask her, in exchange for a beer or two, if she could build it for you. ;)\n\nRequires a [Go workspace](https://golang.org/doc/code.html#Organization).\n\nlocal build:\n(also done with our Makefile default target: `make`)\n\n```\ngo get github.com/docopt/docopt-go\ngo get github.com/docopt/docopts\ncd src/github.com/docopt/docopts\ngo build docopts.go\n```\n\ncross compile for 32 bit:\n\n```\nenv GOOS=linux GOARCH=386 go build docopts.go\n```\n\nor via Makefile:\n\n```\ncd src/github.com/docopt/docopts\nmake all\nmake test\n```\n\nTested builds are built on:\n\n[make README.md]: # (go version)\n\n```\ngo version go1.17.1 linux/amd64\n```\n\n## Features\n\nWarning: may be not up-to-date feature list.\n\nThe [`docopts.sh`](docopts.sh) helper is an extra bash library that you can source in your shell script.\nThis library provides some bash helpers and is not required in order to use `docopts`. See [docopts.sh\ndocumentation](docs/README.md).\n\n`docopts` doesn't need a python interpreter anymore, so it works on any legacy system too.\n\nAs of 2021-09-15\n\n* `docopts` is able to reproduce almost 100% of the python version.\n* unit tests for Go are provided, so hack as you wish.\n* 100% of `language_agnostic_tester.py` tests pass (GNU/Linux 64bits).\n* `bats-core` unittests and functional testing are provided too.\n\n## Developers\n\nRead the [doc for developer](docs/developer.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocopt%2Fdocopts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdocopt%2Fdocopts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocopt%2Fdocopts/lists"}