symbol.c File Reference

Interned symbol type – BST index, make, find, and 3-step eval. More...

#include "x-type/symbol.h"
#include "x-type/str.h"
#include "x-alist.h"
#include "x-eval.h"
#include "x-env.h"
#include "x-token/sexp/symbol.h"

Functions
x_obj_t *	x_make_symbol (x_obj_t *p_base, x_obj_flag_t flags, x_char_t *s)
x_obj_t *	x_type_symbol_save (x_obj_t *p_base, x_obj_t *p_args)
x_obj_t *	x_type_symbol_struct (x_obj_t *p_base, x_obj_t *p_obj)
x_obj_t *	x_type_symbol_register (x_obj_t *p_base, x_obj_t *p_args)
x_obj_t *	x_type_symbol_make (x_obj_t *p_base, x_obj_t *p_args)
x_obj_t *	x_type_symbol_find (x_obj_t *p_base, x_obj_t *p_args)
x_obj_t *	x_type_symbol_eval (x_obj_t *p_base, x_obj_t *p_args)

Variables
x_satom_t	x_type_symbol_name = x_obj_set(x_type_atom_obj, X_OBJ_FLAG_NONE, { .s = (x_char_t *)X_TYPE_SYMBOL_NAME })
x_satom_t	x_type_symbol_make_prim = x_obj_set(x_type_atom_obj, X_OBJ_FLAG_NONE, { (x_obj_t *)&x_type_symbol_make })
x_satom_t	x_type_symbol_eval_prim = x_obj_set(x_type_atom_obj, X_OBJ_FLAG_NONE, { (x_obj_t *)&x_type_symbol_eval })
x_satom_t	x_type_symbol_struct_prim = x_obj_set(x_type_atom_obj, X_OBJ_FLAG_NONE, { (x_obj_t *)&x_type_symbol_struct })
x_satom_t	x_type_symbol_save_prim = x_obj_set(x_type_atom_obj, X_OBJ_FLAG_NONE, { (x_obj_t *)&x_type_symbol_save })

Symbol Intern BST
Index for O(log n) symbol lookup by name. Node layout: (symbol . (left . right)), keyed by x_symbolval. Stored in x_restobj(x_symbol_data(p_type)).
#define	x_symbol_bst(T)   x_restobj(x_symbol_data((T)))
static x_obj_t *	sym_bst_lookup (x_obj_t *p_base, x_obj_t *p_tree, x_char_t *name)
static x_obj_t *	sym_bst_insert (x_obj_t *p_base, x_obj_t *p_tree, x_obj_t *p_sym)

Detailed Description

Interned symbol type – BST index, make, find, and 3-step eval.

Author

Jon Ruttan (jonru.nosp@m.ttan.nosp@m.@gmai.nosp@m.l.co.nosp@m.m)

Copyright

2021 Jon Ruttan @license MIT No Attribution (MIT-0)

Macro Definition Documentation

x_symbol_bst

#define x_symbol_bst

(

T

)

x_restobj(x_symbol_data((T)))

Function Documentation

sym_bst_insert()

static x_obj_t * sym_bst_insert ( x_obj_t *  p_base, x_obj_t *  p_tree, x_obj_t *  p_sym  )

static

Insert a symbol into the BST, returning the (possibly unchanged) root.

If the symbol already exists, the tree is returned unmodified.

Parameters

p_base	Base (execution context) (for allocation).
p_tree	Current BST root (or NULL for empty tree).
p_sym	Symbol object to insert.

Returns

BST root after insertion.

sym_bst_lookup()

static x_obj_t * sym_bst_lookup ( x_obj_t *  p_base, x_obj_t *  p_tree, x_char_t *  name  )

static

Search the BST for a node whose symbol matches name.

Parameters

p_base	Base (execution context).
p_tree	BST root node (or NULL).
name	Symbol name to find.

Returns

BST node containing the symbol, or NULL if not found.

x_make_symbol()

x_obj_t * x_make_symbol	(	x_obj_t *	p_base,
		x_obj_flag_t	flags,
		x_char_t *	s
	)

Allocate (or retrieve interned) SYMBOL for string s.

