Environment

Internal documentation for the amalgam.environment module.

class amalgam.environment.Environment(bindings: Bindings = None, parent: Environment = None, name: str = 'unknown', engine: Engine = None)

Class that manages and represents nested execution environments.

bindings

A mapping of str keys to amalgams.Amalgam values.

Type

Dict[str, Amalgam]

parent

The parent Environment instance to search into, forming a linked list.

Type

Optional[Environment]

level

The current length of the Environment linked list. If a parent is provided, sets the current value to the parent’s level + 1.

Type

int

search_depth

The search depth when traversing the Environment linked list in the __contains__(), __delitem__(), __getitem__(), and __setitem__() methods.

Type

int

name

The name of the execution environment.

Type

str

engine

A reference to the engine managing the parser.Parser instance and the global Environment instance.

Type

Engine

__contains__(item: str) → bool

Recursively checks whether an item exists.

Searches with respect to the current search_depth of the calling Environment instance. If the target item is encountered at a certain depth less than the target depth, immediately returns True, otherwise, returns False.

__delitem__(item: str) → None

Attempts to recursively delete the provided item.

Searches with respect to the current search_depth of the calling Environment instance. If an existing item is encountered at a certain depth less than the target depth, deletes that item instead.

__getitem__(item: str) → Amalgam

Attempts to recursively obtain the provided item.

Searches with respect to the current search_depth of the calling Environment instance. If an existing item is encountered at a certain depth less than the target depth, returns that item, otherwise, raises SymbolNotFound.

__setitem__(item: str, value: Amalgam) → None

Attempts to recursively set the provided value to an item.

Searches with respect to the current search_depth of the calling Environment instance. If an existing item is encountered at a certain depth less than the target depth, overrides that item instead.

env_pop() → amalgam.environment.Environment

Discards the current Environment and returns the parent Environment.

env_push(bindings: Bindings = None, name: str = None) → Environment

Creates a new Environment and binds the calling instance as its parent environment.

search_at(*, depth=0)

Context manager for temporarily setting the lookup depth.

The provided depth argument must not exceed the level of the calling Environment instance, and will raise a ValueError if done so.

>>> env = Environment(FUNCTIONS)
>>>
>>> with env.search_at(depth=42):
...     env["+"]  # Raises ValueError

Any negative integer can be passed as a depth to signify an infinite lookup until the top-most environment.

>>> env = Environment(FUNCTIONS)
>>> cl_env = env.env_push({...})
>>>
>>> with cl_env.search_at(depth=-1):
...    cl_env["+"]  # Searches `env`

class amalgam.environment.TopLevelPop

Raised at Environment.env_pop().