acme.helpers.interpreter.PContext.PContext

class documentation

class PContext:

Known subclasses: acme.runtime.ScriptManager.ACMEPContext

Constructor: PContext(script, symbols, logFunc, logErrorFunc, ...)

Process context for a single script.

This is the main runtime object for the interpreter. To run a script, create a PContext object, and call its run() method.

To add new symbols to the interpreter, inherit from PContext and add them to the symbols dictionary during initialization.

A PContext object can be re-used.

Method	`__init__`	Initialization of a `PContext` object.
Method	`arguments.setter`	Set the arguments for the current call scope.
Method	`clearEnvironment`	Remove all environment variables.
Method	`copyError`	Copy the error attributes from another `PContext` object.
Method	`delVariable`	Delete a variable for a name. If the variable exists in the global scope, it is deleted in all scopes. Otherwise, it is only deleted in the current scope.
Method	`getEnvironmentVariable`	Return an evironment variable for a case insensitive name.
Method	`getMeta`	Return the argument of meta data, or an empty string.
Method	`getVariables`	Return all variables and values which names match a regular expression.
Method	`hasMeta`	Check if a meta data key exists.
Method	`logSymbol`	Log a symbol in verbose mode to the script's log function.
Method	`popCall`	Remove a call from the stack..
Method	`pushCall`	Save various stack information to the script's call stack. This creates a new PCall object.
Method	`reset`	Reset the context / script.
Method	`run`	Run the script in the `PContext` instance.
Method	`scriptName.setter`	Set the name of the script in the meta data.
Method	`setEnvironment`	Clear old environment and assign a new environment.
Method	`setEnvironmentVariable`	Set an environment variable for a name.
Method	`setError`	Set the internal state and error codes.
Method	`setMaxRuntime`	Set the maximum runtime of the script.
Method	`setResult`	Set the result symbol. The difference to directly setting the `result` attribute is that his method return self.
Method	`setVariable`	Set a variable for a name. If the variable exists in the global scope, it is updated or set in all scopes. Otherwise, it is only updated or set in the current scope.
Class Variable	`__slots__`	Slots of class attributes.
Instance Variable	`allowBrackets`	Allow "[" and "]" for opening and closing lists as well.
Instance Variable	`argv`	List of string that are arguments to the script.
Instance Variable	`ast`	The script's abstract syntax tree.
Instance Variable	`environment`	Dictionary of variables that are passed by the application to the script. Similar to `variables`, but the environment is not cleared.
Instance Variable	`error`	Error state.
Instance Variable	`errorFunc`	An optional function that is called when an error occured.
Instance Variable	`evaluateInline`	Check and execute inline expressions in strings.
Instance Variable	`fallbackFunc`	An optional function to retrieve unknown symbols from the caller.
Instance Variable	`functions`	Dictoonary of defined script functions.
Instance Variable	`logErrorFunc`	An optional function that receives error log messages.
Instance Variable	`logFunc`	An optional function that receives non-error log messages.
Instance Variable	`matchFunc`	An optional function that is used to run regex comparisons.
Instance Variable	`maxRuntime`	Number of seconds that is a script allowed to run.
Instance Variable	`meta`	Dictionary of the script's meta tags and their arguments.
Instance Variable	`monitorFunc`	An optional function to monitor function calls, e.g. to forbid them during particular executions.
Instance Variable	`postFunc`	An optional function that is called after running a script.
Instance Variable	`preFunc`	An optional function that is called before running a script.
Instance Variable	`printFunc`	An optional function for printing messages to the screen, console, etc.
Instance Variable	`result`	Intermediate and final results during the execution.
Instance Variable	`script`	The script to run.
Instance Variable	`startupSymbols`	The built-in commands. This original list will be restored later during reset.
Instance Variable	`state`	The internal state of a script.
Instance Variable	`symbols`	A dictionary of new symbols / functions to add to the interpreter.
Instance Variable	`verbose`	Print more debug messages.
Property	`arguments`	Return the arguments of the current call.
Property	`currentCall`	Get the current call as a `PCall` object.
Property	`scriptName`	The name of the script (from the meta data).
Property	`variables`	The variables of the current scope.
Class Variable	`_macroMatch`	Regex for matching macros in strings and JSON.
Instance Variable	`_callStack`	The internal call stack (internal).
Instance Variable	`_maxRTimestamp`	The max timestamp until the script may run (internal).

