Zerionyx Documentation

Data Types

Zerionyx is dynamically typed. Here are the primary data types:

• Number: Can be an integer (e.g., 10, -5) or a float (e.g., 3.14)
• String: A sequence of characters, enclosed in double quotes (e.g., "hello")
• Bool: Represents boolean values, either true or false
• List: An ordered collection of items, similar to an array (e.g., [1, "two", true])
• HashMap: A collection of key-value pairs (e.g., {"name": "Zyx", "version": 1}), keys must be strings
• Bytes: A sequence of raw bytes, useful for binary data and hashing
• CFloat: A "correct float" type that uses high-precision decimals to avoid common floating-point errors
• None: A special type representing the absence of a value, written as none

Built-in Constants

Zerionyx provides several global constants for convenience.

Core Values

• true — The boolean value for truth
• false — The boolean value for falsehood
• none — Represents the absence of a value
• is_main — Check if the current file is the one being executed

Type Representations (Strings)

These constants are string values that correspond to the output of the type() function. They are useful for type checking.

if type([1, 2]) == list do
    println("It's a list!")
done

• list → "<list>"
• str → "<str>"
• int → "<int>"
• float → "<float>"
• bool → "<bool>"
• func → "<func>"
• hashmap → "<hashmap>"
• thread → "<thread>"
• bytes → "<bytes>"
• cfloat → "<cfloat>"
• py_obj → "<py-obj>"
• namespace → "<namespace>"
• channel_type → "<channel>"
• none_type → "<none>"
• thread_pool_type → "<thread-pool>"
• future_type → "<future>"

Special Numeric Values

• nan — Not a Number
• inf — Positive infinity
• neg_inf — Negative infinity

Built-in Functions

• append(obj, val) → list — Add val to end of obj return val
• is_panic(func, args=[], kwargs={}) → list — Run func with args return [result, none, none] if ok or [none, err_msg, err_name ("RT": "Runtime Error", "M": "Math Error", "IO": "IO Error" or "T": "Type Error")] if error
• clear() → none — Clear terminal
• extend(a, b) → none — Add all in b to a both must be list
• input(prompt="") → str — Show prompt get user input
• get_password(prompt="") → str — Show prompt get user password
• insert(lst, i, val) → none — insert val to lst at index i
• is_func(x) → bool — Check if x is func
• is_list(x) → bool — Check if x is list
• is_py_obj(x) → bool — Check if x is PyObject
• is_none(x) → bool — Check if x is none
• is_num(x) → bool — Check if x is number
• is_str(x) → bool — Check if x is string
• is_bool(x) → bool — Check if x is boolean
• is_thread(x) → bool — Check if x is thread
• is_thread_pool(x) → bool — Check if x is thread pool
• is_future(x) → bool — Check if x is future
• is_namespace(x) → bool — Check if x is namespace
• keys(hm) → list — Return list of all keys in hm (a hashmap)
• values(hm) → list — Return list of all values in hm
• items(hm) → list — Return list of [key, value] pairs in hm
• has(hm, key) → bool — Return true if key exists in hm
• get(hmol, koi, default=none) → any — Return value for koi or default if not found
• del_key(hm, key) → none — Delete key and its value from hm
• len(x) → number — Get length of x
• panic(msg, type="RT") — Stop with err msg and type ("RT": "Runtime Error", "M": "Math Error", "IO": "IO Error" or "T": "Type Error")
• pop(lst, i) → any — Remove and return item at i in lst
• print(value="") → none — Prints text to the standard output with no newline
• println(value="") → none — Same as print but adds a newline
• to_float(x, supress_error=false) → number (float)/none — Convert x to float return none if fail and supress_error true else raise
• to_int(x, supress_error=false) → number (int)/none — Convert x to int return none if fail and supress_error true else raise
• to_str(x) → str — Convert x to string
• to_cfloat(x, supress_error=false) → cfloat — Convert x to cfloat (correct float) return none if fail and supress_error true else raise
• to_bytes(x, from_hex=false, supress_error=false) → bytes — Convert x to bytes return none if fail and supress_error true else raise
• type(x) → str — Return type of x as string
• pyexec(code, env={}) → hashmap — Executes embedded Python code and returns its result (use with caution)
• slice(l, from=none, to=none, step=none) → list/string/hashmap/bytes — Slice list/string/hashmap/bytes l from from to to step step (exclusive)
• is_nan(n) → bool — Check if n is NaN (Not a Number)
• is_channel(n) → bool — Check if n is channel
• is_cfloat(n) → bool — Check if n is cfloat
• clone(value) → any — Clone and return value
• get_member(namespace, member, default=none) → any — Gets a member from a namespace, returning default if it does not exist
• shl(a, b) → number (int) — Bitwise left shift on integer a by b positions
• shr(a, b) → number (int) — Bitwise right shift on integer a by b positions
• bitwise_and(a, b) → number (int) — Performs a bitwise AND operation on integers a and b
• bitwise_or(a, b) → number (int) — Performs a bitwise OR operation on integers a and b
• bitwise_xor(a, b) → number (int) — Performs a bitwise XOR operation on integers a and b
• bitwise_not(a) → number (int) — Performs a bitwise NOT (inversion) operation on integer a

