This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
Project Description

WARNING: The upcoming 0.7.0 release of docopts will feature a completely different user interface. Prepare for script breakage.

docopts

shell interface for docopt, the CLI description language

Author:Lari Rasku
Date:2013-02-07
Copyright:MIT
Version:0.6.1+fix
Manual section:1

SYNOPSIS

docopts [options] -h msg : [argv…]

DESCRIPTION

docopts parses the command line argument vector argv according to the docopt string msg and echoes the results to standard output as a snippet of Bash source code. Passing this snippet as an argument to eval(1) is sufficient for handling the CLI needs of most scripts.

If argv matches one of the usage patterns defined in msg, docopts generates code for storing the parsed arguments as Bash variables. As most command line argument names are not valid Bash identifiers, some name mangling will take place:

  • <Angle_Brackets>: Angle_Brackets
  • UPPER-CASE: UPPER_CASE
  • --Long-Option: Long_Option
  • -S: S

If one of the argument names cannot be mangled into a valid Bash identifier, or two argument names map to the same variable name, docopt will exit with an error, and you should really rethink your CLI. The -- and - commands will not be stored.

Alternatively, docopts can be invoked with the -A <name> option, which stores the parsed arguments as fields of a Bash 4 associative array called <name> instead. However, as Bash does not natively support nested arrays, they are faked for repeatable arguments with the following access syntax:

${args[ARG,#]} # the number of arguments to ARG
${args[ARG,0]} # the first argument to ARG
${args[ARG,1]} # the second argument to ARG, etc.

The arguments are stored as follows:

  • Non-repeatable, valueless arguments: true if found, false if not
  • Repeatable valueless arguments: the count of their instances in argv
  • Non-repeatable arguments with values: the value as a string if found, the empty string if not
  • Repeatable arguments with values: a Bash array of the parsed values

Unless the --no-help option is given, docopts handles the --help and --version options and their possible aliases specially, generating code for printing the relevant message to standard output and terminating successfully if either option is encountered when parsing argv. Note however that this also requires listing the relevant option in msg and, in --version’s case, invoking docopts with the --version option.

If argv does not match any usage pattern in msg, docopts will generate code for exiting the program with status 64 (EX_USAGE in sysexits(3)) and printing a diagnostic error message.

OPTIONS

-h <msg>, --help=<msg>
 The help message in docopt format. If - is given, read the help message from standard input. If no argument is given, print docopts’s own help message and quit.
-V <msg>, --version=<msg>
 A version message. If - is given, read the version message from standard input. If the help message is also read from standard input, read it first. If no argument is given, print docopts’s own version message and quit.
-O, --options-first
 Disallow interspersing options and positional arguments: all arguments starting from the first one that does not begin with a dash will be treated as positional arguments.
-H, --no-help Don’t handle –help and –version specially.
-A <name> Export the arguments as a Bash 4.x associative array called <name>.
-s <str>, --separator=<str>
 The string to use to separate the help message from the version message when both are given via standard input. [default: —-]

EXAMPLES

Read the help and version messages from standard input:

eval "$(docopts -V - -h - : "$@" <<EOF
Usage: rock [options] <argv>...

      --verbose  Generate verbose messages.
      --help     Show help options.
      --version  Print program version.
----
rock 0.1.0
Copyright (C) 200X Thomas Light
License RIT (Robot Institute of Technology)
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
EOF
)"

if $verbose ; then
    echo "Hello, world!"
fi

Parse the help and version messages from script comments and pass them as command line arguments:

#? rock 0.1.0
#? Copyright (C) 200X Thomas Light
#? License RIT (Robot Institute of Technology)
#? This is free software: you are free to change and redistribute it.
#? There is NO WARRANTY, to the extent permitted by law.

##? Usage: rock [options] <argv>...
##?
##?       --help     Show help options.
##?       --version  Print program version.

help=$(grep "^##?" "$0" | cut -c 5-)
version=$(grep "^#?"  "$0" | cut -c 4-)
eval "$(docopts -h "$help" -V "$version" : "$@")"

for arg in "${argv[@]}"; do
    echo "$arg"
done

Using the associative array:

eval "$(docopts -A args -h "$help" : "$@")"

if ${args[subcommand]} ; then
    echo "subcommand was given"
fi

if [ -n "${args[--long-option-with-argument]}" ] ; then
    echo "${args[--long-option-with-argument]}"
else
    echo "--long-option-with-argument was not given"
fi

i=0
while [[ $i -lt ${args[<argument-with-multiple-values>,#]} ]] ; do
    echo "${args[<argument-with-multiple-values>,$i]}"
    i=$[$i+1]
done

VERSIONING

The docopts version number always matches that of the docopt Python reference implementation version against which it was built. As docopt follows semantic versioning, docopts should work with any docopt release it shares the major version number with; however, as both docopts and docopt are in major version number 0 at the moment of writing this, docopts can only be relied to work with an installation of docopt with the exact same version number.

Release History

Release History

0.6.1-fix2

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.6.1-fix

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.6.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.6.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.5.0-fix

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.5.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
docopts-0.6.1-fix2.tar.gz (6.0 kB) Copy SHA256 Checksum SHA256 Source May 14, 2013

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS HPE HPE Development Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting