core

The core global functions, reflection utilities, and built-in literal types available in kyro.

Also look at:

std: built-in standard library (native in rust).
lib: modules under lib/ written in kyro.

Built-in Types & The Base `Object` Class

Every value and built-in type in kyro inherits from a root base class named Object. Each built-in literal type has a corresponding global class object in the namespace (such as Object, List, Dict, String, Number, Bool, Nil, Callable, and Class) which can be used for runtime type-checking and reflections using is_instance().

                  Object
                 /  |   \
            Class  List  Number ... (All Built-in & User Classes)

Lists (`[...]`)

Lists are ordered, mutable collections of values. * Internal Representation: Value::List variant wrapping a heap-allocated Rc<RefCell<Vec<Value>>>. * Namespace Class: List < Object

Syntax & Manipulation

// Dynamic literal construction
var list = [1.0, 2.0, 3.0];

// Subscript indexing & slicing
var first = list[0];
var slice = list[1:3]; // [2.0, 3.0]

// Index assignment
list[1] = 100.0;

Bound Methods

.len(): Returns the number of elements in the list.
.push(val): Appends a value to the end of the list.
.pop(): Removes and returns the last element of the list.
.clear(): Removes all elements from the list.
.remove(index): Removes and returns the item at the specified index.
.join(separator): Joins list elements into a single string using a separator.
.map(fn): Transforms each element using a callback function/lambda and returns a new list.
.filter(fn): Returns a new list containing elements that satisfy a predicate function.
.contains(value): Returns true if the list contains the given item.
.index_of(value): Returns the index of the first occurrence of the item, or -1.
.insert(index, value): Inserts an element at a specific index.
.slice(start, end): Returns a sub-list slice from start up to end.
.reverse(): Reverses the list elements in place.
.sort(): Sorts the list elements in place.

Dictionaries (`{...}`)

Dictionaries are mutable key-value maps. * Internal Representation: Value::Dict variant wrapping an Rc<RefCell<HashMap<String, Value>>>. * Namespace Class: Dict < Object

Syntax & Manipulation

// Dynamic literal construction
var dict = {"key": "val"};

// Subscript indexing
var value = dict["key"];

// Index assignment
dict["new_key"] = "new_val";

Bound Methods

.len(): Returns the number of key-value pairs.
.keys(): Returns a list of all keys in the dictionary.
.values(): Returns a list of all values in the dictionary.
.clear(): Removes all entries from the dictionary.
.remove(key): Removes the specified key and returns its associated value.
.get(key, default): Safely retrieves value for key, or returns default (or nil) if not found.
.has_key(key): Returns true if the dictionary contains the given key.
.entries(): Returns a list of [key, value] pairs.
.merge(other_dict): Merges another dictionary into the current dictionary.

Strings

Strings represent UTF-8 encoded text sequences. * Internal Representation: Value::String variant. * Namespace Class: String < Object

Syntax & String Interpolation

Strings support inline interpolation via ${expr} and bracket indexing/slicing (str[0:5]):

var name = "kyro";
var greeting = "Hello, ${name}!";
var sub = greeting[0:5]; // "Hello"

Bound Methods

.len(): Returns the character length of the string.
.slice(start, end): Returns a substring from the start index up to end.
.split(separator): Splits the string into a list of substrings.
.trim(): Removes leading and trailing whitespace.
.contains(substring): Returns true if the string contains the given substring.
.to_lower(): Converts string characters to lowercase.
.to_upper(): Converts string characters to uppercase.
.replace(old, new): Replaces occurrences of old substring with new.
.starts_with(prefix): Returns true if the string starts with prefix.
.ends_with(suffix): Returns true if the string ends with suffix.
.index_of(substring): Returns the starting index of a substring, or -1.
.repeat(count): Repeats the string count times.
.to_number(): Parses and converts string into a numeric value.

Numbers

Numbers represent double-precision floating point numeric values in kyro. * Internal Representation: Value::Number variant wrapping f64. * Namespace Class: Number < Object

Bound Methods

.floor(): Rounds the number down to the nearest integer.
.ceil(): Rounds the number up to the nearest integer.
.round(): Rounds the number to the nearest integer.
.abs(): Returns the absolute value of the number.
.clamp(min, max): Clamps the numeric value between min and max bounds.
.round_to(precision): Rounds the number to specified decimal precision.
.sqrt(): Returns the square root of the number.
.pow(exponent): Raises the number to the specified power.
.to_hex(): Formats an integer number as a hexadecimal string.
.to_binary(): Formats an integer number as a binary string.

Built-in Exception Classes

kyro features a structured, object-oriented exception hierarchy inheriting from Exception and Object.

Object -> Exception -> ValueError
                    -> AttributeError
                    -> TypeError
                    -> IndexError

Exception

The base class of the entire exception hierarchy. All built-in and user-defined exception structures inherit from Exception. * Properties: * message: A message describing the cause of the error. * Methods: * __init__(self, message = ""): Automatically assigns the provided message. * __str__(self): Formats and returns the exception message as ClassName: Message.

ValueError (inherits from `Exception`)

Thrown when an operation receives an argument of the correct type but an inappropriate value (e.g. invalid string parsing using to_number()).

TypeError (inherits from `Exception`)

