Lexical scope stack for Key to Value associations. More...

#include <tpl_scope.H>

Inheritance diagram for Aleph::Scope< Key, Value >:

Collaboration diagram for Aleph::Scope< Key, Value >:

Classes
struct	Binding
	Individual entry in a lexical frame. More...

struct	Frame

Public Member Functions
	Scope ()=default
	Default constructor.

size_t	depth () const noexcept
	Queries the current depth of the scope stack.

bool	empty () const noexcept
	Indicates if the structure is empty of frames.

void	clear () noexcept
	Resets the structure by removing all frames and bindings.

size_t	enter_scope ()
	Creates a new visibility level.

void	leave_scope ()
	Destroys the current visibility level and all its associations.

bool	insert (const Key &key, const Value &value)
	Registers a new association in the current scope.

bool	insert (Key &&key, Value &&value)
	Move version of `insert()`.

Value *	lookup_local (const Key &key) noexcept
	Searches for a key only in the innermost (current) scope.

const Value *	lookup_local (const Key &key) const noexcept
	Constant version of `lookup_local()`.

Value *	lookup (const Key &key) noexcept
	Searches for a key traversing all active scopes (from inside out).

const Value *	lookup (const Key &key) const noexcept
	Constant version of `lookup()`.

Private Member Functions
Frame &	current_frame ()

const Frame &	current_frame () const

Static Private Member Functions
static Value *	find_value (DynArray< Binding > &bindings, const Key &key) noexcept

static const Value *	find_value (const DynArray< Binding > &bindings, const Key &key) noexcept

Private Attributes
DynArray< Frame >	frames

Detailed Description

template<typename Key, typename Value>
requires std::equality_comparable<Key>
class Aleph::Scope< Key, Value >

Lexical scope stack for Key to Value associations.

The Scope class implements a hierarchical dictionary. It is ideal for symbol tables where declarations in inner blocks hide those from the outside.

Usage example:

Scope<string, Symbol*> symbols;
symbols.enter_scope(); // Enter global scope
symbols.insert("x", var1);
 
symbols.enter_scope(); // Enter a block { ... }
symbols.insert("x", var2); // Shadows global "x"
auto* s = symbols.lookup("x"); // Returns var2
 
symbols.leave_scope(); // Leave block
s = symbols.lookup("x"); // Returns var1

Template Parameters

Key	Search key type. Must be equality comparable.
Value	Payload associated with the key.

Note: Thread-safety: Not thread-safe for concurrent mutation operations. Const operations (lookup, depth, empty) are safe for concurrent readers only if there are no active mutations.; Complexity: O(1) for construction.

Definition at line 87 of file tpl_scope.H.

Constructor & Destructor Documentation

◆ Scope()

template<typename Key , typename Value >

Aleph::Scope< Key, Value >::Scope ( )

default

Default constructor.

Creates an instance without active frames.

enter_scope() must be called before performing the first insertion.

Member Function Documentation

◆ clear()

template<typename Key , typename Value >

void Aleph::Scope< Key, Value >::clear ( )

inlinenoexcept

Resets the structure by removing all frames and bindings.

Useful for reusing the Scope object in a new translation unit.

Definition at line 167 of file tpl_scope.H.

References Aleph::Scope< Key, Value >::frames.

Referenced by Aleph::Compiler_Symbol_Bindings::clear().

◆ current_frame() [1/2]

template<typename Key , typename Value >

Frame & Aleph::Scope< Key, Value >::current_frame ( )

inlineprivate

Definition at line 124 of file tpl_scope.H.

References ah_runtime_error_unless, and Aleph::Scope< Key, Value >::frames.

Referenced by Aleph::Scope< Key, Value >::insert(), and Aleph::Scope< Key, Value >::insert().

◆ current_frame() [2/2]

template<typename Key , typename Value >

const Frame & Aleph::Scope< Key, Value >::current_frame ( ) const

inlineprivate

Definition at line 130 of file tpl_scope.H.

References ah_runtime_error_unless, and Aleph::Scope< Key, Value >::frames.

◆ depth()

template<typename Key , typename Value >

size_t Aleph::Scope< Key, Value >::depth ( ) const

inlinenoexcept

Queries the current depth of the scope stack.

Returns: Number of active frames (scopes).

Note: A return of 0 indicates that nothing can be inserted until enter_scope() is called.

Definition at line 149 of file tpl_scope.H.

References Aleph::Scope< Key, Value >::frames.

Referenced by Aleph::Compiler_Symbol_Bindings::append_symbol(), Aleph::Compiler_Symbol_Bindings::declare(), and Aleph::Compiler_Symbol_Bindings::depth().

◆ empty()

template<typename Key , typename Value >

bool Aleph::Scope< Key, Value >::empty ( ) const

inlinenoexcept

Indicates if the structure is empty of frames.

Returns: true if there is no active scope.

Definition at line 158 of file tpl_scope.H.

References Aleph::Scope< Key, Value >::frames.

◆ enter_scope()

template<typename Key , typename Value >

size_t Aleph::Scope< Key, Value >::enter_scope ( )

inline

Creates a new visibility level.

Pushes an empty frame. All subsequent insert() calls will affect this frame until leave_scope() is called.

Returns: The new depth of the stack.

Definition at line 179 of file tpl_scope.H.

References Aleph::Scope< Key, Value >::frames.

Referenced by Aleph::Compiler_Symbol_Bindings::enter_scope(), TEST(), and TEST().

◆ find_value() [1/2]

template<typename Key , typename Value >

