cmd2.parsing
cmd2.parsing
Statement parsing classes for cmd2
MacroArg
dataclass
Information used to replace or unescape arguments in a macro value when the macro is resolved Normal argument syntax: {5} Escaped argument syntax: {{5}}
macro_normal_arg_pattern
class-attribute
instance-attribute
macro_escaped_arg_pattern
class-attribute
instance-attribute
Macro
dataclass
Statement
dataclass
Statement(args='', raw='', command='', arg_list=list(), multiline_command='', terminator='', suffix='', pipe_to='', output='', output_to='')
Bases: str
String subclass with additional attributes to store the results of parsing.
The cmd
module in the standard library passes commands around as a
string. To retain backwards compatibility, cmd2
does the same. However,
we need a place to capture the additional output of the command parsing, so
we add our own attributes to this subclass.
Instances of this class should not be created by anything other than the 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:
-
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. -
For commands with simple positional arguments, use args or arg_list
-
If you don't want to have to worry about quoted arguments, see argv for a trick which strips quotes off for you.
command_and_args
property
Combine command and args with a space separating them.
Quoted arguments remain quoted. Output redirection and piping are excluded, as are any command terminators.
post_command
property
A string containing any ending terminator, suffix, and redirection chars
argv
property
a list of arguments a-la sys.argv
.
The first element of the list is the command after shortcut and macro
expansion. Subsequent elements of the list contain any additional
arguments, with quotes removed, just like bash would. This is very
useful if you are going to use argparse.parse_args()
.
If you want to strip quotes from the input, you can use argv[1:]
.
to_dict
Utility method to convert this Statement into a dictionary for use in persistent JSON history files
from_dict
staticmethod
Utility method to restore a Statement from a dictionary
PARAMETER | DESCRIPTION |
---|---|
source_dict
|
source data dictionary (generated using to_dict())
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
Statement
|
Statement object |
RAISES | DESCRIPTION |
---|---|
KeyError
|
if source_dict is missing required elements |
Source code in cmd2/parsing.py
StatementParser
Parse user input as a string into discrete command components.
Initialize an instance of StatementParser.
The following will get converted to an immutable tuple before storing internally: terminators, multiline commands, and shortcuts.
PARAMETER | DESCRIPTION |
---|---|
terminators
|
iterable containing strings which should terminate commands
TYPE:
|
multiline_commands
|
iterable containing the names of commands that accept multiline input
TYPE:
|
aliases
|
dictionary containing aliases
TYPE:
|
shortcuts
|
dictionary containing shortcuts
TYPE:
|
Source code in cmd2/parsing.py
multiline_commands
instance-attribute
shortcuts
instance-attribute
is_valid_command
Determine whether a word is a valid name for a command.
Commands cannot include redirection characters, whitespace, or termination characters. They also cannot start with a shortcut.
PARAMETER | DESCRIPTION |
---|---|
word
|
the word to check as a command
TYPE:
|
is_subcommand
|
Flag whether this command name is a subcommand name
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
Tuple[bool, str]
|
a tuple of a boolean and an error string If word is not a valid command, return |
Source code in cmd2/parsing.py
tokenize
Lex a string into a list of tokens. Shortcuts and aliases are expanded and comments are removed.
PARAMETER | DESCRIPTION |
---|---|
line
|
the command line being lexed
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
List[str]
|
A list of tokens |
RAISES | DESCRIPTION |
---|---|
Cmd2ShlexError
|
if a shlex error occurs (e.g. No closing quotation) |
Source code in cmd2/parsing.py
parse
Tokenize the input and parse it into a cmd2.parsing.Statement object, stripping comments, expanding aliases and shortcuts, and extracting output redirection directives.
PARAMETER | DESCRIPTION |
---|---|
line
|
the command line being parsed
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
Statement
|
a new cmd2.parsing.Statement object |
RAISES | DESCRIPTION |
---|---|
Cmd2ShlexError
|
if a shlex error occurs (e.g. No closing quotation) |
Source code in cmd2/parsing.py
399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 |
|
parse_command_only
Partially parse input into a cmd2.Statement object.
The command is identified, and shortcuts and aliases are expanded. Multiline commands are identified, but terminators and output redirection are not parsed.
This method is used by tab completion code and therefore must not generate an exception if there are unclosed quotes.
The cmd2.parsing.Statement object returned by this method can at most contain values in the following attributes: cmd2.parsing.Statement.args, cmd2.parsing.Statement.raw, cmd2.parsing.Statement.command, cmd2.parsing.Statement.multiline_command
cmd2.parsing.Statement.args will include all output redirection clauses and command terminators.
Different from cmd2.parsing.StatementParser.parse this method does not remove redundant whitespace within args. However, it does ensure args has no leading or trailing whitespace.
PARAMETER | DESCRIPTION |
---|---|
rawinput
|
the command line as entered by the user
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
Statement
|
a new cmd2.Statement object |
Source code in cmd2/parsing.py
get_command_arg_list
Convenience method used by the argument parsing decorators.
Retrieves just the arguments being passed to their do_*
methods as a list.
PARAMETER | DESCRIPTION |
---|---|
command_name
|
name of the command being run
TYPE:
|
to_parse
|
what is being passed to the
TYPE:
|
preserve_quotes
|
if
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
Tuple[Statement, List[str]]
|
A tuple containing the cmd2.Statement and a list of strings representing the arguments |
Source code in cmd2/parsing.py
split_on_punctuation
Further splits tokens from a command line using punctuation characters.
Punctuation characters are treated as word breaks when they are in unquoted strings. Each run of punctuation characters is treated as a single token.
PARAMETER | DESCRIPTION |
---|---|
tokens
|
the tokens as parsed by shlex
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
List[str]
|
a new list of tokens, further split using punctuation |
Source code in cmd2/parsing.py
shlex_split
A wrapper around shlex.split() that uses cmd2's preferred arguments. This allows other classes to easily call split() the same way StatementParser does.
PARAMETER | DESCRIPTION |
---|---|
str_to_split
|
the string being split
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
List[str]
|
A list of tokens |