Merge branch 'master' into new_quoted_completion

4 files changed, 44 insertions, 11 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0082a067..82d978f5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,4 +1,4 @@
-## 0.8.2 (March TBD, 2018)
+## 0.8.2 (March 21, 2018)
 
 * Bug Fixes
     * Fixed a bug in tab-completion of command names within sub-menus
@@ -13,6 +13,7 @@
     * Added the ability to load an initialization script at startup
         * See [alias_startup.py](https://github.com/python-cmd2/cmd2/blob/master/examples/alias_startup.py) for an example
     * Added a default SIGINT handler which terminates any open pipe subprocesses and re-raises a KeyboardInterrupt
+    * For macOS, will load the ``gnureadline`` module if available and ``readline`` if not
     
 ## 0.8.1 (March 9, 2018)
 
diff --git a/cmd2.py b/cmd2.py
index 13f22273..26d877ba 100755
--- a/cmd2.py
+++ b/cmd2.py
@@ -113,13 +113,17 @@ try:
 except ImportError:
     ipython_available = False
 
-# Try to import readline, but allow failure for convenience in Windows unit testing
-# Note: If this actually fails, you should install readline on Linux or Mac or pyreadline on Windows
+# Prefer statically linked gnureadline if available (for macOS compatibility due to issues with libedit)
 try:
-    # noinspection PyUnresolvedReferences
-    import readline
+    import gnureadline as readline
 except ImportError:
-    pass
+    # Try to import readline, but allow failure for convenience in Windows unit testing
+    # Note: If this actually fails, you should install readline on Linux or Mac or pyreadline on Windows
+    try:
+        # noinspection PyUnresolvedReferences
+        import readline
+    except ImportError:
+        pass
 
 # Load the GNU readline lib so we can make changes to it
 readline_lib = None
diff --git a/docs/index.rst b/docs/index.rst
index 2f2a8dad..b034dafd 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -35,9 +35,10 @@ The basic use of ``cmd2`` is identical to that of cmd_.
 
    The tab-completion feature provided by cmd_ relies on underlying capability provided by GNU readline or an
    equivalent library.  Linux distros will almost always come with the required library installed.
-   For macOS, we recommend using the `Homebrew <https://brew.sh>`_ package manager to install the ``readline`` package;
-   alternatively for macOS the ``conda`` package manager that comes with the Anaconda Python distro can be used to
-   install ``readline`` (preferably from conda-forge).
+   For macOS, we recommend using the `gnureadline <https://pypi.python.org/pypi/gnureadline>`_ Python module which includes
+   a statically linked version of GNU readline.  Alternatively on macOS the ``conda`` package manager that comes
+   with the Anaconda Python distro can be used to install ``readline`` (preferably from conda-forge) or the
+   `Homebrew <https://brew.sh>`_ package manager can be used to to install the ``readline`` package.
    For Windows, we recommend installing the `pyreadline <https://pypi.python.org/pypi/pyreadline>`_ Python module.
 
 Resources
diff --git a/docs/install.rst b/docs/install.rst
index 2c247a3e..b6ee0aff 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -1,5 +1,4 @@
 
-=========================
 Installation Instructions
 =========================
 
@@ -138,5 +137,33 @@ Extra requirement for Python 2.7 only
 If you want to be able to pipe the output of commands to a shell command on Python 2.7, then you will need one
 additional package installed:
 
-  * subprocess32
+  * subprocess32gNU
+
+Extra requirement for macOS
+===========================
+macOS comes with the `libedit <http://thrysoee.dk/editline/>`_ library which is similar, but not identical, to GNU Readline.
+Tab-completion for ``cmd2`` applications is only tested against GNU Readline.
+
+There are several ways GNU Readline can be installed within a Python environment on a Mac, detailed in the following subsections.
+
+gnureadline Python module
+-------------------------
+Install the `gnureadline <https://pypi.python.org/pypi/gnureadline>`_ Python module which is statically linked against a specific compatible version of GNU Readline::
+
+  pip install -U gnureadline
+
+readline via conda
+------------------
+Install the **readline** package using the ``conda`` package manager included with the Anaconda Python distribution::
+
+  conda install readline
+
+readline via brew
+-----------------
+Install the **readline** package using the Homebrew package manager (compiles from source)::
+
+  brew install openssl
+  brew install pyenv
+  brew install readline
 
+Then use pyenv to compile Python and link against the installed readline