Merge pull request #235 from python-cmd2/command_aliases

Updated docs to make updating shortcuts more clear

Author: tleonhardt

docs/index.rst

@@ -48,7 +48,6 @@ Resources
 * `project bug tracker`_
 * Florida PyCon 2017: `slides <https://docs.google.com/presentation/d/1LRmpfBt3V-pYQfgQHdczf16F3hcXmhK83tl77R6IJtE>`_
 * PyOhio 2011: `video <https://archive.org/details/pyvideo_541___pyohio-2011-interactive-command-line-interpreters-with-cmd-and-cmd2>`_
-* PyCon 2010: `video <http://pyvideo.org/pycon-us-2010/pycon-2010--easy-command-line-applications-with-c.html>`_
 
 These docs will refer to ``App`` as your ``cmd2.Cmd``
 subclass, and ``app`` as an instance of ``App``.  Of

docs/settingchanges.rst

@@ -19,11 +19,11 @@ Whether or not you set ``case_insensitive``, *please do not* define
 command method names with any uppercase letters.  ``cmd2`` expects all command methods
 to be lowercase.
 
-Shortcuts
-=========
+Shortcuts (command aliases)
+===========================
 
-Special-character shortcuts for common commands can make life more convenient for your
-users.  Shortcuts are used without a space separating them from their arguments,
+Command aliases for long command names such as special-character shortcuts for common commands can make life more
+convenient for your users.  Shortcuts are used without a space separating them from their arguments,
 like ``!ls``.  By default, the following shortcuts are defined:
 
   ``?``
@@ -42,7 +42,20 @@ To define more shortcuts, update the dict ``App.shortcuts`` with the
 {'shortcut': 'command_name'} (omit ``do_``)::
 
   class App(Cmd2):
-      Cmd2.shortcuts.update({'*': 'sneeze', '~': 'squirm'})
+      def __init__(self):
+        # Make sure you update the shortcuts attribute before calling the super class __init__
+        self.shortcuts.update({'*': 'sneeze', '~': 'squirm'})
+
+        # Make sure to call this super class __init__ after updating shortcuts
+        cmd2.Cmd.__init__(self)
+
+.. warning::
+
+  Command aliases needed to be created by updating the ``shortcuts`` dictionary attribute prior to calling the
+  ``cmd2.Cmd`` super class ``__init__()`` method.  Moreover, that super class init method needs to be called after
+  updating the ``shortcuts`` attribute  This warning applies in general to many other attributes which are not
+  settable at runtime such as ``commentGrammars``, ``multilineCommands``, etc.
+
 
 Default to shell
 ================

examples/arg_print.py

@@ -6,6 +6,8 @@
 
 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.
+
+It also serves as an example of how to create command aliases (shortcuts).
 """
 import pyparsing
 import cmd2
@@ -19,8 +21,13 @@ 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
+        # Create command aliases which are shorter
+        self.shortcuts.update({'ap': 'aprint', 'op': 'oprint'})
+
+        # Make sure to call this super class __init__ *after* setting commentGrammars and/or updating shortcuts
         cmd2.Cmd.__init__(self)
+        # NOTE: It is critical that the super class __init__ method be called AFTER updating certain parameters which
+        # are not settable at runtime.  This includes the commentGrammars, shortcuts, multilineCommands, etc.
 
     def do_aprint(self, arg):
         """Print the argument string this basic command is called with."""