Structured runtime for executing typed HIR. More...

#include <Interpreter_Runtime.H>

Collaboration diagram for Aleph::Interpreter_Runtime:

Classes
struct	Interpreter_Call_Frame

Public Member Functions
	Interpreter_Runtime (Diagnostic_Engine *dx=nullptr, const Interpreter_Runtime_Options &opts={}) noexcept
	Builds a fresh interpreter runtime.

void	set_diagnostics (Diagnostic_Engine *dx) noexcept
	Sets the optional diagnostic sink for runtime failures.

const Interpreter_Environment &	prelude_environment () const noexcept
	Returns the persistent prelude environment.

const Interpreter_Environment &	global_environment () const noexcept
	Returns the globals environment for the last evaluated module.

size_t	call_depth () const noexcept
	Returns the current call depth.

void	reset () noexcept
	Clears globals and the call stack while preserving host bindings.

bool	bind_host_function (const std::string &name, const Interpreter_Host_Function callback, void *user_data=nullptr)
	Defines one host function in the persistent prelude.

Interpreter_Execution_Result	evaluate_module (const Compiler_HIR_Module *module)
	Evaluates one HIR module and leaves its globals installed.

Interpreter_Execution_Result	call (const std::string &name, const DynArray< Interpreter_Value > &arguments)
	Calls one visible function by name.

Private Member Functions
Interpreter_Execution_Result	runtime_error (const Source_Span &span, const std::string &code, const std::string &message, const std::string &note="", const std::string &help="") const

Interpreter_Execution_Result	parse_integer_literal (const Compiler_HIR_Constant_Expr *node) const

Interpreter_Execution_Result	parse_string_literal (const Compiler_HIR_Constant_Expr *node) const

Interpreter_Execution_Result	parse_char_literal (const Compiler_HIR_Constant_Expr *node) const

Interpreter_Execution_Result	require_integer (const Interpreter_Value &value, const Source_Span &span, const std::string &context) const

Interpreter_Execution_Result	require_bool (const Interpreter_Value &value, const Source_Span &span, const std::string &context) const

Interpreter_Execution_Result	evaluate_expr (const Compiler_HIR_Expr *expr, Interpreter_Environment &env)

Interpreter_Execution_Result	evaluate_stmt (const Compiler_HIR_Stmt *stmt, Interpreter_Environment &env)

Interpreter_Execution_Result	call_hir_function (const Interpreter_Value &callee, const DynArray< Interpreter_Value > &arguments, const Source_Span &span)

Interpreter_Execution_Result	call_host_function (const Interpreter_Value &callee, const DynArray< Interpreter_Value > &arguments, const Source_Span &span) const

Interpreter_Execution_Result	call_value (const Interpreter_Value &callee, const DynArray< Interpreter_Value > &arguments, const Source_Span &span)

bool	install_module_function (const Compiler_HIR_Function *function)

Static Private Member Functions
static Interpreter_Execution_Result	ok (const Interpreter_Value &value=Interpreter_Value::make_unit())

static Interpreter_Execution_Result	control (const Interpreter_Control_Flow_Kind flow, const Interpreter_Value &value=Interpreter_Value::make_unit())

static bool	strip_quotes (std::string_view text, const char quote, std::string_view &body) noexcept

static bool	decode_escaped_text (const std::string_view body, std::string &out, std::string &error)

Private Attributes
Interpreter_Runtime_Options	options

Diagnostic_Engine *	diagnostics = nullptr

Interpreter_Environment	prelude

Interpreter_Environment	globals

DynArray< Interpreter_Call_Frame >	call_stack

Detailed Description

Structured runtime for executing typed HIR.

Host functions live in a persistent prelude environment, while user functions and top-level let bindings are installed in the globals environment for the last evaluated module.

Definition at line 734 of file Interpreter_Runtime.H.

Constructor & Destructor Documentation

◆ Interpreter_Runtime()

