Code style fixes and minor Readme tweaks

README.rst

@@ -221,8 +221,8 @@ The file's contents should then be sourced in e.g. ``~/.bashrc``.
 
 Debugging
 ---------
-Set the ``ARC_DEBUG`` variable in your shell to enable verbose debugging every time argcomplete runs. Alternatively, you
-can bypass the bash completion shellcode altogether and interact with the Python code directly with something like
+Set the ``ARC_DEBUG`` variable in your shell to enable verbose debug output every time argcomplete runs. Alternatively,
+you can bypass the bash completion shellcode altogether, and interact with the Python code directly with something like
 this::
 
     PROGNAME=./{YOUR_PY_SCRIPT} TEST_ARGS='some_arguments with autocompl' _ARC_DEBUG=1 COMP_LINE="$PROGNAME $TEST_ARGS" COMP_POINT=31 _ARGCOMPLETE=1 $PROGNAME 8>&1 9>>~/autocomplete_debug.log

argcomplete/__init__.py

@@ -101,11 +101,11 @@ def split_word(word):
             else:
                 raise ArgcompleteException("unexpected state? TODO")
 
-def default_validator(c, my_word):
-    return c.startswith(my_word)
+def default_validator(completion, prefix):
+    return completion.startswith(prefix)
 
 def autocomplete(argument_parser, always_complete_options=True, exit_method=os._exit, output_stream=None,
-        exclude=None, validator=default_validator):
+                 exclude=None, validator=None):
     '''
     :param argument_parser: The argument parser to autocomplete on
     :type argument_parser: :class:`argparse.ArgumentParser`
@@ -115,6 +115,8 @@ def autocomplete(argument_parser, always_complete_options=True, exit_method=os._
     :type exit_method: method
     :param exclude: List of strings representing options to be omitted from autocompletion
     :type exclude: iterable
+    :param validator: Function to filter all completions through before returning (return value is evaluated as a boolean)
+    :type validator: callable
 
     Produces tab completions for ``argument_parser``. See module docs for more info.
 
@@ -140,6 +142,9 @@ def autocomplete(argument_parser, always_complete_options=True, exit_method=os._
             debug("Unable to open fd 8 for writing, quitting")
             exit_method(1)
 
+    if validator is None:
+        validator = default_validator
+
     # print >>debug_stream, ""
     # for v in 'COMP_CWORD', 'COMP_LINE', 'COMP_POINT', 'COMP_TYPE', 'COMP_KEY', '_ARGCOMPLETE_COMP_WORDBREAKS', 'COMP_WORDS':
     #     print >>debug_stream, v, os.environ[v]