Namespaces

Namespaces are objects that serve as containers to group related variables and functions. They help organize code and prevent name conflicts, especially when building libraries.

You can define a namespace using the namespace ... done block. Members inside the namespace are accessed using dot notation (.).

Important note: All variables and functions declared inside a namespace are immutable. This means:

• The names of variables and functions cannot be changed or reassigned after they are defined.
• Members of a namespace are read-only — they can be accessed but not modified or overridden.

# Define a namespace to group math-related utilities
namespace math_utils
    pi = 3.14159
    
    defun circle_area(radius)
        return pi * radius ^ 2
    done
done

# Access members using dot notation
r = 10
area = math_utils.circle_area(r)

println("The area is " + to_str(area))
println("Pi value: " + to_str(math_utils.pi))

Control Flow

Conditional logic is handled using if, elif, and else statements. Each block of code to be executed is introduced by the do keyword and the entire structure is terminated by done.

score = 85

if score >= 90 do
    println("Grade: A")
elif score >= 80 do
    println("Grade: B")
else do
    println("Grade: C or lower")
done

Loops

Zerionyx provides three types of loops.

While Loop

Executes a code block if a condition is true.

count = 0
while count < 5 do
    println(count)
    count = count + 1
done

For Loop (Numeric Range)

Iterates over a range of numbers.

# Prints numbers from 0 to 10
for i to 11 do
    println(i)
done

# Prints numbers from 01 to 99
for i to 10, j = 1 to 10 do
    println(to_str(i) + to_str(j))
done

# Prints even numbers from 2 to 10
for j = 2 to 11 step 2 do
    println(j)
done

For-In Loop (Iterator)

Iterates over the elements of an iterable like a list or string.

fruits = ["apple", "banana", "cherry"]
for fruit in fruits do
    println("I like " + fruit)
done

The break statement can be used to exit a loop immediately, and continue skips to the next iteration.

Functions

Functions are defined with the defun keyword. They can accept parameters and also support default values.

Function

A function is a reusable block of code that can be called with arguments to perform specific operations.

defun greet(name="World")
    return "Hello, " + to_str(name) + "!"
done

println(greet("Zerionyx")) # Output: Hello, Zerionyx!
println(greet())           # Output: Hello, World!

Anonymous and One-Line Functions

Functions can also be defined on a single line, and can be anonymous (without a name).

# One-line function
defun sqrt(x) -> x ^ 0.5

# Anonymous function assigned to a variable
a = defun (x) -> x ^ 0.5

Decorators

Decorators modify or enhance functions using the & symbol before the function definition. A decorator is a function that takes another function and returns a new, modified function.

load "libs.decorators"

# &decorators.once ensures this function only runs its body the first time it's called
&decorators.once
defun initialize_settings()
    println("Settings initialized")
done

initialize_settings() # Output: Settings initialized
initialize_settings() # Does nothing

The using Statement: Accessing Global Scope

The using statement is used to explicitly bind a variable reference to the global scope rather than creating a new local variable. This allows a function to read from and modify a global variable directly.

using : The global Analogy

When you need a function to modify a variable that exists in the global scope (or a specific top-level namespace), using creates a direct, writable link to that original variable. This brings the name into the local scope for easy access.

is_running = true

defun stop_application()
    using is_running
    is_running = false
done

println("App is running: " + to_str(is_running)) # Output: App is running: true

stop_application()

println("App is running: " + to_str(is_running)) # Output: App is running: false

using parent Statement: The nonlocal Analogy

The using parent statement is used inside nested functions. It binds a variable reference to the immediate parent function’s scope, similar to Python’s nonlocal keyword.

x = 2 # Global variable

defun outer()
    x = 0 # Local variable, shadows the global 'x'

    defun inner()
        using parent x
        x += 1
    done

    println("outer's x before: " + to_str(x)) # Output: outer's x before: 0
    inner()
    println("outer's x after: " + to_str(x)) # Output: outer's x after: 1
done

outer()
println("global x: " + to_str(x)) # Output: global x: 2

Vargs and Kwargs

Zerionyx supports functions that can accept a variable number of arguments using special syntax in the parameter list.

Vargs (*args)

