7. pypsi.cmdline - User input processing

Classes used for parsing user input.

7.1. Commands and expressions

class pypsi.cmdline.Expression(operand, operator, value)

Bases: object

Holds a string-based expression in the form of operand operator value. This class makes parsing expressions that may be in a single string or a list of strings. For example, the pypsi.plugins.VarCommand command accepts input in the form of: name = value. This class allows for the user to input any of the following lines and the same Expression object would be created, regardless of how the input lines are tokenized:

• some_var = 2 => ['some_var', '=', '2']
• some_var= 2 => ['some_var=', '2']
• some_var =2 => ['some_var', '=2']
• some_var=2 => ['some_var=2']

classmethod parse(args)

Create an Expression from a list of strings.

Parameters:args (list) – arguments Returns:a tuple of (remaining, expression), where remaining is the list of remaining string arguments of args after parsing has completed, and expression in the parsed Expression, or None if the expression is invalid.

class pypsi.cmdline.CommandInvocation(name, args=None, stdout=None, stderr=None, stdin=None, chain=None)

Bases: object

An invocation of a command.

__call__(shell)

Invoke the command by proxying streams, running the command, and cleaning the resetting streams.

Returns:the commnd’s return code.

chain_and()

Returns:True if the chain operator is AND (&&)

chain_or()

Returns:True if the chain operator is OR (||)

chain_pipe()

Returns:True if the chain operator is PIPE (|)

chain_uncond()

Returns:True if the chain operator is UNCONDITIONAL (;)

cleanup_io()

Close proxied streams and unproxy them.

close_streams()

Close all streams that were opened.

get_input(stream)

Open an input stream, if specified.

Returns file:the stream opened for reading if specified, otherwise None.

get_output(output)

Open an output stream, if specified.

Returns file:the stream opened for writting if specified, otherwise const:None.

get_stream(path, mode, safe=False)

Open a file path.

Parameters:

• path (str) – file path
• mode (str) – file open mode
• safe (bool) – whether to use pypsi.util.safe_open() instead of the standard open() method.

Raises:

IORedirectionError – stream could not be opened

setup(shell)

Retrieve the Pypsi command to execute and setup the streams for stdout, stderr, and stdin depending on whether I/O redirection is being performed.

Raises:

• CommandNotFoundError – command specified does not exist
• IORedirectionError – I/O redirection error occurred

setup_io()

Setup stdout, stderr, and stdin by proxying the thread local streams.

should_continue(prev_rc)

Returns:whether this invocation is chained and, using the previous invocation’s return code, determine if the next command in the chain should be executed.

args = None

List of command arguments

chain = None

The chain operator, if any is specified: &&, ||, |, ;.

cmd = None

The resolved pypsi command (Command)

fallback_cmd = None

The fallback command to use if cmd is None.

name = None

Command name

stderr = None

stderr redirection

stdin = None

stderr redirection

stdout = None

stdout redirection

7.2. Tokens

7.2.1. Constants

These constants are returned by each token’s add_char() function to determine where tokens begin, end, and what they contain.

pypsi.cmdline.TokenContinue = 0

The token accepts more characters.

pypsi.cmdline.TokenEnd = 1

The token does not accept the current chracter.

pypsi.cmdline.TokenTerm = 2

The token is finished and the current chracter should not be processed again.

7.2.2. Classes

class pypsi.cmdline.Token(index, features=None)

Bases: object

Base class for all tokens.

Parameters:index (int) – the starting index of this token

class pypsi.cmdline.WhitespaceToken(index, c=' ', features=None)

Bases: pypsi.cmdline.Token

Whitespace token that can contain any number of whitespace characters.

add_char(c)

Add a character to this token.

Parameters:c (str) – the current character Returns int:TokenEnd or TokenContinue

class pypsi.cmdline.StringToken(index, c, quote=None, features=None)

Bases: pypsi.cmdline.Token

A string token. This token may be bound by matching quotes and/or contain escaped whitespace characters.

Parameters:

• c (str) – the current string or character
• quote (str) – the surrounding quotes, None if there isn’t any

add_char(c)

Add a character to this token.

Parameters:c (str) – the current character Returns int:TokenEnd or TokenContinue

class pypsi.cmdline.OperatorToken(index, operator)

Bases: pypsi.cmdline.Token

An operator token. An operator can consist of one or more repetitions of the same operator character. For example, the string “>>” would be parsed as one OperatorToken, whereas the string “<>” would be parsed as two separate OperatorToken objects.

Parameters:operator (str) – the operator

add_char(c)

Add a character to this token.

Parameters:c (str) – the current character Returns int:TokenEnd or TokenContinue

Operators = '<>|&;'

Valid operator characters

7.3. Statements

class pypsi.cmdline.StatementParser(features=None)

Bases: object

Parses raw user input into a Statement.

build(tokens)

Create a Statement object from tokenized input and statement context. This method will first remove all remaining escape sequences and then condense() all the tokens before building the statement.

Parameters:tokens (list) – list of Token objects to process as a statement Raises:StatementSyntaxError on error Returns:(Statement) the parsed statement

clean_escapes(tokens)

Remove all escape sequences.

Parameters:tokens (list) – Token objects to remove escape sequences

condense(tokens)

Condenses sequential like Token objects into a single Token of the same type. For example, two sequential StringToken objects will be concatenated into a single StringToken.

Parameters:tokens (list) – Token objects to condense Returns:condensed list of Token objects

process(index, c)

Process a single character of input.

Parameters:

• index (int) – current character index
• c (str) – current character

tokenize(line)

Transform a str into a list of Token objects.

Parameters:line (str) – the line of text to tokenize Returns:list of Token objects

class pypsi.cmdline.Statement(invokes=None)

Bases: object

A parsed statement containing a list of CommandInvocation instances.

Parameters:invokes (list[CommandInvocation]) – list of command invocations

__iter__()

Returns:an iterator for the CommandInvocation instances

__len__()

Returns int:the number of command invocations

append(invoke)

Append a new command invocation.

Parameters:invoke (CommandInvocation) – parsed command invocation

7.3.1. Exceptions

class pypsi.cmdline.StatementSyntaxError(message, index)

Bases: SyntaxError

Invalid statement syntax was entered.

Parameters:

• message (str) – error message
• index (int) – index in the statement that caused the error

class pypsi.cmdline.CommandNotFoundError(name)

Bases: Exception

The specified command does not exist.

name = None

the command name