Aleph::Interpreter_Runtime::Interpreter_Runtime	(	Diagnostic_Engine *	dx = `nullptr`,
		const Interpreter_Runtime_Options &	opts = `{}`
	)

inlineexplicitnoexcept

Builds a fresh interpreter runtime.

Parameters

dx	Optional diagnostic sink for mirrored runtime errors.
opts	Runtime options such as maximum call depth.

Definition at line 1452 of file Interpreter_Runtime.H.

Member Function Documentation

◆ bind_host_function()

bool Aleph::Interpreter_Runtime::bind_host_function	(	const std::string &	name,
		const Interpreter_Host_Function	callback,
		void *	user_data = `nullptr`
	)

inline

Defines one host function in the persistent prelude.

Parameters

name	Host-visible callable name.
callback	Host callback.
user_data	Opaque embedding-owned pointer forwarded to `callback`.

Returns: false if name already exists in the prelude.

Definition at line 1496 of file Interpreter_Runtime.H.

References ah_runtime_error_unless, Aleph::blossom_maximum_cardinality_matching(), Aleph::Interpreter_Environment::define(), Aleph::Interpreter_Value::make_host_function(), and prelude.

Referenced by Aleph::Compiler_Driver::bind_host_function(), and Aleph::Compiler_Generic_Driver::bind_host_function().

◆ call()

Interpreter_Execution_Result Aleph::Interpreter_Runtime::call	(	const std::string &	name,
		const DynArray< Interpreter_Value > &	arguments
	)

inline

Calls one visible function by name.

The name is resolved first in globals, then in the persistent prelude.

Parameters

name	Function or host function name.
arguments	Positional arguments.

Returns: Structured call result.

Definition at line 1551 of file Interpreter_Runtime.H.

References call_value(), globals, Aleph::Interpreter_Environment::lookup(), prelude, runtime_error(), and value.

◆ call_depth()

size_t Aleph::Interpreter_Runtime::call_depth ( ) const

inlinenoexcept

Returns the current call depth.

Definition at line 1476 of file Interpreter_Runtime.H.

References call_stack.

◆ call_hir_function()

Interpreter_Execution_Result Aleph::Interpreter_Runtime::call_hir_function	(	const Interpreter_Value &	callee,
		const DynArray< Interpreter_Value > &	arguments,
		const Source_Span &	span
	)

inlineprivate

◆ call_host_function()

Interpreter_Execution_Result Aleph::Interpreter_Runtime::call_host_function	(	const Interpreter_Value &	callee,
		const DynArray< Interpreter_Value > &	arguments,
		const Source_Span &	span
	)		const

inlineprivate

Definition at line 1401 of file Interpreter_Runtime.H.

References Aleph::Interpreter_Value::callable_name, Aleph::code(), Aleph::error(), Aleph::Interpreter_Value::host_function, Aleph::Interpreter_Value::host_user_data, Aleph::Interpreter_Value::make_invalid(), Aleph::message(), ok(), and runtime_error().

Referenced by call_value().

◆ call_value()

Interpreter_Execution_Result Aleph::Interpreter_Runtime::call_value	(	const Interpreter_Value &	callee,
		const DynArray< Interpreter_Value > &	arguments,
		const Source_Span &	span
	)

inlineprivate

Definition at line 1419 of file Interpreter_Runtime.H.

References call_hir_function(), call_host_function(), Aleph::Function, Aleph::Host_Function, Aleph::interpreter_value_kind_name(), Aleph::Interpreter_Value::kind, and runtime_error().

Referenced by call(), and evaluate_expr().

◆ control()

static Interpreter_Execution_Result Aleph::Interpreter_Runtime::control	(	const Interpreter_Control_Flow_Kind	flow,
		const Interpreter_Value &	value = `Interpreter_Value::make_unit()`
	)

inlinestaticprivate

Definition at line 757 of file Interpreter_Runtime.H.

References Aleph::Interpreter_Execution_Result::flow, value, and Aleph::Interpreter_Execution_Result::value.

Referenced by evaluate_stmt().

◆ decode_escaped_text()

