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.Located

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

property column

The starting column number of a node.

property end_column

The ending column number of a node.

property end_line

The ending line number of a node.

property line

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__().

bind(environment: Environment) → Amalgam

Protocol for implementing environment binding for Function.

This base implementation is responsible for allowing bind to be called on other Amalgam subclasses by performing no operation aside from returning self.

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

Protocol for implementing function calls for Function.

This base implementation is responsible for making the type signature of SExpression.func to properly type check when SExpression.evaluate() is called, as well as returning a fatal Notification for non-callable types.

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: 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

The rest of the SExpression.vals.

property func

The head of the SExpression.vals.

class amalgam.amalgams.Vector(*vals: 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: 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.Internal(value: P)

An Amalgam that holds Python object s.

Parameterized as a Generic by: P = TypeVar("P", bound=object)

value

The Python object being wrapped.

Type

P

evaluate(_environment: Environment) → Internal

Evaluates to the same Internal reference.

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

Encapsulates information for tracking notifications.

property amalgam

Alias for field number 0

property environment

Alias for field number 1

property message

Alias for field number 2

class amalgam.amalgams.Notification(*, fatal: bool = True, payload: amalgam.amalgams.Amalgam = <Atom 'NIL' @ 0x7f42075dd810>)

An Amalgam that encapsulates and tracks notifications.

fatal

Specifies whether the notification should unconditionally propagate and halt evaluation.

Type

bool

payload

An optional payload to be carried by a notification.

Type

Amalgam

trace

A stack of Trace objects that tell how the notification propagated.

Type

List[Trace]

evaluate(_environment: Environment) → Notification

Evaluates to the same Notification reference.

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

Generates a report to be printed to sys.stderr.

Accepts text and source for prettified output.

pop() → amalgam.amalgams.Trace

Pops a Trace from Notification.trace.

push(amalgam: Amalgam, environment: Environment, message: str) → None

Pushes a Trace into Notification.trace.