Types¶

KSP Type System

Import¶

import "_IVLS/std-library/ksp/types.ksp"

Overview¶

KSP Type System

LIBRARY MODULE

Compile-time object system for IVLS using macro-generated memory pool management.

type.Create / type.CreateCustomPool — allocate pool and generate field accessors
type.Functions — generate CRUD operations (new, copy, delete, init, repr, etc.)
type.Locals / type.RawLocals and fill-back variants — local variable helpers
type.CheckRef / type.CheckMethodRef — reference validation guards
All field access goes through generated properties (e.g. MyType[ref].field_name)

API¶

Defines¶

Name	Description
`define check_ref(#type#, #ref#)`	Validates that an object reference is non-null and currently allocated.
`define TYPE.MEM_CLEAR`	Sentinel value written to deallocated object fields by clear_mem().

Const Blocks¶

Name	Description
`const #type#.field`	Auto-enumerated field index constants for #type#.

Properties¶

Name	Description
`property #type#.#field#`	Named field accessor for #field# on #type# objects.
`property #type#.access`	Raw indexed access to an object's fields by field index.

Macros¶

Name	Description
`store_literal_name(#array#, #n#, #l#)`	Stores stringified field name into array at given index.
`type.CheckMethodRef(#type#, #method#, #ref#)`	Asserts that an object reference is valid, including method name in failure mess...
`type.CheckRef(#type#, #ref#)`	Asserts that an object reference is valid, triggering assertion failure if not.
`type.Create(#type#)`	Creates a type with the default pool size (524288 integers).
`type.CreateCustomPool(#type#, #pool#)`	Generates complete type infrastructure with a custom pool size.
`type.FillLocals(#type#, #ref#)`	Refreshes type-prefixed local variables from object fields without re-declaring ...
`type.FillObj(#type#, #ref#)`	Writes type-prefixed local variables back to object fields.
`type.FillRawLocals(#type#, #ref#)`	Refreshes unprefixed local variables from object fields without re-declaring the...
`type.FillRawObj(#type#, #ref#)`	Writes unprefixed local variables back to object fields.
`type.Functions(#type#)`	Generates all CRUD and utility functions for a type.
`type.Locals(#type#, #ref#)`	Declares type-prefixed local variables for all fields, initialized from an objec...
`type.RawLocals(#type#, #ref#)`	Declares unprefixed local variables for all type fields, initialized from an obj...

Functions¶

Name	Description
`#type#.clear_mem(address)`	Fills all object fields with TYPE.MEM_CLEAR sentinel value.
`#type#.clear_pool()`	Deletes all allocated objects in the pool.
`#type#.copy(src) -> result`	Creates a new object as a copy of an existing object.
`#type#.copy_a_to_b(a_ref, b_ref)`	Copies all fields from source object to destination object with validation.
`#type#.copy_a_to_b.unsafe(a_ref, b_ref)`	Copies all fields from source to destination without validation.
`#type#.delete(ref)`	Deallocates an object and returns it to the free pool.
`#type#.empty_fields(address)`	Fills all object fields with -1.
`#type#.init(address)`	Initializes all object fields from INIT array.
`#type#.new() -> result`	Allocates a new object with default field initialization.
`#type#.new_copy() -> result`	Allocates a new object without field initialization.
`#type#.print(ref)`	Prints object representation to message area.
`#type#.repr(ref) -> result`	Generates string representation of object fields.

Defines¶

`define check_ref(#type#, #ref#)`¶

Validates that an object reference is non-null and currently allocated.

Parameter	Description
`#type#`	Type name
`#ref#`	Reference to validate

Post: (int) result - 1 if reference is valid, 0 otherwise

Notes: Safe to use with null or out-of-bounds references. Used internally by delete() and copy operations.

`define TYPE.MEM_CLEAR`¶

Sentinel value written to deallocated object fields by clear_mem().

Post: (int) TYPE.MEM_CLEAR - Sentinel value -123547689

Const Blocks¶

`const #type#.field`¶

Auto-enumerated field index constants for #type#.

Properties¶

`property #type#.#field#`¶

Named field accessor for #field# on #type# objects.

`property #type#.access`¶

Raw indexed access to an object's fields by field index.

Macros¶

`store_literal_name(#array#, #n#, #l#)`¶

Stores stringified field name into array at given index.

Parameter	Description
`#array#`	Target string array
`#n#`	Index to write to
`#l#`	Literal field name to stringify

Side effects:

Assigns stringified #l# to #array#[#n#]

`type.CheckMethodRef(#type#, #method#, #ref#)`¶

Asserts that an object reference is valid, including method name in failure messages.

