Skip to content

TUK_REFERENCE.md

Latest commit

 

History

History
509 lines (429 loc) · 9.69 KB

TUK_REFERENCE.md

File metadata and controls

509 lines (429 loc) · 9.69 KB

Tuk Language Reference

Table of Contents

  1. Keywords
  2. Types
  3. Operators
  4. Stdlib Modules
  5. Common Patterns
  6. Common Mistakes
  7. Compiler Builtins

Keywords

Declaration Keywords

  • pub - Make declaration public (exportable)
  • con / pub con - Constant declaration (compile-time)
  • type - Type/struct definition
  • enum - Enum/tagged union definition
  • trait - Interface definition
  • impl - Trait implementation

Control Flow

  • if / else / when - Conditionals
  • for - Loops (range, condition, infinite, each)
  • match - Pattern matching
  • break / continue - Loop control
  • defer - Deferred execution (LIFO)

Functions

  • fn - Function declaration
  • fail - Function can return error
  • or - Error handling: or fwd (propagate), or value (fallback), or panic (crash)

Other

  • use - Import module
  • extern - C FFI
  • go - Spawn thread
  • wait - Join thread

Types

Primitive Types

i8, i16, i32, i64, i128      -- Signed integers
u8, u16, u32, u64, u128      -- Unsigned integers  
f32, f64                     -- Floating point
bool                         -- Boolean (true, false)
str                          -- String
void                         -- No value

Collection Types

vec[T]       -- Vector of T (e.g., vec[i32], vec[str], vec[f64])
fvec         -- Vector of f64 (specialized float vector)
map[K]       -- Map with key type K (e.g., map[str], map[i32])
map[K, V]    -- Map with key K and value V
chan(N)      -- Channel with buffer size N
mat          -- Matrix (2D array of f64)

Special Types

?T           -- Optional type (nullable)
*T           -- Pointer to T
() -> T      -- Function type

Operators

Arithmetic

+    -- Add
-    -- Subtract
*    -- Multiply
/    -- Divide
%    -- Modulo

Comparison

==   -- Equal
!=   -- Not equal
<    -- Less than
>    -- Greater than
<=   -- Less or equal
>=   -- Greater or equal

Logical

&&   -- AND (note: NOT 'and')
||   -- OR (note: NOT 'or')
!    -- NOT

Bitwise

<<   -- Shift left
>>   -- Shift right
&    -- Bitwise AND
|    -- Bitwise OR
^    -- Bitwise XOR

Assignment

=    -- Assign
:=   -- Declare and assign (shorthand)

Stdlib Modules

Built-in (no import needed)

use mathlib        -- Math: arithmetic, primes, geometry, neural activations

Available Modules

Module Description
mathlib Math: add, sub, mul, pow, isqrt, clamp, factorial, fibonacci, is_prime, gcd, lcm
ml ML: ml_sigmoid, ml_relu, ml_tanh
gboost Gradient boosting primitives
automl AutoML: model selection, hyperparameter search
lexer.t Self-hosted tokenizer (use lexer)
parser.t Self-hosted parser (use parser)
alloc.t Arena allocator
native_vec.t Vec implementation in Tuk
complex.t Complex numbers
evolve.t Genetic algorithms
tukllm LLM inference: Linear, Embedding, LayerNorm, Attention, MLP, Transformer
tukquant Quantization: Q8_0, Q4_0, Q4_K
tukgui GUI framework: Text, Button, Row, Column, Stack, Container, Image, Scroll
tukgui.core GUI core: Colors, Size, Box, Constraints, RenderCommand
tukgui.layout Layout engine: flexbox-like layout system
tukgui.widget Widget base: Widget trait, children management
tukgui.events Events: pointer, keyboard, gestures
tukgui.widgets.basic Basic widgets: Text, Button, Row, Column, Stack, Container

Runtime Functions (built-in)

-- Random
random() f64                      -- Random float 0-1
random(lo: f64, hi: f64) f64     -- Random float in range
seed(n: i32) void                -- Set PRNG seed
rand() i32                       -- Next PRNG value (after seed)

-- Hash
hash(s: str) i32                 -- FNV-1a hash
to_hex(n: i32) str                -- Convert to hex string

-- Math
abs(x: f64) f64
sqrt(x: f64) f64
exp(x: f64) f64
ln(x: f64) f64
pow(x: f64, y: f64) f64
sin(x: f64) f64
cos(x: f64) f64
tan(x: f64) f64
asin(x: f64) f64
acos(x: f64) f64
atan(x: f64) f64
floor(x: f64) f64
ceil(x: f64) f64
round(x: f64) f64

-- String
len(s: str) i32
trim(s: str) str
to_upper(s: str) str
to_lower(s: str) str
contains(haystack: str, needle: str) bool
starts_with(s: str, prefix: str) bool
index_of(s: str, sub: str) i32
split(s: str, delim: str) vec[str]
replace(s: str, old: str, new: str) str
char_at(s: str, i: i32) str
substr(s: str, start: i32, len: i32) str
to_int(s: str) i32
to_float(s: str) f64
to_str(n: i32) str
to_str(f: f64) str
to_str(b: bool) str

-- I/O
open(path: str, mode: str) file
read_csv(path: str) csv
read_lines(path: str) lines
print(...) void
println(...) void

-- Matrix (mat)
mat(rows: i32, cols: i32) mat
mat_rows(m: mat) i32
mat_cols(m: mat) i32
mat_get(m: mat, r: i32, c: i32) f64
mat_set(m: mat, r: i32, c: i32, v: f64) void
mat_add(a: mat, b: mat) mat
mat_sub(a: mat, b: mat) mat
mat_mul(a: mat, b: mat) mat
mat_scale(m: mat, s: f64) mat
mat_transpose(m: mat) mat
mat_sum(m: mat) f64
mat_mean(m: mat) f64

