Metadata-Version: 1.1
Name: docopts
Version: 0.5.0
Summary: Shell interface for docopt, the command-line interface description language.
Home-page: https://github.com/docopt/docopts
Author: Lari Rasku
Author-email: raskug@lavabit.com
License: MIT
Description: ================================================================================
         docopts
        ================================================================================
        --------------------------------------------------------------------------------
         shell interface for docopt, the CLI description language
        --------------------------------------------------------------------------------
        :Author:        `Lari Rasku <rasku@lavabit.com>`_
        :Date:           2012-10-09
        :Copyright:     `MIT <http://opensource.org/licenses/MIT>`_
        :Version:        0.5.0
        :Manual section: 1
        
        SYNOPSIS
        ================================================================================
        ``docopts`` [*options*] *doc* *version* [-- *argv*...]
        
        DESCRIPTION
        ================================================================================
        ``docopts`` parses the command line argument vector *argv* according to the
        `docopt <http://docopt.org>`_ string *doc* and echoes the results to standard
        output as a snippet of Bash source code.  Passing this snippet as an argument to
        `eval(1) <http://man.cx/eval(1)>`_ is sufficient for handling the CLI needs of
        most scripts.
        
        If *argv* matches one of the usage patterns defined in *doc*, ``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(1) <http://man.cx/true(1)>`_
          if found, `false(1) <http://man.cx/false(1)>`_ 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
        *doc*, and in ``--version``'s case, invoking ``docopts`` with a non-empty
        *version* string.
        
        If *argv* does not match any usage pattern in *doc*, ``docopts`` will generate
        code for exiting the program with status 64 (``EX_USAGE`` in
        `sysexits(3) <http://man.cx/sysexits(3)>`_) and printing a diagnostic error
        message.
        
        ARGUMENTS
        ================================================================================
        :doc:                           The help message in docopt format.  If ``-`` is
                                        given, read the help message from standard
                                        input.
        :version:                       A version message.  If an empty argument is
                                        given via ``''``, no version message is used.
                                        If ``-`` is given, the version message is read
                                        from standard input.  The version message is
                                        read after the help message if both are given
                                        via standard input.
        
        OPTIONS
        ================================================================================
          -A <name>                     Export the arguments as a Bash 4.x associative
                                        array called *name*.
          -s <sep>, --separator=<sep>   The string to use to separate *doc* from
                                        *version* when both are given via standard
                                        input [default: ``----``]
          -H, --no-help                 Don't handle ``--help`` and ``--version``
                                        specially.
          -d, --debug                   Export the arguments as JSON.  The docopt
                                        language agnostic test suite can be run for
                                        docopts by passing ``docopts -d - '' --`` as
                                        its argument.
          -h, --help                    Show help options.
          -V, --version                 Print program version.
        
        EXAMPLES
        ================================================================================
        Read *doc* and *version* from standard input::
        
            eval "$(docopts - - -- "$@" <<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 *doc* and *version* 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 "$help" "$version" -- "$@")"
            
            for arg in "${argv[@]}"; do
                # do something
            done
        
        Using the associative array::
        
            eval "$(docopts -A args "$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
        
        INSTALLATION
        ================================================================================
        To install ``docopts`` for every user, extract the release archive and execute
        the following command in it::
        
            python setup.py install
        
        To install ``docopts`` just for you, use this instead::
        
            python setup.py install --user
        
        Alternatively, you can simply copy the ``docopts`` file to anywhere on your
        ``PATH``; it is self-contained.
        
        VERSIONING
        ================================================================================
        The ``docopts`` version number always matches that of the
        `docopt Python reference implementation <https://github.com/docopt/docopt>`_
        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 (2012-10-09), ``docopts`` can only be
        relied to work with an installation of ``docopt`` with the exact same version
        number.
        
Keywords: shell bash docopt command-line
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2.5
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.1
Classifier: Programming Language :: Python :: 3.2
Classifier: Topic :: Software Development :: User Interfaces