static bool Aleph::Interpreter_Runtime::decode_escaped_text	(	const std::string_view	body,
		std::string &	out,
		std::string &	error
	)

inlinestaticprivate

Definition at line 800 of file Interpreter_Runtime.H.

References Aleph::blossom_maximum_cardinality_matching(), Aleph::error(), and out.

Referenced by parse_char_literal(), and parse_string_literal().

◆ evaluate_expr()

Interpreter_Execution_Result Aleph::Interpreter_Runtime::evaluate_expr	(	const Compiler_HIR_Expr *	expr,
		Interpreter_Environment &	env
	)

inlineprivate

Definition at line 931 of file Interpreter_Runtime.H.

References Aleph::Amp, Aleph::and, Aleph::AndAnd, Aleph::DynArray< T >::append(), Aleph::Assign, Aleph::Bang, Aleph::Binary, Aleph::blossom_maximum_cardinality_matching(), Aleph::Bool, Aleph::Call, call_value(), Aleph::Caret, Aleph::Character, Aleph::compiler_operator_is_compound_assignment(), Aleph::compiler_operator_name(), Aleph::Constant, Aleph::EqEq, evaluate_expr(), Aleph::Greater, Aleph::GreaterEq, Aleph::Integer, Aleph::interpreter_values_equal(), Aleph::Invalid, Aleph::Compiler_HIR_Expr::kind, Aleph::Less, Aleph::LessEq, Aleph::Interpreter_Value::make_bool(), Aleph::Interpreter_Value::make_integer(), Aleph::Interpreter_Value::make_unit(), Aleph::Minus, Aleph::MinusEq, Aleph::NotEq, ok(), Aleph::OrOr, parse_char_literal(), parse_integer_literal(), parse_string_literal(), Aleph::Percent, Aleph::PercentEq, Aleph::Pipe, Aleph::Plus, Aleph::PlusEq, require_bool(), require_integer(), runtime_error(), Aleph::Slash, Aleph::SlashEq, Aleph::Compiler_HIR_Node::span, Aleph::Star, Aleph::StarEq, Aleph::String, Aleph::Unary, Aleph::Unit, value, and Aleph::Variable.

Referenced by evaluate_expr(), and evaluate_stmt().

◆ evaluate_module()

Interpreter_Execution_Result Aleph::Interpreter_Runtime::evaluate_module ( const Compiler_HIR_Module * module )

inline

Evaluates one HIR module and leaves its globals installed.

Function declarations are installed first to support recursion and mutual recursion. Top-level statements are then evaluated in order.

Parameters

module HIR module to evaluate.

Returns: Structured runtime result for the module evaluation.

Definition at line 1513 of file Interpreter_Runtime.H.

References Aleph::blossom_maximum_cardinality_matching(), Aleph::Break, Aleph::Continue, evaluate_stmt(), Aleph::Compiler_HIR_Module::functions, globals, install_module_function(), ok(), reset(), Aleph::Return, Aleph::Runtime_Error, runtime_error(), and Aleph::Compiler_HIR_Module::statements.

Referenced by Aleph::Compiler_Driver::execute_hir_runtime(), and Aleph::Compiler_Generic_Driver::execute_hir_runtime().

◆ evaluate_stmt()

Interpreter_Execution_Result Aleph::Interpreter_Runtime::evaluate_stmt	(	const Compiler_HIR_Stmt *	stmt,
		Interpreter_Environment &	env
	)

inlineprivate

Definition at line 1244 of file Interpreter_Runtime.H.

References Aleph::Block, Aleph::blossom_maximum_cardinality_matching(), Aleph::Break, Aleph::Continue, control(), Aleph::Eval, evaluate_expr(), evaluate_stmt(), Aleph::If, Aleph::init, Aleph::Invalid, Aleph::Compiler_HIR_Stmt::kind, Aleph::Let, Aleph::Interpreter_Value::make_unit(), Aleph::None, ok(), require_bool(), Aleph::Return, Aleph::Runtime_Error, runtime_error(), Aleph::Compiler_HIR_Node::span, value, and Aleph::While.