-- Conversions
to_i8(x) i8
to_i16(x) i16
to_i32(x) i32
to_i64(x) i64
to_u8(x) u8
to_u16(x) u16
to_u32(x) u32
to_u64(x) u64
to_f32(x) f32
to_f64(x) f64

-- Crypto (runtime)
sha256(s: str) str
md5(s: str) str
hmac_sha256(key: str, msg: str) str
base64_encode(s: str) str
base64_decode(s: str) str
aes256_encrypt(key: str, plaintext: str) str
aes256_decrypt(key: str, ciphertext: str) str
chacha20_encrypt(key: str, nonce: str, msg: str) str
chacha20_decrypt(key: str, nonce: str, msg: str) str
random_bytes(n: i32) str
regex_match(pattern: str, s: str) i32
regex_extract(pattern: str, s: str) str
regex_replace(pattern: str, s: str, replacement: str) str

Common Patterns

Creating a Matrix

m = mat(3, 4)
m.set(i, j, val)
val = m.get(i, j)
rows = mat_rows(m)
cols = mat_cols(m)

Matrix Operations (use METHODS, not functions)

result = a.mul(b)      -- matrix multiply
result = a.add(b)      -- matrix add
result = a.scale(2.0)  -- scalar multiply
result = transpose(m)  -- standalone function

Vector Operations

v = vec[i32]()
v.push(42)
v.get(i)
v.len()

Loops

-- Range
for i in 0..10 { ... }

-- Condition
for x > 0 { ... }

-- Infinite
for { ... }

-- Each
for item in items { ... }

Error Handling

fn read_file(path: str) str fail {
    f = open(path, "r") or fwd
    content = f.read()
    f.close()
    > content
}

-- Usage with fallback
data = read_file("config.json") or ""

Struct Definition

type Point {
    x: f64
    y: f64
}

pub type Point3D {
    x: f64
    y: f64
    z: f64
}

Method Definition

(p: Point) distance(other: Point) f64 {
    dx = p.x - other.x
    dy = p.y - other.y
    > isqrt((dx*dx + dy*dy).to_int()).to_float()
}

Trait + Impl

trait Printable {
    to_string() str
}

impl Printable for Point {
    (p: Point) to_string() str {
        > "Point({p.x}, {p.y})"
    }
}

Pipe Operator

result = "  hello world  " |> .trim() |> .to_upper()
-- result: "HELLO WORLD"

If-Else Expression

x = if a > b { a } else { b }

Match Expression

result = match x {
    1 -> "one"
    2 -> "two"
    _ -> "other"
}

Common Mistakes

1. DON'T use tensor type - use mat

-- WRONG
pub zeros(rows: i32, cols: i32) tensor { ... }

-- RIGHT
pub zeros(rows: i32, cols: i32) mat { ... }

2. DON'T use standalone functions for mat ops - use METHODS

-- WRONG
result = mat_mul(input, weight)

-- RIGHT
result = input.mul(weight)

3. DON'T use compound assignment

-- WRONG
cache.current_len += seq_len

-- RIGHT
cache.current_len = cache.current_len + seq_len

4. DON'T use and / or - use && / ||

-- WRONG
if a > 0 and b > 0 { ... }

-- RIGHT
if a > 0 && b > 0 { ... }

5. DON'T use complex and conditions in if - use intermediate variables

-- WRONG
if idx >= 0 && idx < e.num_embeddings { ... }

-- RIGHT
valid = idx < e.num_embeddings
if valid { ... }

6. Use standalone functions for NN modules, NOT methods

-- WRONG
(l: Linear) forward(input: mat) mat { ... }

-- RIGHT
linear_forward(l: Linear, input: mat) mat { ... }

7. DON'T use field access in complex expressions

-- WRONG (may not work)
result = complex_expr.field.get(0)

-- RIGHT
temp = complex_expr.field
result = temp.get(0)

8. Module imports are flat

-- WRONG
use tukllm.core.config

-- RIGHT
use tukllm

9. Constants use con not const

-- WRONG
const MAX_SIZE: i32 = 100

-- RIGHT
con MAX_SIZE: i32 = 100

Compiler Builtins

These are available automatically without import:

Type Conversions

to_int(x) i32
to_float(x) f64
to_str(x) str
to_i8(x) i8
to_i16(x) i16
to_i32(x) i32
to_i64(x) i64
to_u8(x) u8
to_u16(x) u16
to_u32(x) u32
to_u64(x) u64
to_f32(x) f32
to_f64(x) f64

String Methods

s.len() i32
s.trim() str
s.to_upper() str
s.to_lower() str
s.contains(sub: str) bool
s.starts_with(prefix: str) bool
s.index_of(sub: str) i32
s.split(delim: str) vec[str]
s.replace(old: str, new: str) str
s.char_at(i: i32) str
s.substr(start: i32, len: i32) str
s.to_int() i32
s.to_float() f64

Vector Methods

v.len() i32
v.push(val) void
v.get(i: i32) T
v.set(i: i32, val) void
v.pop() T

Matrix Methods

m.mul(other: mat) mat
m.add(other: mat) mat
m.scale(s: f64) mat

Notes

  • All loops in Tuk are expressions (return value)
  • Default return is implicit (last expression)
  • Pipe operator chains method calls
  • Block comments use --- ... ---
  • No semicolons needed
  • Indentation matters for blocks