crash.commands package
**********************

The crash.commands module is the interface for implementing commands
in crash-python.

The only mandatory part of implementing a command is to derive a class
from "Command", implement the "Command.execute()" method, and
instantiate it.  If the command should have multiple aliases, accept a
name in the constructor and instantiate it multiple times.

Optional extensions:

* Adding a parser (derived from "ArgumentParser") that parses
  arguments.  If not provided, an empty parser will be used.

* Adding a module docstring to be used as help text.  If not provided,
  the argparse generic help text will be used instead.

The module docstring will be placed automatically in the command
reference section of the user guide and will also be converted into
plaintext help for use in command execution.  It should be in
reStructuredText format.

Example:

   """
   NAME
   ----

     helloworld

   SYNOPSYS
   --------

     ``helloworld`` -- a command that prints hello world
   """

   import crash.commands

   class HelloWorld(crash.commands.Command):
       def __init__(self) -> None:
           parser = crash.commands.ArgumentParser(prog='helloworld')

           super().__init__('helloworld', parser)

       def execute(self, args: argparse.Namespace) -> None:
           print("hello world")

   HelloWorld()

class crash.commands.ArgumentParser(*args: Any, **kwargs: Any)

   Bases: "ArgumentParser"

   A simple extension to "argparse.ArgumentParser" that:

   * Requires a command name be set

   * Loads help text automatically from files

   * Handles errors by raising "CommandLineError"

   static address(v: str) -> int

   error(message: str) -> Any

      An error callback that raises the "CommandLineError" exception.

   format_help() -> str

      A help formatter that loads the parsed rST documentation from
      disk or returns the generic help text otherwise.

class crash.commands.Command(name: str, parser: ArgumentParser = None)

   Bases: "Command"

   The Command class is the starting point for implementing a new
   command.

   The "Command.execute()" method will be invoked when the user
   invokes the command.

   Once the constructor returns, the command will be registered with
   "gdb" and the command will be available for use.

   Parameters:
      * **name** -- The name of the command.  The string "py" will be
        prefixed to it.

      * **parser** -- The parser to use to handle the arguments.  It
        must be derived from the "ArgumentParser" class.

   Raises:
      **ArgumentTypeError** -- The parser is not derived from
      "ArgumentParser".

   execute(args: Namespace) -> None

      This method implements the command functionality.

      Each command has a derived class associated with it that,
      minimally, implements this method.

      Parameters:
         **args** -- The arguments to this command already parsed by
         the commmand's parser.

   format_help() -> str

      Used by the "help" module, it delegates the help formatting to
      the parser object.

   invoke(argstr: str, from_tty: bool = False) -> None

      Invokes the command directly and translates exceptions.

      This method is called by "gdb" to implement the command.

      It translates the "CommandError", "CommandLineError", and
      "DelayedAttributeError" exceptions into readable error messages.

      Unless you are doing something special, see "execute()" instead.

      Parameters:
         * **argstr** -- The command arguments

         * **from_tty** (*default=False*) -- Whether the command was
           invoked from a tty.

   invoke_uncaught(argstr: str, from_tty: bool = False) -> None

      Invokes the command directly and does not catch exceptions.

      This is used mainly for unit testing to ensure proper exceptions
      are raised.

      Unless you are doing something special, see "execute()" instead.

      Parameters:
         * **argstr** -- The command arguments

         * **from_tty** (*default=False*) -- Whether the command was
           invoked from a tty.

exception crash.commands.CommandError

   Bases: "RuntimeError"

   An error occured while executing this command

exception crash.commands.CommandLineError

   Bases: "RuntimeError"

   An error occured while handling the command line for this command

crash.commands.discover() -> None