def __init__(self, script: str, symbols: PSymbolDict | None = None, logFunc: PLogCallable | None = lambda pcontext, msg: print(f'** {msg}'), logErrorFunc: PErrorLogCallable | None = lambda pcontext, msg, exception: print(f'!! {msg}'), printFunc: PLogCallable | None = lambda pcontext, msg: print(msg), preFunc: PFuncCallable | None = None, postFunc: PFuncCallable | None = None, errorFunc: PFuncCallable | None = None, matchFunc: PMatchCallable | None = lambda pcontext, l, r: l == r, maxRuntime: float | None = None, fallbackFunc: PSymbolCallable | None = None, monitorFunc: PSymbolCallable | None = None, allowBrackets: bool | None = False, verbose: bool | None = False): ¶

overridden in acme.runtime.ScriptManager.ACMEPContext

Initialization of a PContext object.

Parameters
script:`str`	The script to run.
symbols:`PSymbolDict \| None`	An optional dictionary of new symbols / functions to add to the interpreter.
logFunc:`PLogCallable \| None`	An optional function that receives non-error log messages.
logErrorFunc:`PErrorLogCallable \| None`	An optional function that receives error log messages.
printFunc:`PLogCallable \| None`	An optional function for printing messages to the screen, console, etc.
preFunc:`PFuncCallable \| None`	An optional function that is called before running a script.
postFunc:`PFuncCallable \| None`	An optional function that is called after running a script.
errorFunc:`PFuncCallable \| None`	An optional function that is called when an error occured.
matchFunc:`PMatchCallable \| None`	An optional function that is used to run regex comparisons.
maxRuntime:`float \| None`	Number of seconds that is a script allowed to run.
fallbackFunc:`PSymbolCallable \| None`	An optional function to retrieve unknown symbols from the caller.
monitorFunc:`PSymbolCallable \| None`	An optional function to monitor function calls, e.g. to forbid them during particular executions.
allowBrackets:`bool \| None`	Allow "[" and "]" for opening and closing lists as well.
verbose:`bool \| None`	Print more debug messages.

@arguments.setter

def arguments(self, value: dict[str, SSymbol]): ¶

Set the arguments for the current call scope.

Parameters
value:`dict[str, SSymbol]`	The arguments for the current call scope.

def clearEnvironment(self): ¶

Remove all environment variables.

def copyError(self, pcontext: PContext): ¶

Copy the error attributes from another PContext object.

Parameters
pcontext:`PContext`	PContext object from which to copy the error status.

def delVariable(self, key: str) -> SSymbol | None: ¶

Delete a variable for a name. If the variable exists in the global scope, it is deleted in all scopes. Otherwise, it is only deleted in the current scope.

Parameters
key:`str`	Variable name

Returns
`SSymbol \| None`	Variable content, or None if variable is not defined.

def getEnvironmentVariable(self, key: str) -> SSymbol: ¶

Return an evironment variable for a case insensitive name.

Parameters
key:`str`	Environment variable name

Returns
`SSymbol`	Environment variable content, or None.

def getMeta(self, key: str, default: str | None = '') -> str: ¶

Return the argument of meta data, or an empty string.

Parameters
key:`str`	Key of the meta data to look for.
default:`str \| None`	Default value to return if the key is not found.

Returns
`str`	String, value or the default value.

def getVariables(self, expression: str) -> list[tuple[str, SSymbol]]: ¶

Return all variables and values which names match a regular expression.

Parameters
expression:`str`	A string with the regular expression.

Returns
`list[tuple[str, SSymbol]]`	List of tuples ( variable name, variable value ).

def hasMeta(self, key: str) -> bool: ¶

Check if a meta data key exists.

Parameters
key:`str`	Key of the meta data to look for.

Returns
`bool`	True if the key exists, False otherwise.

def logSymbol(self, symbol: SSymbol): ¶

Log a symbol in verbose mode to the script's log function.

Parameters
symbol:`SSymbol`	The `SSymbol` object to log.

def popCall(self): ¶

Remove a call from the stack..

def pushCall(self, name: str | None = None, args: dict[str, SSymbol] = {}) -> PCall: ¶

Save various stack information to the script's call stack. This creates a new PCall object.

Parameters
name:`str \| None`	Name of the function.
args:`dict[str, SSymbol]`	Arguments for the function call.

Returns
`PCall`	The new `PCall` object.

def reset(self): ¶

Reset the context / script.

def run(self, arguments: list[str] = [], isSubCall: bool | None = False) -> PContext: ¶

Run the script in the PContext instance.

Parameters
arguments:`list[str]`	Optional list of string arguments to the script. They are available to the script via the argv function.
isSubCall:`bool \| None`	Optional indicator whether the script is called from another script.

