Overhauling tab completion examples

Author: kmvanbrunt

README.md

@@ -175,14 +175,14 @@ Instructions for implementing each feature follow.
         - See the [paged_output.py](https://github.com/python-cmd2/cmd2/blob/master/examples/paged_output.py) example for a simple use case
         - See the [python_scripting.py](https://github.com/python-cmd2/cmd2/blob/master/examples/python_scripting.py) example for a more full-featured use case
     - `flag_based_complete` helper method for tab completion based on a particular flag preceding the token being completed
-        - See the [tab_completion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/tab_completion.py) example for a demonstration of how to use this feature
+        - See the [basic_completion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/basic_completion.py) example for a demonstration of how to use this feature
     - `index_based_complete` helper method for tab completion based on a fixed position in the input string
-        - See the [tab_completion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/tab_completion.py) example for a demonstration of how to use this feature
+        - See the [basic_completion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/basic_completion.py) example for a demonstration of how to use this feature
     - `basic_complete` helper method for tab completion against a list
     - `delimiter_complete` helper method for tab completion against a list but each match is split on a delimiter 
-        - See the [tab_autocompletion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/tab_autocompletion.py) example for a demonstration of how to use this feature
-    - `cmd2` in combination with `argparse` also provide several advanced capabilities for automatic tab-completion
-            - See the [tab_autocompletion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/tab_autocompletion.py) example for more info
+        - See the [basic_completion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/basic_completion.py) example for a demonstration of how to use this feature
+    - `cmd2` in combination with `argparse` also provide several advanced capabilities for automatic tab completion
+        - See the [argparse_completion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/argparse_completion.py) example for more info
 
 - Multi-line commands
 

docs/features/argument_processing.rst

@@ -328,11 +328,10 @@ You may add multiple layers of subcommands for your command. ``cmd2`` will
 automatically traverse and tab-complete subcommands for all commands using
 argparse.
 
-See the subcommands_ and tab_autocompletion_ example to learn more about how to
+See the subcommands_ example to learn more about how to
 use subcommands in your ``cmd2`` application.
 
 .. _subcommands: https://github.com/python-cmd2/cmd2/blob/master/examples/subcommands.py
-.. _tab_autocompletion: https://github.com/python-cmd2/cmd2/blob/master/examples/tab_autocompletion.py
 
 
 Argparse Extensions

docs/features/completion.rst

@@ -17,7 +17,7 @@ implementing the ``do_foo`` method.  To enable path completion for the ``foo``
 command, then add a line of code similar to the following to your class which
 inherits from ``cmd2.Cmd``::
 
-    complete_foo = self.path_complete
+    complete_foo = cmd2.Cmd.path_complete
 
 This will effectively define the ``complete_foo`` readline completer method in
 your class and make it utilize the same path completion logic as the built-in
@@ -47,9 +47,9 @@ parameters to ``argparse.ArgumentParser.add_argument()``
 - ``completer_function`` / ``completer_method``
 
 See the arg_decorators_ or colors_ example for a demonstration of how to
-use the ``choices`` parameter. See the tab_autocompletion_ example for a
+use the ``choices`` parameter. See the argparse_completion_ example for a
 demonstration of how to use the ``choices_function`` and ``choices_method``
-parameters. See the arg_decorators_ or tab_autocompletion_ example for a
+parameters. See the arg_decorators_ or argparse_completion_ example for a
 demonstration of how to use the ``completer_method`` parameter.
 
 When tab-completing flags and/or argument values for a ``cmd2`` command using
@@ -60,7 +60,7 @@ displayed to help the user.
 
 .. _arg_decorators: https://github.com/python-cmd2/cmd2/blob/master/examples/arg_decorators.py
 .. _colors: https://github.com/python-cmd2/cmd2/blob/master/examples/colors.py
-.. _tab_autocompletion: https://github.com/python-cmd2/cmd2/blob/master/examples/tab_autocompletion.py
+.. _argparse_completion: https://github.com/python-cmd2/cmd2/blob/master/examples/argparse_completion.py
 
 
 CompletionItem For Providing Extra Context
@@ -76,5 +76,5 @@ or ``completion_method``.
 .. autoclass:: cmd2.argparse_custom.CompletionItem
     :members:
 
-See the tab_autocompletion_ example or the implementation of the built-in
+See the argparse_completion_ example or the implementation of the built-in
 **set** command for demonstration of how this is used.

examples/tab_completion.py examples/basic_completion.pyexamples/tab_completion.py renamed to examples/basic_completion.py

@@ -1,24 +1,39 @@
 #!/usr/bin/env python
 # coding=utf-8
 """
-A simple example demonstrating how to use flag and index based tab-completion functions
-For argparse-based tab completion, see tab_autocompletion.py
+A simple example demonstrating how to enable tab completion by assigning a completer function to do_* commands.
+This also demonstrates capabilities of the following completer methods included with cmd2:
+- flag_based_complete
+- index_based_complete
+- delimiter_completer
+
+For an example enabling tab completion with argparse, see argparse_completion.py
 """
 import argparse
+import functools
 
 import cmd2
 
-# List of strings used with flag and index based completion functions
+# List of strings used with completion functions
 food_item_strs = ['Pizza', 'Ham', 'Ham Sandwich', 'Potato']
 sport_item_strs = ['Bat', 'Basket', 'Basketball', 'Football', 'Space Ball']
 
+file_strs = \
+    [
+        '/home/user/file.db',
+        '/home/user/file space.db',
+        '/home/user/another.db',
+        '/home/other user/maps.db',
+        '/home/other user/tests.db'
+    ]
+
 
 class TabCompleteExample(cmd2.Cmd):
     """ Example cmd2 application where we a base command which has a couple subcommands."""
-
     def __init__(self):
         super().__init__()
 
+    # The add_item command uses flag_based_complete
     add_item_parser = argparse.ArgumentParser()
     add_item_group = add_item_parser.add_mutually_exclusive_group()
     add_item_group.add_argument('-f', '--food', help='Adds food item')
@@ -58,6 +73,7 @@ def complete_add_item(self, text, line, begidx, endidx):
 
         return self.flag_based_complete(text, line, begidx, endidx, flag_dict=flag_dict)
 
+    # The list_item command uses index_based_complete
     @cmd2.with_argument_list
     def do_list_item(self, args):
         """List item command help"""
@@ -74,6 +90,14 @@ def complete_list_item(self, text, line, begidx, endidx):
 
         return self.index_based_complete(text, line, begidx, endidx, index_dict=index_dict)
 
+    # The file_list command uses delimiter_complete
+    def do_file_list(self, statement: cmd2.Statement):
+        """List files entered on command line"""
+        self.poutput("You selected: {}".format(statement.args))
+
+    # Use a partialmethod to set arguments to delimiter_complete
+    complete_file_list = functools.partialmethod(cmd2.Cmd.delimiter_complete, match_against=file_strs, delimiter='/')
+
 
 if __name__ == '__main__':
     import sys

examples/python_scripting.py

@@ -87,6 +87,7 @@ def do_cd(self, arglist):
 
     # Enable tab completion for cd command
     def complete_cd(self, text, line, begidx, endidx):
+        # Tab complete only directories
         return self.path_complete(text, line, begidx, endidx, path_filter=os.path.isdir)
 
     dir_parser = argparse.ArgumentParser()