From 6fc6bee0c1bcadd34dc409df890db8a59d339ff6 Mon Sep 17 00:00:00 2001
From: Eric Lin <anselor@gmail.com>
Date: Tue, 26 Jun 2018 17:46:24 -0400
Subject: Example added demonstrating bash completion bridging argcomplete with
 AutoCompleter

---
 examples/bash_completion.py | 81 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)
 create mode 100755 examples/bash_completion.py

(limited to 'examples/bash_completion.py')

diff --git a/examples/bash_completion.py b/examples/bash_completion.py
new file mode 100755
index 00000000..666d3a0c
--- /dev/null
+++ b/examples/bash_completion.py
@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+# coding=utf-8
+# PYTHON_ARGCOMPLETE_OK - This is required at the beginning of the file to enable argcomplete support
+"""A simple example demonstrating integration with argcomplete"""
+import argparse
+
+optional_strs = ['Apple', 'Banana', 'Cranberry', 'Durian', 'Elderberry']
+
+bash_parser = argparse.ArgumentParser(prog='base')
+
+bash_parser.add_argument('option', choices=['load', 'export', 'reload'])
+
+bash_parser.add_argument('-u', '--user', help='User name')
+bash_parser.add_argument('-p', '--passwd', help='Password')
+
+input_file = bash_parser.add_argument('-f', '--file', type=str, help='Input File')
+
+if __name__ == '__main__':
+    from cmd2.argcomplete_bridge import bash_complete
+    # bash_complete flags this argument telling AutoCompleter to yield to bash to perform
+    # tab completion of a file path
+    bash_complete(input_file)
+
+flag_opt = bash_parser.add_argument('-o', '--optional', help='Optional flag with choices')
+setattr(flag_opt, 'arg_choices', optional_strs)
+
+# Handle bash completion if it's installed
+# This early check allows the script to bail out early to provide tab-completion results
+# to the argcomplete library. Putting this at the end of the file would cause the full application
+# to load fulfill every tab-completion request coming from bash.  This can cause a notable delay
+# on the bash prompt.
+try:
+    # only move forward if we can import CompletionFinder and AutoCompleter
+    from cmd2.argcomplete_bridge import CompletionFinder
+    from cmd2.argparse_completer import AutoCompleter
+    import sys
+    if __name__ == '__main__':
+        completer = CompletionFinder()
+
+        # completer will return results to argcomplete and exit the script
+        completer(bash_parser, AutoCompleter(bash_parser))
+except ImportError:
+    pass
+
+# Intentionally below the bash completion code to reduce tab completion lag
+import cmd2
+
+
+class DummyApp(cmd2.Cmd):
+    """
+    Dummy cmd2 app
+    """
+
+    def __init__(self):
+        super().__init__()
+
+
+if __name__ == '__main__':
+    args = bash_parser.parse_args()
+
+    # demonstrates some handling of the command line parameters
+
+    if args.user is None:
+        user = input('Username: ')
+    else:
+        user = args.user
+
+    if args.passwd is None:
+        import getpass
+        password = getpass.getpass()
+    else:
+        password = args.passwd
+
+    if args.file is not None:
+        print('Loading file: {}'.format(args.file))
+
+    # Clear the argumentns so cmd2 doesn't try to parse them
+    sys.argv = sys.argv[:1]
+
+    app = DummyApp()
+    app.cmdloop()
-- 
cgit v1.2.1


From 21ad2e38dde39e92c4583ab7fa2d31f8721a79d6 Mon Sep 17 00:00:00 2001
From: Todd Leonhardt <todd.leonhardt@gmail.com>
Date: Tue, 26 Jun 2018 20:59:32 -0700
Subject: Just added some comments at the top of the example to try to give
 some context

---
 examples/bash_completion.py | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

(limited to 'examples/bash_completion.py')

diff --git a/examples/bash_completion.py b/examples/bash_completion.py
index 666d3a0c..6a5a2a89 100755
--- a/examples/bash_completion.py
+++ b/examples/bash_completion.py
@@ -1,7 +1,24 @@
 #!/usr/bin/env python3
 # coding=utf-8
 # PYTHON_ARGCOMPLETE_OK - This is required at the beginning of the file to enable argcomplete support
-"""A simple example demonstrating integration with argcomplete"""
+"""A simple example demonstrating integration with argcomplete.
+
+This example demonstrates how to achieve automatic auto-completion of argparse arguments for a command-line utility
+(CLU) in the Bash shell.
+
+Realistically it will probably only work on Linux and then only in a Bash shell.  With some effort you can probably get
+it to work on macOS or Windows Subsystem for Linux (WSL); but then again, specifically within a Bash shell.  This
+automatic Bash completion integration with the argcomplete module is included within cmd2 in order to assist developers
+with providing a the best possible out-of-the-box experience with their cmd2 applications, which in many cases will
+accept argparse arguments on the command-line when executed.  But from an architectural point of view, the
+"argcomplete_bridge" functionality within cmd2 doesn't really depend on the rest of cmd2 and could be used in your own
+CLU which doesn't use cmd2.
+
+WARNING:  For this example to work correctly you need the argcomplete module installed and activated:
+    pip install argcomplete
+    activate-global-python-argcomplete
+Please see https://github.com/kislyuk/argcomplete for more information on argcomplete.
+"""
 import argparse
 
 optional_strs = ['Apple', 'Banana', 'Cranberry', 'Durian', 'Elderberry']
-- 
cgit v1.2.1