diff options
Diffstat (limited to 'docs/migrating/next_steps.rst')
| -rw-r--r-- | docs/migrating/next_steps.rst | 60 |
1 files changed, 58 insertions, 2 deletions
diff --git a/docs/migrating/next_steps.rst b/docs/migrating/next_steps.rst index 3f560501..f43c69c9 100644 --- a/docs/migrating/next_steps.rst +++ b/docs/migrating/next_steps.rst @@ -1,6 +1,62 @@ Next Steps ========== -What features (with links to details) are easy to implement next +Once your current application is using ``cmd2``, you can start to expand the +functionality by levering other ``cmd2`` features. The three ideas here will +get you started. Browse the rest of the :ref:`features/index:Features` to see +what else ``cmd2`` can help you do. -:doc:`Help <../features/help>` + +Argument Parsing +---------------- + +For all but the simplest of commands, it's probably easier to use `argparse +<https://docs.python.org/3/library/argparse.html>`_ to parse user input. +``cmd2`` provides a ``@with_argparser()`` decorator which associates an +``ArgumentParser`` object with one of your commands. Using this method will: + +1. Pass your command a `Namespace +<https://docs.python.org/3/library/argparse.html#argparse.Namespace>`_ +containing the arguments instead of a string of text. + +2. Properly handle quoted string input from your users. + +3. Create a help message for you based on the ``ArgumentParser``. + +4. Give you a big headstart adding :ref:`features/completion:Completion` to + your application. + +5. Make it much easier to implement subcommands (i.e. ``git`` has + a bunch of subcommands such as ``git pull``, ``git diff``, etc). + +There's a lot more about :ref:`features/argument_processing:Argument +Processing` if you want to dig in further. + + +Help +---- + +If you have lot of commands in your application, ``cmd2`` can categorize those +commands using a one line decorator ``@with_category()``. When a user types +``help`` the available commands will be organized by the category you +specified. + +If you were already using ``argparse`` or decided to switch to it, you can +easily :ref:`standardize all of your help messages +<features/argument_processing:Help Messages>` to be generated by your argument +parsers and displayed by ``cmd2``. No more help messages that don't match what +the code actually does. + + +Generating Output +----------------- + +If your program generates output by printing directly to ``sys.stdout``, you +should consider switching to :meth:`cmd2.cmd2.Cmd.poutput`, +:meth:`cmd2.cmd2.Cmd.perror`, and :meth:`cmd2.cmd2.Cmd.pfeedback`. These +methods work with several of the built in :ref:`features/settings:Settings` to +allow the user to view or suppress feedback (i.e. progress or status output). +They also properly handle ansi colored output according to user preference. +Speaking of colored output, you can use any color library you want, or use the +included :meth:`cmd2.ansi.style` function. These and other related topics are +covered in :ref:`features/generating_output:Generating Output`. |