Referenced by call_hir_function(), evaluate_module(), and evaluate_stmt().

◆ global_environment()

const Interpreter_Environment & Aleph::Interpreter_Runtime::global_environment ( ) const

inlinenoexcept

Returns the globals environment for the last evaluated module.

Definition at line 1470 of file Interpreter_Runtime.H.

References globals.

◆ install_module_function()

bool Aleph::Interpreter_Runtime::install_module_function ( const Compiler_HIR_Function * function )

inlineprivate

Definition at line 1439 of file Interpreter_Runtime.H.

References Aleph::Interpreter_Environment::define(), globals, Aleph::Interpreter_Value::make_function(), and Aleph::Compiler_HIR_Function::name.

Referenced by evaluate_module().

◆ ok()

static Interpreter_Execution_Result Aleph::Interpreter_Runtime::ok ( const Interpreter_Value & value = Interpreter_Value::make_unit() )

inlinestaticprivate

Definition at line 748 of file Interpreter_Runtime.H.

References Aleph::Interpreter_Execution_Result::flow, Aleph::None, value, and Aleph::Interpreter_Execution_Result::value.

Referenced by call_hir_function(), call_host_function(), evaluate_expr(), evaluate_module(), evaluate_stmt(), parse_char_literal(), parse_integer_literal(), parse_string_literal(), require_bool(), and require_integer().

◆ parse_char_literal()

Interpreter_Execution_Result Aleph::Interpreter_Runtime::parse_char_literal ( const Compiler_HIR_Constant_Expr * node ) const

inlineprivate

Definition at line 887 of file Interpreter_Runtime.H.

References Aleph::blossom_maximum_cardinality_matching(), decode_escaped_text(), Aleph::Interpreter_Value::make_character(), ok(), runtime_error(), Aleph::Compiler_HIR_Node::span, strip_quotes(), and Aleph::Compiler_HIR_Constant_Expr::text.

Referenced by evaluate_expr().

◆ parse_integer_literal()

Interpreter_Execution_Result Aleph::Interpreter_Runtime::parse_integer_literal ( const Compiler_HIR_Constant_Expr * node ) const

inlineprivate

Definition at line 852 of file Interpreter_Runtime.H.

References Aleph::blossom_maximum_cardinality_matching(), Aleph::Interpreter_Value::make_integer(), ok(), runtime_error(), Aleph::Compiler_HIR_Node::span, Aleph::Compiler_HIR_Constant_Expr::text, and value.

Referenced by evaluate_expr().

◆ parse_string_literal()

Interpreter_Execution_Result Aleph::Interpreter_Runtime::parse_string_literal ( const Compiler_HIR_Constant_Expr * node ) const

inlineprivate

Definition at line 874 of file Interpreter_Runtime.H.

References Aleph::blossom_maximum_cardinality_matching(), decode_escaped_text(), Aleph::Interpreter_Value::make_string(), ok(), runtime_error(), Aleph::Compiler_HIR_Node::span, strip_quotes(), and Aleph::Compiler_HIR_Constant_Expr::text.

Referenced by evaluate_expr().

◆ prelude_environment()

const Interpreter_Environment & Aleph::Interpreter_Runtime::prelude_environment ( ) const

inlinenoexcept

Returns the persistent prelude environment.

Definition at line 1464 of file Interpreter_Runtime.H.

References prelude.

◆ require_bool()

Interpreter_Execution_Result Aleph::Interpreter_Runtime::require_bool	(	const Interpreter_Value &	value,
		const Source_Span &	span,
		const std::string &	context
	)		const

inlineprivate

Definition at line 918 of file Interpreter_Runtime.H.

References Aleph::Bool, Aleph::interpreter_value_kind_name(), ok(), runtime_error(), and value.

Referenced by evaluate_expr(), and evaluate_stmt().

◆ require_integer()