Returns
`PContext`	`PContext` object with the result and the termination reason.

@scriptName.setter

def scriptName(self, name: str): ¶

Set the name of the script in the meta data.

Parameters
name:`str`	Name of the script.

def setEnvironment(self, environment: dict[str, SSymbol] | None = {}): ¶

Clear old environment and assign a new environment.

This includes the meta tags in the format meta.<tag>.

Parameters
environment:`dict[str, SSymbol] \| None`	Dictionary with the new environment

def setEnvironmentVariable(self, key: str, value: SSymbol): ¶

Set an environment variable for a name.

Parameters
key:`str`	Environment variable name
value:`SSymbol`	Value to store

def setError(self, error: PError, msg: str, state: PState | None = PState.terminatedWithError, expression: SSymbol = None, exception: Exception | None = None) -> PContext: ¶

Set the internal state and error codes.

These can be retrieved by accessing the state and error attributes.

Parameters
error:`PError`	`PError` to indicate the type of error.
msg:`str`	String that further explains the error.
state:`PState \| None`	`PState` to indicate the state of the script. Default is "terminatedWithError".
expression:`SSymbol`	The original `SSymbol` that caused the error.
exception:`Exception \| None`	Optional exception to provide with the error message.

Returns
`PContext`	Self.

def setMaxRuntime(self, maxRuntime: float): ¶

Set the maximum runtime of the script.

Parameters
maxRuntime:`float`	Maximum runtime in seconds.

def setResult(self, symbol: SSymbol) -> PContext: ¶

Set the result symbol. The difference to directly setting the result attribute is that his method return self.

Parameters
symbol:`SSymbol`	The `SSymbol` object to set as a result.

Returns
`PContext`	Self.

def setVariable(self, key: str, value: SSymbol): ¶

Set a variable for a name. If the variable exists in the global scope, it is updated or set in all scopes. Otherwise, it is only updated or set in the current scope.

Parameters
key:`str`	Variable name
value:`SSymbol`	Value to store

__slots__: tuple[str, ...] = ¶

overridden in acme.runtime.ScriptManager.ACMEPContext

Slots of class attributes.

allowBrackets = ¶

Allow "[" and "]" for opening and closing lists as well.

argv: list[str] = ¶

List of string that are arguments to the script.

ast: SSymbolsList = ¶

The script's abstract syntax tree.

environment: dict[str, SSymbol] = ¶

Dictionary of variables that are passed by the application to the script. Similar to variables, but the environment is not cleared.

error: PErrorState = ¶

Error state.

errorFunc = ¶

An optional function that is called when an error occured.

evaluateInline: bool = ¶

Check and execute inline expressions in strings.

fallbackFunc = ¶

An optional function to retrieve unknown symbols from the caller.

functions: dict[str, FunctionDefinition] = ¶

Dictoonary of defined script functions.

logErrorFunc = ¶

An optional function that receives error log messages.

logFunc = ¶

An optional function that receives non-error log messages.

matchFunc = ¶

An optional function that is used to run regex comparisons.

maxRuntime = ¶

overridden in acme.runtime.ScriptManager.ACMEPContext

Number of seconds that is a script allowed to run.

meta: dict[str, str] = ¶

Dictionary of the script's meta tags and their arguments.

monitorFunc = ¶

An optional function to monitor function calls, e.g. to forbid them during particular executions.

postFunc = ¶

An optional function that is called after running a script.

preFunc = ¶

An optional function that is called before running a script.

printFunc = ¶

An optional function for printing messages to the screen, console, etc.

result: SSymbol = ¶

Intermediate and final results during the execution.

script = ¶

The script to run.

startupSymbols = ¶

The built-in commands. This original list will be restored later during reset.

state: PState = ¶

The internal state of a script.

symbols: PSymbolDict = ¶

A dictionary of new symbols / functions to add to the interpreter.

verbose: bool = ¶

Print more debug messages.

@property

arguments: dict[str, SSymbol] = ¶

Return the arguments of the current call.

Returns
The arguments of the current call.

@property

currentCall: PCall | None = ¶

Get the current call as a PCall object.

Returns
`PCall` object, or None.

@property

scriptName: str = ¶

The name of the script (from the meta data).

Returns
The name of the script, or None.

@property

variables: dict[str, SSymbol] = ¶

The variables of the current scope.

Returns
The variables of the current scope.

_macroMatch = ¶

Regex for matching macros in strings and JSON.

_callStack: list[PCall] = ¶

The internal call stack (internal).

_maxRTimestamp: float = ¶

The max timestamp until the script may run (internal).