Improved documentation for how a user can modify comment grammar/style

Also:
- Added arg_print.py example to demonstrate this
- Bumped version to 0.7.8a
- Updated CHANGELOG

6 files changed, 53 insertions, 5 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 67029b56..7a8e8d1b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,11 @@
+## 0.7.8 (TBD, 2017)
+
+* Bug Fixes
+    * Fixed ``poutput()`` so it can print an integer zero and other **falsy** things
+* Enhancements
+    * Improved documentation for user-settable environment parameters
+    * Improved documentation for overriding the default supported comment styles
+
 ## 0.7.7 (August 25, 2017)
 
 * Bug Fixes
@@ -12,7 +20,7 @@
         * The prior behavior removed whitespace before making the comparison, now whitespace must match exactly
         * Prior version did not allow regexes with whitespace, new version allows any regex
     * Improved display for ``load`` command and input redirection when **echo** is ``True``
-    
+
 ## 0.7.6 (August 11, 2017)
 
 * Bug Fixes
diff --git a/cmd2.py b/cmd2.py
index 87fb3aad..32fdc431 100755
--- a/cmd2.py
+++ b/cmd2.py
@@ -98,7 +98,7 @@ if six.PY3:
 else:
     BROKEN_PIPE_ERROR = IOError
 
-__version__ = '0.7.7'
+__version__ = '0.7.8a'
 
 # Pyparsing enablePackrat() can greatly speed up parsing, but problems have been seen in Python 3 in the past
 pyparsing.ParserElement.enablePackrat()
diff --git a/docs/freefeatures.rst b/docs/freefeatures.rst
index efb74316..e3787720 100644
--- a/docs/freefeatures.rst
+++ b/docs/freefeatures.rst
@@ -36,7 +36,7 @@ before it is passed to a ``do_`` method.  By
 default, both Python-style and C-style comments
 are recognized; you may change this by overriding
 ``app.commentGrammars`` with a different pyparsing_
-grammar.
+grammar (see the arg_print_ example for specifically how to to this).
 
 Comments can be useful in :ref:`scripts`, but would
 be pointless within an interactive session.
@@ -52,6 +52,7 @@ be pointless within an interactive session.
   it was  delicious!
 
 .. _pyparsing: http://pyparsing.wikispaces.com/
+.. _arg_print: https://github.com/python-cmd2/cmd2/blob/master/examples/arg_print.py
 
 Commands at invocation
 ======================
diff --git a/examples/arg_print.py b/examples/arg_print.py
new file mode 100755
index 00000000..20fa7c02
--- /dev/null
+++ b/examples/arg_print.py
@@ -0,0 +1,39 @@
+#!/usr/bin/env python
+# coding=utf-8
+"""A simple example demonstrating the following:
+    1) How arguments and options get parsed and passed to commands
+    2) How to change what syntax get parsed as a comment and stripped from the arguments
+
+This is intended to serve as a live demonstration so that developers can experiment with and understand how command
+and argument parsing is intended to work.
+"""
+import pyparsing
+import cmd2
+from cmd2 import options, make_option
+
+
+class ArgumentAndOptionPrinter(cmd2.Cmd):
+    """ Example cmd2 application where we create commands that just print the arguments they are called with."""
+
+    def __init__(self):
+        # Uncomment this line to disable Python-style comments but still allow C-style comments
+        # self.commentGrammars = pyparsing.Or([pyparsing.cStyleComment])
+
+        # Make sure to call this super class __init__ after setting commentGrammars and not before
+        cmd2.Cmd.__init__(self)
+
+    def do_aprint(self, arg):
+        """Print the argument string this basic command is called with."""
+        print('aprint was called with argument: {!r}'.format(arg))
+
+    @options([make_option('-p', '--piglatin', action="store_true", help="atinLay"),
+              make_option('-s', '--shout', action="store_true", help="N00B EMULATION MODE"),
+              make_option('-r', '--repeat', type="int", help="output [n] times")], arg_desc='positional_arg_string')
+    def do_oprint(self, arg, opts=None):
+        """Print the options and argument list this options command was called with."""
+        print('oprint was called with the following\n\toptions: {!r}\n\targuments: {!r}'.format(opts, arg))
+
+
+if __name__ == '__main__':
+    app = ArgumentAndOptionPrinter()
+    app.cmdloop()
diff --git a/setup.py b/setup.py
index 7d2821e4..b4b76098 100755
--- a/setup.py
+++ b/setup.py
@@ -5,7 +5,7 @@ Setuptools setup file, used to install or test 'cmd2'
 """
 from setuptools import setup
 
-VERSION = '0.7.7'
+VERSION = '0.7.8a'
 DESCRIPTION = "cmd2 - a tool for building interactive command line applications in Python"
 LONG_DESCRIPTION = """cmd2 is a tool for building interactive command line applications in Python. Its goal is to make 
 it quick and easy for developers to build feature-rich and user-friendly interactive command line applications.  It 
diff --git a/tests/test_cmd2.py b/tests/test_cmd2.py
index 4f65606d..11b03163 100644
--- a/tests/test_cmd2.py
+++ b/tests/test_cmd2.py
@@ -24,7 +24,7 @@ from conftest import run_cmd, normalize, BASE_HELP, HELP_HISTORY, SHORTCUTS_TXT,
 
 
 def test_ver():
-    assert cmd2.__version__ == '0.7.7'
+    assert cmd2.__version__ == '0.7.8a'
 
 
 def test_empty_statement(base_app):