Thrown when an operation is applied to an object of an inappropriate type (e.g., trying to execute math on non-numbers, or calling a non-callable value).

AttributeError (inherits from `Exception`)

Thrown when an attribute reference fails on an object or class instance.

IndexError (inherits from `Exception`)

Thrown when a subscript index is out of bounds.

String Representation (`str`) Protocol

Whenever a class instance is printed using echo, print(), or converted via use("std:util").to_string(), the interpreter checks if the instance defines a __str__() magic method. If present, it executes __str__() and uses the returned string representation.

class CustomItem {
    fn __init__(self, val) {
        self.val = val;
    }

    fn __str__(self) {
        return "CustomItem(" + use("std:util").to_string(self.val) + ")";
    }
}

var item = CustomItem(100.0);
echo item; // Output: CustomItem(100)

Core Globals & Reflection

`id(item)`

Returns the unique memory address of the given item. * Backend Implementation: IdFn Rust struct in stdlib/mod.rs.

Usage:

var x = [1.0, 2.0, 3.0];
echo id(x); // Prints memory address

`dir(item)`

Returns a list of strings containing all keys, methods, and attributes associated with the specified item. * Backend Implementation: DirFn Rust struct in stdlib/mod.rs.

Usage:

var list = [1.0, 2.0];
echo dir(list); // ["clear", "contains", "filter", "index_of", "insert", "join", "len", "map", "pop", "push", "remove", "reverse", "slice", "sort"]

`is_instance(item, class)`

Checks whether the provided item is an instance of the specified class (or inherits from it). Supports both custom class structures and native built-in types (Object, String, Number, List, Dict, Bool, Nil, Callable, Class). * Backend Implementation: IsInstanceFn Rust struct in stdlib/mod.rs.

Usage:

// Checking primitive types using namespace classes
echo is_instance(42.0, Number);     // true
echo is_instance("hello", String);  // true
echo is_instance("hello", Object);  // true

// Checking custom OOP hierarchies
class Animal {}
class Dog < Animal {}

var poppy = Dog();
echo is_instance(poppy, Dog);      // true
echo is_instance(poppy, Animal);   // true (honors inheritance)
echo is_instance(poppy, Object);   // true (all instances inherit from Object)
echo is_instance(poppy, List);     // false

`type_of(value)`

Inspects the provided value and returns its corresponding namespace class object (type constructor). * Backend Implementation: TypeOfFn Rust struct in stdlib/mod.rs.

Usage:

echo type_of("hello") == String; // true
echo type_of(42.0) == Number;    // true
echo type_of([1.0, 2.0]) == List; // true

class Hello {}
var h = Hello();
echo type_of(h) == Hello;        // true
echo type_of(Hello) == Class;    // true

`range(start, end, step = 1)`

Generates a sequential list of numbers from the start value up to (but excluding) the end value, progressing by the step size. * Backend Implementation: RangeFn Rust struct in stdlib/mod.rs.

Usage:

// Range from 0 to 5 using default step size of 1
var r1 = range(0, 5); 
echo r1; // [0, 1, 2, 3, 4]

// Range with custom step size
var r2 = range(0, 10, step = 2);
echo r2; // [0, 2, 4, 6, 8]

// Reverse range using negative step size
var r3 = range(5, 0, step = -1);
echo r3; // [5, 4, 3, 2, 1]

`use(module_name)`

Loads a standard library or external module. All modules in kyro are namespace-isolated and must be explicitly imported. Calling use returns a module instance containing its native functions and values. If used ona folder, the main.kyro or main.ky file is included instead. Usage:

var util = use("std:util");
echo util.to_number("123.45");

`name`

A pre-loaded global variable storing the current module's name. For the primary entrypoint script, this evaluates to "__main__".

Usage:

if (__name__ == "__main__") {
    echo "Running as main script";
}

`instance.class`

Accessing __class__ on any class instance returns its underlying class definition as a class object.

Usage:

var class_name = my_instance.__class__.__name__;

`callable.name`

Accessing __name__ on any callable object (such as a class or function) returns its string identifier.

Usage:

echo my_function.__name__; // "my_function"

core

Built-in Types & The Base Object Class

Lists ([...])

Syntax & Manipulation

Bound Methods

Dictionaries ({...})

Syntax & Manipulation

Bound Methods

Strings

Syntax & String Interpolation

Bound Methods

Numbers

Bound Methods

Built-in Exception Classes

Exception

ValueError (inherits from Exception)

TypeError (inherits from Exception)

AttributeError (inherits from Exception)

IndexError (inherits from Exception)

String Representation (__str__) Protocol

Core Globals & Reflection

id(item)

dir(item)

is_instance(item, class)

type_of(value)

range(start, end, step = 1)

use(module_name)

__name__

instance.__class__

callable.__name__

Built-in Types & The Base `Object` Class

Lists (`[...]`)

Dictionaries (`{...}`)

ValueError (inherits from `Exception`)

TypeError (inherits from `Exception`)

AttributeError (inherits from `Exception`)

IndexError (inherits from `Exception`)

String Representation (`str`) Protocol

`id(item)`

`dir(item)`

`is_instance(item, class)`

`type_of(value)`

`range(start, end, step = 1)`

`use(module_name)`

`name`

`instance.class`

`callable.name`