[Feature request] Autocomplete

[con-f-use]

The thing that gets me about docopt is that there is nothing like argcomplete for argparse. I know one can use docopt_wordlist and docopt-wordlist.bash from docopt.rs but that is hard to set up and doesn't work in some cases. Another solution is infi.docopt_autocomplete that creates bash and zsh completion files. The drawback with that: the user has to update the completion files by hand, EVERY time, the options change in the original script. I think a command line interface goes hand in hand with auto-completion. So if you feel, you're being bored, a nice mechanism for auto-completing commands would be good that doesn't require installation beyond a simple pip install. (See Issue discussed in docopt repository for reference).

Desired result:

If I have and the desired feature "docpie auto-completion" installed:

# This is 'prog.py'
"""
Usage:
    prog.py --long-option --longer-option <file>...
"""
from docpie import docpie
args = docpie(__doc__ % locals()
print args

And prog.py is in the current working directory of my shell together with these other files: example1.txt, example2.txt, example3.txt

I want to be able to auto-complete in the shell like this:

shell> ./prog.py --lo[TAB]
--long-option     --longer-option
shell> ./prog.py --longer[TAB]
shell> ./prog.py --longer-option
shell> ./prog.py --longer-option ex[TAB]
example1.txt   example2.txt    example3.txt

Ideally the auto-completion is smart and uses existing built-in completions for things like files, hostnames, ip-adresses, kernel-versions and s.o. In Bash they can be listed with complete -p.

[TylerTemp]

Thanks for feedback.

I'm not so familiar with how the auto-complete works. Thanks for mention infi.docopt_completion, it should be a good example that I can get start with.

So far the infi.docopt_completion does not work on my Ubuntu and MacOSX. I'll try to figure it out and add this feature one day (for now I need to refactor the code first and a little bug fix, the code inside is not so clear and clean 😨 )

If you know any source that I can get more knowledge about this "tab-to-complete", please tell me too, thanks :D

[con-f-use]

I learned a bit here. Shells other than bash of course have a different way to get auto-completion. Bash has many pre-defined completions (see bash complete -p) so one could auto-detect argument names like '' or '' in usage strings and get the actual files or hostnames from pre-defined completion functions. E.g. on my system:

# Gives completitions of defined hostnames starting with 'con' 
confus@confusion:~$ compgen -A hostname con
confusion
conserve
convolve

Assume the script prog.py from above is, what you want to install auto-completion for using infi.docopt_completion. What I had to do to get infi.docopt_completion to work on Ubuntu 14.04 was simply:

 confus@confusion:~$ sudo apt-get install python-pip
 confus@confusion:~$ sudo pip install infi.docopt-completion
 confus@confusion:~$ chmod +x prog.py
 confus@confusion:~$ docopt-completion --manual-bash ./prog.py  # Generates the completion file in next line
 confus@confusion:~$ export PATH="$(pwd):PATH"                   # 'prog.py' must be callable without the './' in front
 confus@confusion:~$ source prog.py.sh                           # Use completion file only in open shell
 confus@confusion:~$ prog.py --lo[TAB][TAB]
 --long-option     --longer-option
 confus@confusion:~$ ./prog.py --lo[TAB][TAB]     # WILL NOT WORK because of "./"

To install completion for prog.py permanently for the current user, you can:

dir="$HOME/.bash_completion.d/" 
mkdir $dir 
cp prog.py.sh $dir

Or if you dare install the completion system-wide for every user:

sudo docopt-completion --manual-bash ./prog.py

In any case, the script prog.py must be executable and its location in $PATH.

[TylerTemp]

commit (I'm kind of signing to a wrong issue number 😭 )

First simple implement (only bash so far). Feel free to commit.