Class Statement

cmd2/parsing.py:102–244

String subclass with additional attributes to store the results of parsing. Instances of this class should not be created by anything other than the [StatementParser.parse][cmd2.parsing.StatementParser.parse] method, nor should any of the attributes be modified once the object is create

@dataclass(frozen=True)
class Statement(str):  # noqa: SLOT000
    """String subclass with additional attributes to store the results of parsing.

    Instances of this class should not be created by anything other than the
    [StatementParser.parse][cmd2.parsing.StatementParser.parse] method, nor should any of the
    attributes be modified once the object is created.

    The string portion of the class contains the arguments, but not the
    command, nor the output redirection clauses.

    Tips:

    1. `argparse <https://docs.python.org/3/library/argparse.html>`_ is your
       friend for anything complex. ``cmd2`` has the decorator
       ([cmd2.decorators.with_argparser][]) which you can
       use to make your command method receive a namespace of parsed arguments,
       whether positional or denoted with switches.

    2. For commands with simple positional arguments, use
       [args][cmd2.parsing.Statement.args] or [arg_list][cmd2.parsing.Statement.arg_list]

    3. If you don&#x27;t want to have to worry about quoted arguments, see
       [argv][cmd2.parsing.Statement.argv] for a trick which strips quotes off for you.
    """

    # A space-delimited string containing the arguments to the command (quotes preserved).
    # This does not include any output redirection clauses.
    # Note: If a terminator is present, characters that would otherwise be
    # redirectors (like '>') are treated as literal arguments if they appear
    # before the terminator.
    args: str = ""

    # The original, unmodified input string
    raw: str = ""

    # The resolved command name (after shortcut/alias expansion)
    command: str = ""

    # Whether the command is recognized as a multiline-capable command
    multiline_command: bool = False

    # The character which terminates the command/arguments portion of the input.
    # While primarily used to signal the end of multiline commands, its presence
    # defines the boundary between arguments and any subsequent redirection.
    terminator: str = ""

    # Characters appearing after the terminator but before output redirection
    suffix: str = ""

    # The operator used to redirect output (e.g. '>', '>>', or '|').
    redirector: str = ""

    # The destination for the redirected output (a file path or a shell command).
    # Quotes are preserved.
    redirect_to: str = ""

    def __new__(cls, value: object, *_pos_args: Any, **_kw_args: Any) -> Self:
        """Create a new instance of Statement.