sounio copilot-instructions.md

Sounio Language Instructions for GitHub Copilot

Sounio (.sio) is a systems + scientific programming language. It is NOT Rust. Full syntax reference: docs/LLM_PROGRAMMING_GUIDE.md

Compiler

SOUC=./bin/souc
$SOUC check file.sio        # type-check
$SOUC run file.sio          # compile to temp ELF, then execute

Critical Syntax Differences from Rust

• NO semicolons: let x = 5 not let x = 5;
• NO &mut: use &! for exclusive refs
• NO let mut: use var for mutable bindings
• NO Rust macros: assert(cond) not assert!(cond), println("text") not println!("text")
• NO unary minus: 0 - 42 not -42
• NO closure literals: |x| x + 1 does not work. Use named fn refs: let f = square
• NO attributes: no #[test], #[derive()]
• Bit shifts require u8: x >> 4u8

Effects System (REQUIRED)

Functions must declare side effects or the compiler rejects them:

fn pure(a: i64, b: i64) -> i64 { a + b }
fn greet(name: &str) with IO { println(name) }
fn mutate(x: &!i32) with Mut { *x = 42 }
fn divide(a: f64, b: f64) -> f64 with Div, Panic { a / b }
fn main() with IO, Mut, Panic, Div { /* ... */ }

Effects: IO (print/file), Mut (&! mutation), Div (division/modulo), Panic (array access, assert, as casts)

Variables and Types

let x = 5                           // immutable
var y: i32 = 10                     // mutable
var buf: [i64; 8] = [0; 8]          // fixed-size array
let p = Point { x: 1.0, y: 2.0 }   // struct
let (a, b) = (1, 2)                 // tuple destructuring

Primitives: i8, i16, i32, i64, u8, u16, u32, u64, f32, f64, bool, char

Control Flow

for i in 0..10 { /* exclusive */ }
for i in 0..=10 { /* inclusive */ }
for x in arr { /* array iteration */ }
while cond { /* ... */ }
if x > 0 { "pos" } else { "neg" }   // if is an expression

break and continue work in for-in and while loops.

Functions and Methods

fn square(x: i64) -> i64 { x * x }

// Function references (closures do NOT work)
let f = square
let r = f(7)

// Higher-order
fn apply(f: fn(i64) -> i64, x: i64) -> i64 { f(x) }

// Methods use explicit self
impl MyStruct {
    fn new() -> MyStruct { MyStruct { val: 0 } }
    fn get(self: &MyStruct) -> i64 { self.val }
    fn set(self: &!MyStruct, v: i64) with Mut { self.val = v }
}