A parameter prefixed with a single asterisk (*) will collect all extra positional arguments into a list. This is often called "vargs" or "star-args".

Kwargs (**kwargs)

A parameter prefixed with a double asterisk (**) will collect all extra keyword arguments into a HashMap. This is commonly known as "kwargs".

defun show_details(name, *scores, **details)
    println("Name: " + name)
    println("Scores (Vargs): " + to_str(scores))
    println("Details (Kwargs): " + to_str(details))
done

# Call the function with multiple positional and keyword arguments
show_details("Alice", 95, 88, 100, age=25, city="New York")

# Output:
# Name: Alice
# Scores (Vargs): [95, 88, 100]
# Details (Kwargs): {"age": 25, "city": "New York"}

Input/Output

Basic console I/O is handled by built-in functions.

• println(value): Prints the value followed by a newline
• print(value): Prints the value without a newline
• input(prompt): Displays a prompt and returns the user's input as a string

name = input("Enter your name: ")
println("Hello, " + name)

Error Handling

Zerionyx uses a "panic" system for errors. Instead of traditional try-catch blocks, you can safely execute a function using the is_panic built-in. It returns a list indicating success or failure.

defun divide(a, b)
    if b == 0 do
        panic("Cannot divide by zero!", "M") # "M" for Math Error
    done
    return a / b
done

result = is_panic(divide, [10, 0])
value = result$0      # The result if successful
error_msg = result$1  # The error message if it failed
error_type = result$2 # The error type (e.g., "M")

if error_msg != none do
    println("Error: " + error_msg)
else do
    println("Result: " + to_str(value))
done
# Output: Error: Cannot divide by zero!

File Handling

File operations are managed through the ffio standard library.

load "libs.ffio"

filename = "greetings.txt"
content = "Hello from Zerionyx!"

# Write to a file
ffio.write(filename, "w", content)

# Read from a file
read_content = ffio.read(filename, "r")
println(read_content) # Output: Hello from Zerionyx!

Strings

Strings are immutable sequences of characters.

• Concatenation: "a" + "b" results in "ab"
• Repetition: "a" * 3 results in "aaa"
• Indexing: Use the $ operator to get a character at a specific index "hello"$1 results in "e"

For more advanced functions like splitting, joining, and replacing, use the string library.

Lists

Lists are mutable, ordered collections of items.

• Creation: my_list = [1, "a", true]
• Indexing: my_list$0 returns 1
• Appending: my_list + "new" returns [1, "a", true, "new"]
• Concatenation: [1, 2] * [3, 4] returns [1, 2, 3, 4]
• Removal by index: [1, 2, 3] - 1 returns [1, 3]

The listm library provides functions like map, filter, sort, etc.

HashMaps

HashMaps store key-value pairs. Keys must be strings.

• Creation: person = {"name": "Alex", "age": 30}
• Accessing: person$"name" returns "Alex"
• Adding/Updating: person + {"city": "New York"}, note that this returns a new map

Use built-in functions like keys(hm), values(hm), and has(hm, key) for more operations.

Assignment to Lists and HashMaps

The $ operator is not only used for accessing elements but also for assigning or updating values at a specific index in a list or a key in a HashMap.

List Assignment

You can change the value at a specific index of a list.

nums = [1, 2, 3, 4, 5]
nums$1 = 99 # Update the value at index 1
println(nums) # Output: [1, 99, 3, 4, 5]
println(nums$1) # Output: 99

HashMap Assignment

You can add a new key-value pair or update an existing one. This is particularly useful when building complex structures like a list of hashmaps.

users = []
append(users, {}) # Add an empty hashmap to the list

# Assign values to the hashmap inside the list
users$0$"name" = "user-1"
users$0$"password" = "123456"

println(users)
println(users$0$"name")
println(users$0$"password")

Bytes

The bytes type represents an immutable sequence of bytes. It's essential for working with binary data, file I/O in binary mode, and cryptographic hashing.

• Creation: Use the to_bytes(value) function
• From String: to_bytes("hello")
• From Hex: to_bytes("68656c6c6f", from_hex=true)
• Operations: Supports concatenation (+) and indexing ($)

load "libs.hash"
data = to_bytes("my secret data")
hashed_data = hash.sha256(data)
println(hashed_data)

CFloat (Correct Float)

Due to the nature of binary floating-point arithmetic, simple operations like 0.1 + 0.2 can result in imprecise values (e.g., 0.30000000000000004). The cfloat type avoids this by using a high-precision decimal representation.

Use to_cfloat(value) to create a CFloat. They support all standard arithmetic operations.

a = to_cfloat("0.1")
b = to_cfloat("0.2")
result = a + b

println(result) # Output: 0.3