Amalgams

Internal documentation for the amalgam.amalgams module.

class amalgam.amalgams.Located

The base dataclass for encapsulating location data of nodes.

Provides an API similar to Lark’s Token class for convenience.

line_span

Lines spanned by a node

Type

Tuple[int, int]

column_span

Columns spanned by a node

Type

Tuple[int, int]

located_on(*, lines: Tuple[int, int] = (- 1, - 1), columns: Tuple[int, int] = (- 1, - 1)) → amalgam.amalgams.L

Helper method for setting Located.line_span and Located.column_span.

property column: int

The starting column number of a node.

property end_column: int

The ending column number of a node.

property end_line: int

The ending line number of a node.

property line: int

The starting line number of a node.

class amalgam.amalgams.Amalgam

The abstract base class for language constructs.

_make_repr(value: Any) → str

Helper method for creating a __repr__().

abstract evaluate(environment: Environment) → Any

Protocol for evaluating or unwrapping Amalgam objects.

class amalgam.amalgams.Atom(value: str)

An Amalgam that represents different atoms.

value

The name of the atom.

Type

str

evaluate(_environment: Environment) → Atom

Evaluates to the same Atom reference.

class amalgam.amalgams.Numeric(value: amalgam.amalgams.N)

An Amalgam that wraps around numeric types.

Parameterized as a Generic by: N = TypeVar("N", int, float, Fraction)

value

The numeric value being wrapped.

Type

N

evaluate(_environment: Environment) → Numeric

Evaluates to the same Numeric reference.

class amalgam.amalgams.Symbol(value: str)

An Amalgam that wraps around symbols.

value

The name of the symbol.

Type

str

evaluate(environment: Environment) → Amalgam

Searches the provided environment fully with Symbol.value. Returns the Amalgam object bound to the Symbol.value in the environment. Returns a fatal Notification if a binding is not found.

class amalgam.amalgams.Function(name: str, fn: Callable[[...], amalgam.amalgams.Amalgam], defer: bool = False, contextual: bool = False)

An Amalgam that wraps around functions.

name

The name of the function.

Type

str

fn

The function being wrapped. Must have the signature: (env, amalgams…) -> amalgam.

Type

Callable[..., Amalgam]

defer

If set to False, arguments are evaluated before being passed to Function.fn.

Type

bool

contextual

If set to True, disallows function calls when Function.in_context is set to False.

Type

bool

env

The environment.Environment instance bound to the function. Overrides the environment parameter passed to the Function.call() method.

Type

environment.Environment

in_context

Predicate that disallows functions to be called outside of specific contexts. Makes Function.call() return a fatal Notification when set to False and Function.contextual is set to True.

Type

bool

bind(environment: Environment) → Function

Sets the Function.env attribute and returns the same Function reference.

call(environment: Environment, *arguments: Amalgam) → Amalgam

Performs the call to the Function.fn attribute.

Performs pre-processing depending on the values of Function.defer, Function.contextual, and Function.in_context,

evaluate(_environment: Environment) → Function

Evaluates to the same Function reference.

with_name(name: str) → amalgam.amalgams.Function

Sets the Function.name attribute and returns the same Function reference.

class amalgam.amalgams.SExpression(*vals: amalgam.amalgams.Amalgam)

An Amalgam that wraps around S-Expressions.

vals

Entities contained by the S-Expression.

Type

Tuple[Amalgam, ...]

evaluate(environment: Environment) → Amalgam

Evaluates func using environment before invoking the call() method with environment and SExpression.args.

property args: Tuple[amalgam.amalgams.Amalgam, ...]

The rest of the SExpression.vals.

property func: amalgam.amalgams.Amalgam

The head of the SExpression.vals.

class amalgam.amalgams.Vector(*vals: amalgam.amalgams.T)

An Amalgam that wraps around a homogenous vector.

Parameterized as a Generic by: T = TypeVar("T", bound=Amalgam)

vals

Entities contained by the vector

Type

Tuple[T, ...]

mapping

Mapping representing vectors with Atom s for odd indices and Amalgam s for even indices.

Type

Mapping[str, Amalgam]

_as_mapping() → Mapping[str, amalgam.amalgams.Amalgam]

Attemps to create a Mapping[str, Amalgam] from Vector.vals.

Odd indices must be Atom s and even indices must be Amalgam s. Returns an empty mapping if this form is not met.

evaluate(environment: Environment) → Amalgam

Creates a new Vector by evaluating every value in Vector.vals.

class amalgam.amalgams.Quoted(value: amalgam.amalgams.T)

An Amalgam that defers evaluation of other Amalgam s.

Parameterized as a Generic by: T = TypeVar("T", bound=Amalgam)

value

The Amalgam being deferred.

Type

T

evaluate(_environment: Environment) → Quoted

Evaluates to the same Quoted reference.

class amalgam.amalgams.Failure(amalgam: Amalgam, environment: Environment, message: str)

Represents failures during evaluation.

amalgam

The Amalgam where evaluation failed.

Type

Amalgam

environment

The execution environment used to evaluate amalgam.

Type

Environment

message

An error message attached to the failure.

Type

str

class amalgam.amalgams.FailureStack(failures: List[amalgam.amalgams.Failure])

Represents a collection of Failure instances.

failures

A stack of Failure instances.

Type

List[Failure]

make_report(text: str, source: str = '<unknown>') → str

Generates a report to be printed to sys.stderr.

Accepts text and source for prettified output.

push(failure: amalgam.amalgams.Failure) → None

Pushes a Failure into the failures stack.

property unpacked_failures: Iterator[Tuple[Amalgam, Environment, str]]

Helper property for unpacking Failure s.