summaryrefslogtreecommitdiff
path: root/docs/features/hooks.rst
diff options
context:
space:
mode:
authorkotfu <kotfu@kotfu.net>2019-07-06 05:09:46 -0600
committerkotfu <kotfu@kotfu.net>2019-07-06 05:09:46 -0600
commita19f5274325e9dd3f3f578f7a3e26b922e8f7ecd (patch)
tree8fe218c1ede5618c9964f3f20c988383df9f92be /docs/features/hooks.rst
parent9e64f600b65d99ea5a83051372372512be698b1b (diff)
downloadcmd2-git-a19f5274325e9dd3f3f578f7a3e26b922e8f7ecd.tar.gz
Formatting cleanups
Diffstat (limited to 'docs/features/hooks.rst')
-rw-r--r--docs/features/hooks.rst29
1 files changed, 16 insertions, 13 deletions
diff --git a/docs/features/hooks.rst b/docs/features/hooks.rst
index 5db97fe5..01d12425 100644
--- a/docs/features/hooks.rst
+++ b/docs/features/hooks.rst
@@ -1,7 +1,5 @@
-.. cmd2 documentation for application and command lifecycle and the available hooks
-
-cmd2 Application Lifecycle and Hooks
-====================================
+Hooks
+=====
The typical way of starting a cmd2 application is as follows::
@@ -17,6 +15,7 @@ There are several pre-existing methods and attributes which you can tweak to
control the overall behavior of your application before, during, and after the
command processing loop.
+
Application Lifecycle Hooks
---------------------------
@@ -114,8 +113,9 @@ If a hook raises any other exception:
Specific types of hook methods have additional options as described below.
+
Postparsing Hooks
-^^^^^^^^^^^^^^^^^
+-----------------
Postparsing hooks are called after the user input has been parsed but before
execution of the command. These hooks can be used to:
@@ -186,7 +186,7 @@ attribute set to ``True``:
Precommand Hooks
-^^^^^^^^^^^^^^^^^
+----------------
Precommand hooks can modify the user input, but can not request the application
terminate. If your hook needs to be able to exit the application, you should
@@ -224,7 +224,7 @@ with ``cmd.Cmd``, this method is passed a ``Statement``, not a
Postcommand Hooks
-^^^^^^^^^^^^^^^^^^
+-----------------
Once the command method has returned (i.e. the ``do_command(self, statement)
method`` has been called and returns, all postcommand hooks are called. If
@@ -254,10 +254,11 @@ After all registered postcommand hooks have been called,
``self.postcmd(statement)`` will be called to retain full backward compatibility
with ``cmd.Cmd``.
-If any postcommand hook (registered or ``self.postcmd()``) returns a ``PostcommandData`` object
-with the stop attribute set to ``True``, subsequent postcommand hooks will still be called, as
-will the command finalization hooks, but once those hooks have all been called, the application
-will terminate. Likewise, if ``self.postcmd()`` returns ``True``, the command finalization hooks
+If any postcommand hook (registered or ``self.postcmd()``) returns a
+``PostcommandData`` object with the stop attribute set to ``True``, subsequent
+postcommand hooks will still be called, as will the command finalization hooks,
+but once those hooks have all been called, the application will terminate.
+Likewise, if ``self.postcmd()`` returns ``True``, the command finalization hooks
will be called before the application terminates.
Any postcommand hook can change the value of the ``stop`` parameter before
@@ -270,7 +271,7 @@ compelling reason to do otherwise.
Command Finalization Hooks
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+--------------------------
Command finalization hooks are called even if one of the other types of hooks or
the command method raise an exception. Here's how to create and register a
@@ -284,7 +285,9 @@ command finalization hook::
def myhookmethod(self, stop, statement):
return stop
-Command Finalization hooks must check whether the statement object is ``None``. There are certain circumstances where these hooks may be called before the statement has been parsed, so you can't always rely on having a statement.
+Command Finalization hooks must check whether the statement object is ``None``.
+There are certain circumstances where these hooks may be called before the
+statement has been parsed, so you can't always rely on having a statement.
If any prior postparsing or precommand hook has requested the application to
terminate, the value of the ``stop`` parameter passed to the first command