Parameter	Description
`#type#`	Type name
`#method#`	Method name to include in error messages
`#ref#`	Reference to validate

Side effects:

Operations

Calls assert_fail() with method name if reference is -1 (null pointer)
Calls assert_fail() with method name if reference is dangling (not allocated)

function MyType.calculate(ref)
    type.CheckMethodRef(MyType, calculate, ref)
    // Safe to access MyType[ref] here
end function

See also: type.CheckRef, check_ref

`type.CheckRef(#type#, #ref#)`¶

Asserts that an object reference is valid, triggering assertion failure if not.

Parameter	Description
`#type#`	Type name
`#ref#`	Reference to validate

Side effects:

Operations

Calls assert_fail() if reference is -1 (null pointer)
Calls assert_fail() if reference is dangling (not allocated)

function MyType.some_method(ref)
    type.CheckRef(MyType, ref)
    // Safe to access MyType[ref] here
end function

See also: type.CheckMethodRef, check_ref

`type.Create(#type#)`¶

Creates a type with the default pool size (524288 integers).

Parameter	Description
`#type#`	Type name to create

Side effects:

Expands to type.CreateCustomPool(#type#, 524288)

See also: type.CreateCustomPool

`type.CreateCustomPool(#type#, #pool#)`¶

Generates complete type infrastructure with a custom pool size.

Preconditions:

User must define #type#.MEMBERS (field list)
User must define #type#.INIT[] (default values array)
User must define function #type#.def() (custom initialization hook, can be empty)

Parameter	Description
`#type#`	Type name to create
`#pool#`	Pool size in integers (will be adjusted down to multiple of block size)

Side effects:

Declarations

Name	Type	Purpose
#type#.field	const block	Enumerated field indices (auto-generated from MEMBERS)
#type#.BLOCK	const	Number of fields per object
#type#.POOL_SIZE	const	Adjusted pool size (multiple of BLOCK)
#type#.pool[]	int array	Memory pool for all objects
#type#.is_alloc[]	int array	Allocation status (1 = allocated, 0 = free)
#type#.count	int	Current number of allocated objects
type.#type#.iterator	int	Iterator variable for pool operations
@#type#.to_string	string	Temporary string for repr/print operations
!#type#.field_names[]	string array	Field names for debugging/repr
#type#.Blocks	queue	Free block queue (via adt.CreateQueue)
#type#.access	property	Raw field access by index
#type#.#field#	property	Named field access (one per member)

Operations

Increments lib_mem by pool size
Calls #type#.def() user hook
Calls lib.MakeRamReport for RAM tracking
Initializes pool: sets count to 0, clears allocation tracker, fills free block queue
Optionally prints memory allocation message if use_ram_report is TRUE

Notes: Pool access patterns: #type#[ref].access[field_idx] for raw index, #type#[ref].field_name for named field.

See also: type.Create, type.Functions

`type.FillLocals(#type#, #ref#)`¶

Refreshes type-prefixed local variables from object fields without re-declaring them.

Parameter	Description
`#type#`	Type name
`#ref#`	Object reference to read from

Side effects:

Operations

Assigns all prefixed local variables (#type#.#field#) from corresponding object fields

See also: type.Locals, type.FillObj

`type.FillObj(#type#, #ref#)`¶

Writes type-prefixed local variables back to object fields.

Parameter	Description
`#type#`	Type name
`#ref#`	Object reference to write to

Side effects:

Operations

Writes all prefixed local variables (#type#.#field#) to corresponding object fields

See also: type.Locals, type.FillLocals

`type.FillRawLocals(#type#, #ref#)`¶

Refreshes unprefixed local variables from object fields without re-declaring them.

Parameter	Description
`#type#`	Type name
`#ref#`	Object reference to read from

Side effects:

Operations

Assigns all unprefixed local variables (#field#) from corresponding object fields

See also: type.RawLocals, type.FillRawObj

`type.FillRawObj(#type#, #ref#)`¶

Writes unprefixed local variables back to object fields.

Parameter	Description
`#type#`	Type name
`#ref#`	Object reference to write to

Side effects:

Operations

Writes all unprefixed local variables (#field#) to corresponding object fields

See also: type.RawLocals, type.FillRawLocals

`type.Functions(#type#)`¶

Generates all CRUD and utility functions for a type.

Parameter	Description
`#type#`	Type name to generate functions for

Side effects:

Declarations

All generated functions are inlined.

Name	Purpose
#type#.Constructor(ref)	Post-allocation hook (empty, override to customize)
#type#.CopyConstructor(ref)	Post-copy hook (empty, override to customize)
#type#.Destructor(ref)	Pre-deallocation hook (empty, override to customize)
#type#.new() -> result	Allocate new object with default initialization
#type#.new_copy() -> result	Allocate new object without field initialization
#type#.copy(src) -> result	Create new object as copy of src
#type#.delete(ref)	Deallocate object and set ref to -1
#type#.copy_a_to_b(a_ref, b_ref)	Copy fields from a to b with validation
#type#.copy_a_to_b.unsafe(a_ref, b_ref)	Copy fields without validation
#type#.init(address)	Initialize fields from INIT array
#type#.clear_mem(address)	Fill fields with TYPE.MEM_CLEAR sentinel
#type#.empty_fields(address)	Fill fields with -1
#type#.print(ref)	Print object representation to message area
#type#.repr(ref) -> result	Generate string representation
#type#.clear_pool()	Delete all allocated objects

Operations

Calls adt.QueueFunctions(#type#.Blocks) to generate queue operations

Notes: All functions are inlined. delete() modifies the caller's ref variable (sets to -1) as a consequence of inlining. copy_a_to_b() declares a local fail variable in caller's scope.

See also: type.CreateCustomPool

`type.Locals(#type#, #ref#)`¶

Declares type-prefixed local variables for all fields, initialized from an object.

Parameter	Description
`#type#`	Type name
`#ref#`	Object reference to read from

Side effects: Declarations

Declares one local variable per field: #type#.#field# initialized from object field value.

declare obj := MyType.new()
MyType[obj].x := 100
type.Locals(MyType, obj)  // Declares MyType.x := 100, MyType.y := ..., etc.
MyType.x := 200
type.FillObj(MyType, obj)  // Writes MyType.x back to obj

See also: type.FillLocals, type.FillObj, type.RawLocals

`type.RawLocals(#type#, #ref#)`¶

Declares unprefixed local variables for all type fields, initialized from an object.

Parameter	Description
`#type#`	Type name
`#ref#`	Object reference to read from

Side effects: Declarations

Declares one local variable per field: #field# (no type prefix) initialized from object field value.

Notes: Higher risk of variable name collisions compared to type.Locals(). Use when type prefix is not needed or when field names are known to be unique in scope.

See also: type.FillRawLocals, type.FillRawObj, type.Locals

Functions¶

`#type#.clear_mem(address)`¶

Fills all object fields with TYPE.MEM_CLEAR sentinel value.

Parameter	Type	Description
`address`	int	Object reference to clear

Side effects:

Writes TYPE.MEM_CLEAR to all fields via pool access
Declares local variable i in caller's scope

`#type#.clear_pool()`¶

Deletes all allocated objects in the pool.

Side effects:

Calls #type#.delete() on all allocated objects
Resets #type#.count to 0
Returns all blocks to free queue

`#type#.copy(src) -> result`¶

Creates a new object as a copy of an existing object.

Parameter	Type	Description
`src`	int	Reference to source object to copy

Returns: result — Reference to new copied object, or -1 if pool exhausted

Side effects:

Calls #type#.new_copy() (allocates object)
Calls #type#.copy_a_to_b() (copies fields)
Calls #type#.CopyConstructor() hook

`#type#.copy_a_to_b(a_ref, b_ref)`¶

Copies all fields from source object to destination object with validation.

Parameter	Type	Description
`a_ref`	int	Source object reference
`b_ref`	int	Destination object reference

Side effects:

Declares local variable fail in caller's scope
Calls copy_a_to_b.unsafe() if validation passes
Prints error message if either reference is invalid

Notes: Declares a fail variable in caller's scope which may collide with existing variables.

`#type#.copy_a_to_b.unsafe(a_ref, b_ref)`¶

Copies all fields from source to destination without validation.

Parameter	Type	Description
`a_ref`	int	Source object reference
`b_ref`	int	Destination object reference

Side effects:

Writes all fields from a_ref to b_ref via pool access
Declares local variable i in caller's scope

Notes: Caller is responsible for ensuring both references are valid. Use copy_a_to_b() for validated copying.

`#type#.delete(ref)`¶

Deallocates an object and returns it to the free pool.

Parameter	Type	Description
`ref`	int	Reference to object to delete

Side effects:

Calls #type#.Destructor() hook
Decrements #type#.count
Marks block as free in #type#.is_alloc[]
Returns block to #type#.Blocks queue
Sets ref to -1 in caller's scope (consequence of inlining)
Updates RAM report if use_ram_report is TRUE

Notes: Safe to call on null (-1) or dangling references (silently ignored). The ref parameter is modified in the caller's scope due to function inlining.

`#type#.empty_fields(address)`¶

Fills all object fields with -1.

Parameter	Type	Description
`address`	int	Object reference to clear

Side effects:

Writes -1 to all fields via pool access
Declares local variable i in caller's scope

`#type#.init(address)`¶

Initializes all object fields from INIT array.

Parameter	Type	Description
`address`	int	Object reference to initialize

Side effects:

Writes all fields from INIT array via pool access
Declares local variable i in caller's scope

`#type#.new() -> result`¶

Allocates a new object with default field initialization.

Returns: result — Reference to new object, or -1 if pool exhausted

Side effects:

Marks block as allocated in #type#.is_alloc[]
Increments #type#.count
Calls #type#.init() to set fields from INIT array
Calls #type#.Constructor() hook
Updates RAM report if use_ram_report is TRUE
Prints error message if pool exhausted

`#type#.new_copy() -> result`¶

Allocates a new object without field initialization.

Returns: result — Reference to new uninitialized object, or -1 if pool exhausted

Side effects:

Marks block as allocated in #type#.is_alloc[]
Increments #type#.count
Calls #type#.Constructor() hook
Updates RAM report if use_ram_report is TRUE
Prints error message if pool exhausted

Notes: Fields contain garbage values until explicitly written. Intended for internal use by copy().

`#type#.print(ref)`¶

Prints object representation to message area.

Parameter	Type	Description
`ref`	int	Object reference to print

Side effects:

Calls #type#.repr() to generate string
Writes to @#type#.to_string
Displays message via message() command

`#type#.repr(ref) -> result`¶

Generates string representation of object fields.

Parameter	Type	Description
`ref`	int	Object reference to represent

Returns: result — String representation of object

Side effects:

Declares local variable i in caller's scope

Example¶

// TODO: Add usage example

Types¶

Import¶

Overview¶

API¶

Defines¶

Const Blocks¶

Properties¶

Macros¶

Functions¶

Defines¶

define check_ref(#type#, #ref#)¶

define TYPE.MEM_CLEAR¶

Const Blocks¶

const #type#.field¶

Properties¶

property #type#.#field#¶

property #type#.access¶

Macros¶

store_literal_name(#array#, #n#, #l#)¶

type.CheckMethodRef(#type#, #method#, #ref#)¶

type.CheckRef(#type#, #ref#)¶

type.Create(#type#)¶

type.CreateCustomPool(#type#, #pool#)¶

type.FillLocals(#type#, #ref#)¶

type.FillObj(#type#, #ref#)¶

type.FillRawLocals(#type#, #ref#)¶

type.FillRawObj(#type#, #ref#)¶

type.Functions(#type#)¶

type.Locals(#type#, #ref#)¶

type.RawLocals(#type#, #ref#)¶

Functions¶

#type#.clear_mem(address)¶

#type#.clear_pool()¶

#type#.copy(src) -> result¶

#type#.copy_a_to_b(a_ref, b_ref)¶

#type#.copy_a_to_b.unsafe(a_ref, b_ref)¶

#type#.delete(ref)¶

#type#.empty_fields(address)¶

#type#.init(address)¶

#type#.new() -> result¶

#type#.new_copy() -> result¶

#type#.print(ref)¶

#type#.repr(ref) -> result¶

Example¶

See Also¶

`define check_ref(#type#, #ref#)`¶

`define TYPE.MEM_CLEAR`¶

`const #type#.field`¶

`property #type#.#field#`¶

`property #type#.access`¶

`store_literal_name(#array#, #n#, #l#)`¶

`type.CheckMethodRef(#type#, #method#, #ref#)`¶

`type.CheckRef(#type#, #ref#)`¶

`type.Create(#type#)`¶

`type.CreateCustomPool(#type#, #pool#)`¶

`type.FillLocals(#type#, #ref#)`¶

`type.FillObj(#type#, #ref#)`¶

`type.FillRawLocals(#type#, #ref#)`¶

`type.FillRawObj(#type#, #ref#)`¶

`type.Functions(#type#)`¶

`type.Locals(#type#, #ref#)`¶

`type.RawLocals(#type#, #ref#)`¶

`#type#.clear_mem(address)`¶

`#type#.clear_pool()`¶

`#type#.copy(src) -> result`¶

`#type#.copy_a_to_b(a_ref, b_ref)`¶

`#type#.copy_a_to_b.unsafe(a_ref, b_ref)`¶

`#type#.delete(ref)`¶

`#type#.empty_fields(address)`¶

`#type#.init(address)`¶

`#type#.new() -> result`¶

`#type#.new_copy() -> result`¶

`#type#.print(ref)`¶

`#type#.repr(ref) -> result`¶