From 7a2f0a210cbbfd53bb99d650c6e92d1ff2206dbd Mon Sep 17 00:00:00 2001 From: kotfu Date: Sun, 15 Jul 2018 16:21:16 -0600 Subject: Update description of command loop --- docs/hooks.rst | 32 ++++++++++++++++---------------- docs/integrating.rst | 25 ++++++++++++++++--------- 2 files changed, 32 insertions(+), 25 deletions(-) (limited to 'docs') diff --git a/docs/hooks.rst b/docs/hooks.rst index 3c91c6bf..a6a8d80a 100644 --- a/docs/hooks.rst +++ b/docs/hooks.rst @@ -78,21 +78,22 @@ the application exits: 1. Output the prompt 2. Accept user input -3. Parse user input into `Statement` object -4. Call methods registered with `register_postparsing_hook()` -5. Call `postparsing_precmd()` - for backwards compatibility with prior releases of cmd2, now deprecated -6. Redirect output, if user asked for it and it's allowed -7. Start timer -8. Call methods registered with `register_precmd_hook()` -9. Call `precmd()` - for backwards compatibility with ``cmd.Cmd`` -10. Add statement to history -11. Call `do_command` method -12. Call methods registered with `register_postcmd_hook()` -13. Call `postcmd(stop, statement)` - for backwards compatibility with ``cmd.Cmd`` -14. Stop timer and display the elapsed time -15. Stop redirecting output if it was redirected -16. Call methods registered with `register_cmdfinalization_hook()` -17. Call `postparsing_postcmd()` - for backwards compatibility - deprecated +3. Call `preparse()` - for backwards compatibility with prior releases of cmd2, now deprecated +4. Parse user input into `Statement` object +5. Call methods registered with `register_postparsing_hook()` +6. Call `postparsing_precmd()` - for backwards compatibility with prior releases of cmd2, now deprecated +7. Redirect output, if user asked for it and it's allowed +8. Start timer +9. Call methods registered with `register_precmd_hook()` +10. Call `precmd()` - for backwards compatibility with ``cmd.Cmd`` +11. Add statement to history +12. Call `do_command` method +13. Call methods registered with `register_postcmd_hook()` +14. Call `postcmd(stop, statement)` - for backwards compatibility with ``cmd.Cmd`` +15. Stop timer and display the elapsed time +16. Stop redirecting output if it was redirected +17. Call methods registered with `register_cmdfinalization_hook()` +18. Call `postparsing_postcmd()` - for backwards compatibility - deprecated By registering hook methods, steps 4, 8, 12, and 16 allow you to run code during, and control the flow of the command processing loop. Be aware that @@ -147,7 +148,6 @@ and raises a ``TypeError`` if it has the wrong number of parameters. It will also raise a ``TypeError`` if the passed parameter and return value are not annotated as ``PostparsingData``. - The hook method will be passed one parameter, a ``PostparsingData`` object which we will refer to as ``params``. ``params`` contains two attributes. ``params.statement`` is a ``Statement`` object which describes the parsed diff --git a/docs/integrating.rst b/docs/integrating.rst index 56691069..a234173c 100644 --- a/docs/integrating.rst +++ b/docs/integrating.rst @@ -56,15 +56,22 @@ script file. The **onecmd_plus_hooks()** method will do the following to execute a single ``cmd2`` command in a normal fashion: -#. Parse the command line text -#. Execute postparsing_precmd() -#. Add the command to the history -#. Apply output redirection, if present -#. Execute precmd() -#. Execute onecmd() - this is what actually runs the command -#. Execute postcmd() -#. Undo output rediriection (if present) and perform piping, if present -#. Execute postparsing_postcmd() +1. Call `preparse()` - for backwards compatibility with prior releases of cmd2, now deprecated +2. Parse user input into `Statement` object +3. Call methods registered with `register_postparsing_hook()` +4. Call `postparsing_precmd()` - for backwards compatibility with prior releases of cmd2, now deprecated +5. Redirect output, if user asked for it and it's allowed +6. Start timer +7. Call methods registered with `register_precmd_hook()` +8. Call `precmd()` - for backwards compatibility with ``cmd.Cmd`` +9. Add statement to history +10. Call `do_command` method +11. Call methods registered with `register_postcmd_hook()` +12. Call `postcmd(stop, statement)` - for backwards compatibility with ``cmd.Cmd`` +13. Stop timer and display the elapsed time +14. Stop redirecting output if it was redirected +15. Call methods registered with `register_cmdfinalization_hook()` +16. Call `postparsing_postcmd()` - for backwards compatibility - deprecated Running in this fashion enables the ability to integrate with an external event loop. However, how to integrate with any specific event loop is beyond the scope of this documentation. Please note that running in this fashion comes with -- cgit v1.2.1