Interpreter_Execution_Result Aleph::Interpreter_Runtime::require_integer	(	const Interpreter_Value &	value,
		const Source_Span &	span,
		const std::string &	context
	)		const

inlineprivate

Definition at line 905 of file Interpreter_Runtime.H.

References Aleph::Integer, Aleph::interpreter_value_kind_name(), ok(), runtime_error(), and value.

Referenced by evaluate_expr().

◆ reset()

void Aleph::Interpreter_Runtime::reset ( )

inlinenoexcept

Clears globals and the call stack while preserving host bindings.

Definition at line 1482 of file Interpreter_Runtime.H.

References call_stack, Aleph::Interpreter_Environment::clear(), globals, prelude, and Aleph::Interpreter_Environment::set_parent().

Referenced by Aleph::Compiler_Driver::clear(), Aleph::Compiler_Generic_Driver::clear(), and evaluate_module().

◆ runtime_error()

Interpreter_Execution_Result Aleph::Interpreter_Runtime::runtime_error	(	const Source_Span &	span,
		const std::string &	code,
		const std::string &	message,
		const std::string &	note = `""`,
		const std::string &	help = `""`
	)		const

inlineprivate

◆ set_diagnostics()

void Aleph::Interpreter_Runtime::set_diagnostics ( Diagnostic_Engine * dx )

inlinenoexcept

Sets the optional diagnostic sink for runtime failures.

Definition at line 1458 of file Interpreter_Runtime.H.

References diagnostics.

Referenced by Aleph::Compiler_Driver::clear(), and Aleph::Compiler_Generic_Driver::clear().

◆ strip_quotes()

static bool Aleph::Interpreter_Runtime::strip_quotes	(	std::string_view	text,
		const char	quote,
		std::string_view &	body
	)

inlinestaticprivatenoexcept

Definition at line 790 of file Interpreter_Runtime.H.

References Aleph::blossom_maximum_cardinality_matching().

Referenced by parse_char_literal(), and parse_string_literal().

Member Data Documentation

◆ call_stack

DynArray<Interpreter_Call_Frame> Aleph::Interpreter_Runtime::call_stack

private

Definition at line 746 of file Interpreter_Runtime.H.

Referenced by call_depth(), call_hir_function(), and reset().

◆ diagnostics

Diagnostic_Engine* Aleph::Interpreter_Runtime::diagnostics = nullptr

private

Definition at line 743 of file Interpreter_Runtime.H.

Referenced by runtime_error(), and set_diagnostics().

◆ globals

Interpreter_Environment Aleph::Interpreter_Runtime::globals

private

Definition at line 745 of file Interpreter_Runtime.H.

Referenced by call(), call_hir_function(), evaluate_module(), global_environment(), install_module_function(), and reset().

◆ options

Interpreter_Runtime_Options Aleph::Interpreter_Runtime::options

private

Definition at line 742 of file Interpreter_Runtime.H.

Referenced by call_hir_function().

◆ prelude

Interpreter_Environment Aleph::Interpreter_Runtime::prelude

private

Definition at line 744 of file Interpreter_Runtime.H.

Referenced by bind_host_function(), call(), prelude_environment(), and reset().

The documentation for this class was generated from the following file:

Interpreter_Runtime.H

Classes

Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Interpreter_Runtime()

Member Function Documentation

◆ bind_host_function()

◆ call()

◆ call_depth()

◆ call_hir_function()

◆ call_host_function()

◆ call_value()

◆ control()

◆ decode_escaped_text()

◆ evaluate_expr()

◆ evaluate_module()

◆ evaluate_stmt()

◆ global_environment()

◆ install_module_function()

◆ ok()

◆ parse_char_literal()

◆ parse_integer_literal()

◆ parse_string_literal()

◆ prelude_environment()

◆ require_bool()

◆ require_integer()

◆ reset()

◆ runtime_error()

◆ set_diagnostics()

◆ strip_quotes()

Member Data Documentation

◆ call_stack

◆ diagnostics

◆ globals

◆ options

◆ prelude