static const Value * Aleph::Scope< Key, Value >::find_value	(	const DynArray< Binding > &	bindings,
		const Key &	key
	)

inlinestaticprivatenoexcept

Definition at line 116 of file tpl_scope.H.

◆ find_value() [2/2]

template<typename Key , typename Value >

static Value * Aleph::Scope< Key, Value >::find_value	(	DynArray< Binding > &	bindings,
		const Key &	key
	)

inlinestaticprivatenoexcept

Definition at line 108 of file tpl_scope.H.

Referenced by Aleph::Scope< Key, Value >::insert(), Aleph::Scope< Key, Value >::insert(), Aleph::Scope< Key, Value >::lookup(), Aleph::Scope< Key, Value >::lookup(), Aleph::Scope< Key, Value >::lookup_local(), and Aleph::Scope< Key, Value >::lookup_local().

◆ insert() [1/2]

template<typename Key , typename Value >

bool Aleph::Scope< Key, Value >::insert	(	const Key &	key,
		const Value &	value
	)

inline

Registers a new association in the current scope.

The name is added to the innermost frame. If the name already exists in an outer frame, this method will "shadow" it without error. If it already exists in the current frame, the insertion will fail to prevent collisions.

Parameters

key	Key to register (e.g., variable name).
value	Value to associate (e.g., symbol metadata).

Returns: true if the insertion was successful, false if the key already exists in the current visibility level (redefinition forbidden).

Exceptions

std::runtime_error If there is no active scope.

Definition at line 215 of file tpl_scope.H.

References Aleph::Scope< Key, Value >::current_frame(), Aleph::Scope< Key, Value >::find_value(), and value.

Referenced by Aleph::Compiler_Symbol_Bindings::declare().

◆ insert() [2/2]

template<typename Key , typename Value >

bool Aleph::Scope< Key, Value >::insert	(	Key &&	key,
		Value &&	value
	)

inline

Move version of insert().

Avoids expensive copies of keys and values.

See also: insert(const Key&, const Value&)

Definition at line 229 of file tpl_scope.H.

References Aleph::Scope< Key, Value >::current_frame(), Aleph::Scope< Key, Value >::find_value(), and value.

◆ leave_scope()

template<typename Key , typename Value >

void Aleph::Scope< Key, Value >::leave_scope ( )

inline

Destroys the current visibility level and all its associations.

Restores the visibility of the previous (outer) frame.

Exceptions

std::runtime_error If called without active frames.

Note: Use this method when encountering a block closure (e.g., '}').

Definition at line 195 of file tpl_scope.H.

References ah_runtime_error_unless, Aleph::blossom_maximum_cardinality_matching(), and Aleph::Scope< Key, Value >::frames.

Referenced by Aleph::Compiler_Symbol_Bindings::leave_scope().

◆ lookup() [1/2]

template<typename Key , typename Value >

const Value * Aleph::Scope< Key, Value >::lookup ( const Key & key ) const

inlinenoexcept

Constant version of lookup().

Definition at line 280 of file tpl_scope.H.

References Aleph::Scope< Key, Value >::find_value(), Aleph::Scope< Key, Value >::frames, and value.

◆ lookup() [2/2]

template<typename Key , typename Value >

Value * Aleph::Scope< Key, Value >::lookup ( const Key & key )

inlinenoexcept

Searches for a key traversing all active scopes (from inside out).

Implements standard lexical lookup: searches first in the current frame, then in the immediately superior one, and so on until the global one. This allows name shadowing.

Parameters

key	Key to search.

Returns: Pointer to the nearest association value, or nullptr if the key is not defined in any accessible level.

Definition at line 271 of file tpl_scope.H.

References Aleph::Scope< Key, Value >::find_value(), Aleph::Scope< Key, Value >::frames, and value.

Referenced by Aleph::Compiler_Symbol_Bindings::declare(), and Aleph::Compiler_Symbol_Bindings::lookup().

◆ lookup_local() [1/2]

template<typename Key , typename Value >

const Value * Aleph::Scope< Key, Value >::lookup_local ( const Key & key ) const

inlinenoexcept

Constant version of lookup_local().

Definition at line 254 of file tpl_scope.H.

References Aleph::Scope< Key, Value >::find_value(), and Aleph::Scope< Key, Value >::frames.

◆ lookup_local() [2/2]

template<typename Key , typename Value >

Value * Aleph::Scope< Key, Value >::lookup_local ( const Key & key )

inlinenoexcept

Searches for a key only in the innermost (current) scope.

Useful for detecting redefinitions in the same code block without being affected by what happens in outer scopes.

Parameters

key	Key to search.

Returns: Pointer to the value if found, nullptr otherwise.

Definition at line 246 of file tpl_scope.H.

References Aleph::Scope< Key, Value >::find_value(), and Aleph::Scope< Key, Value >::frames.

Referenced by Aleph::Compiler_Symbol_Bindings::declare(), and Aleph::Compiler_Symbol_Bindings::lookup_local().

Member Data Documentation

◆ frames

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

tpl_scope.H

Classes

Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Usage example:

Constructor & Destructor Documentation

◆ Scope()

Member Function Documentation

◆ clear()

◆ current_frame() [1/2]

◆ current_frame() [2/2]

◆ depth()

◆ empty()

◆ enter_scope()

◆ find_value() [1/2]

◆ find_value() [2/2]

◆ insert() [1/2]

◆ insert() [2/2]

◆ leave_scope()

◆ lookup() [1/2]

◆ lookup() [2/2]

◆ lookup_local() [1/2]

◆ lookup_local() [2/2]

Member Data Documentation

◆ frames