Packs the string and flags into stack-allocated args and delegates to x_type_symbol_make(), which handles interning.

Parameters

p_base	Base (execution context).
flags	Object flags (e.g. X_OBJ_FLAG_OWN).
s	Null-terminated symbol name.

Returns

Interned SYMBOL object.

x_type_symbol_eval()

x_obj_t * x_type_symbol_eval	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Evaluate a symbol: the value bound to it in the current environment or an ancestor.

The environment is a chain of (bindings . parent) pairs ending at the root, whose bindings are a tree; x_env_lookup walks it. An unbound symbol is an error naming the symbol.

Parameters

p_base	x_obj_t* – Base (execution context)
p_args	x_obj_t* – Eval args: (symbol . env)

Returns

The bound value, or NULL on error.

See also

x_env_lookup

x_type_symbol_find()

x_obj_t * x_type_symbol_find	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Look up an interned symbol by name using the BST index.

Parameters

p_base	Base (execution context).
p_args	Argument list whose first element wraps the name string.

Returns

BST node containing the symbol, or NULL if not interned.

x_type_symbol_make()

x_obj_t * x_type_symbol_make	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Type-system make handler – intern or allocate a new SYMBOL.

If a symbol with the same name already exists, returns the existing interned object. Otherwise allocates a new one, appends it to the intern list, and inserts it into the BST. Ownership of the source string is transferred when the source has X_OBJ_FLAG_OWN set.

Interning sequence:

1. Calls x_type_symbol_find which does a BST lookup (O(log n)) on the type's intern BST. If the symbol already exists, the existing heap-allocated symbol object is returned immediately – no allocation.
2. On miss, allocates a new symbol atom via x_obj_make, prepends it to the linear intern list (x_symbol_data_list), and inserts it into the intern BST (x_symbol_bst) for future lookups.
3. String ownership: if the source atom has X_OBJ_FLAG_OWN, that flag is transferred to the new symbol and cleared on the source, ensuring exactly one owner for the malloc'd string.

Parameters

p_base	Base (execution context).
p_args	Argument list: (name-atom [flags-atom]).

Returns

Interned SYMBOL object.

Note

TODO: allow the symbol list to be optionally supplied by argument.

See also

x_type_symbol_find for the BST lookup path

sym_bst_insert for the intern BST insertion (mutating, not path-copying)

x_type_symbol_register()

x_obj_t * x_type_symbol_register	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Register (or retrieve) the SYMBOL type and initialize its data field.

On first call, allocates the intern list and BST root in the type's data slot.

Parameters

p_base	Base (execution context).
p_args	Unused.

Returns

The registered SYMBOL type object.

x_type_symbol_save()

x_obj_t * x_type_symbol_save	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Build the SYMBOL type struct descriptor.

Populates name, make, eval, analyse, read, write, and display hooks.

Parameters

p_base	Base (execution context).
p_obj	Unused.

Returns

Type struct pair-tree for SYMBOL.

x_type_symbol_struct()

x_obj_t * x_type_symbol_struct	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Build the SYMBOL type struct descriptor.

Variable Documentation

x_type_symbol_eval_prim

x_satom_t x_type_symbol_eval_prim = x_obj_set(x_type_atom_obj, X_OBJ_FLAG_NONE, { (x_obj_t *)&x_type_symbol_eval })

x_type_symbol_make_prim

x_satom_t x_type_symbol_make_prim = x_obj_set(x_type_atom_obj, X_OBJ_FLAG_NONE, { (x_obj_t *)&x_type_symbol_make })

x_type_symbol_name

x_satom_t x_type_symbol_name = x_obj_set(x_type_atom_obj, X_OBJ_FLAG_NONE, { .s = (x_char_t *)X_TYPE_SYMBOL_NAME })

x_type_symbol_save_prim

x_satom_t x_type_symbol_save_prim = x_obj_set(x_type_atom_obj, X_OBJ_FLAG_NONE, { (x_obj_t *)&x_type_symbol_save })

x_type_symbol_struct_prim

x_satom_t x_type_symbol_struct_prim = x_obj_set(x_type_atom_obj, X_OBJ_FLAG_NONE, { (x_obj_t *)&x_type_symbol_struct })