Skip to content

Latest commit

 

History

History
505 lines (465 loc) · 26.4 KB

current-syntax.md

File metadata and controls

505 lines (465 loc) · 26.4 KB

Current Zmeu Syntax

This file maps the active Zmeu surface syntax. It is descriptive, not a design promise: older planning notes do not extend the accepted language.

File Shape

  • Zmeu uses indentation-sensitive blocks. Child blocks use exactly four spaces.
  • Top-level items are import, from, export from, const, extern, struct, enum, impl, and def. Importable declarations use export; pub remains accepted as legacy syntax.
  • Comments are line comments with #.
import std.fs as fs
from std.result import Result
export from .collections.hashmap import HashMap
const BUF_SIZE: usize = 4096

Declarations

  • import path.to.module imports a module namespace only, requiring qualified access such as std.fs.open_read(path).
  • import path.to.module as alias imports a module namespace under an explicit alias, requiring qualified access such as fs.open_read(path).
  • from path.to.module import Item, Other imports selected exported items into bare scope.
  • from .child import Item imports selected items from a child module. Parent relative imports are not part of this slice.
  • export from .child import Item re-exports selected accessible items as part of the current module's public API.
  • const NAME: Type = expr declares a checked compile-time constant.
  • export const NAME: Type = expr exports a constant from an imported module.
  • export(super) const NAME: Type = expr exposes a constant to the parent module.
  • export(package) const NAME: Type = expr exposes a constant inside the current package; the project and std are separate packages.
  • def name(params) -> Type: declares a function.
  • export def name(params) -> Type: exports a function from an imported module.
  • export(super) def name(params) -> Type: exposes a function to the parent module.
  • export(package) def name(params) -> Type: exposes a function inside the current package.
  • unsafe def name(params) -> Type: declares a function whose callers must use unsafe:. Its body is still checked normally.
  • export unsafe def name(params) -> Type: exports an unsafe function.
  • The same export, export(super), and export(package) visibility forms are accepted on struct, enum, struct fields, and impl methods. Plain declarations remain private by default; pub remains accepted as a legacy alias for public export.
  • def name[T, E](...) -> Type: declares an explicitly-instantiated generic function.
  • Function effect markers follow the return type before :: blocking, allocates, suspends, and offloads_blocking. Public suspending APIs must spell suspends; private helpers may infer it from their direct call graph. Source calls remain direct style, so a suspending call uses normal call syntax but must be reached through a root or structured spawn_io green-task boundary.
  • Executable entry point main may return None for success exit code 0, or i32 when the program intentionally returns a process exit code. Use std.process.process_exit(code) for explicit early exits from main -> None.
  • Method-level type parameters such as def method[T](...) are reserved for a later milestone.
  • extern "C": declares bodyless C ABI functions. Raw extern declarations are module-private in this slice.
  • unsafe: permits unsafe function calls, raw extern calls, and raw extern-call argument views inside the block.
  • import std.time as time exposes monotonic runtime time helpers: monotonic_nanos() -> u64 and elapsed_nanos(start: u64) -> u64.
  • import std.math as math exposes f32/f64 helpers for sqrt, abs, floor, ceil, trunc, is_nan, and is_finite.
  • import std.fmt as fmt exposes width-suffixed to_string_* helpers for integer, float, and bool values.
  • import std.time.reactor as time_reactor exposes reactor-backed sleep_for and sleep_until helpers for structured green tasks.
  • import std.bytes as bytes exposes safe ByteBuf and byte-slice helpers such as zeroed, filled, from_slice, append, resize_zeroed, copy_from, equal, starts_with, ends_with, find, contains, fill, and copy_exact.
  • import std.ascii as ascii exposes byte-oriented ASCII classification, folding, hex conversion, and case-insensitive equality helpers.
  • import std.json as json exposes validation-first JSON helpers: validate(input) -> Result[None, JsonError] and scan_structural_indexes(input) -> Result[List[usize], JsonError]. count_structural_indexes(input) -> Result[usize, JsonError] validates the same string lexemes and returns the structural count without materializing the index list. validate_and_count_structural_indexes(input) -> Result[usize, JsonError] validates full JSON syntax and returns the structural count in the same parser pass.
def identity[T](value: T) -> T:
    return value

extern "C":
    def write(fd: c_int, buf: *const u8, len: usize) -> c_ssize

Types

  • Scalars: i32, i64, u8, u32, u64, usize, f32, f64, bool, None.
  • C ABI aliases: c_int, c_long, c_size, c_ssize, c_bool, c_float, c_double.
  • Text/path wrappers are nominal std/runtime types such as String, PathBuf, Path, ByteBuf, CString, and CStr.
  • Borrowed text is written view str; borrowed paths/C strings are view Path and view CStr.
  • Views: view T for shared non-owning access and mut view T for mutable non-owning access. &T and &mut T remain accepted compatibility syntax.
  • Raw pointers: *const T and *mut T, currently only for narrow extern C boundaries.
  • Fixed-width SIMD values are written Simd[T; N] for T = u8, i32, u32, f32, or f64; masks are written Mask[N]. SIMD values and masks are copy fixed-size values and can be locals, params, returns, and struct fields in this slice.
  • Borrowed slices: [T]; fixed arrays: [T; N]. Borrowed slices are scalar integer/float/bool views in this slice. Fixed arrays support those scalar element types, concrete structs, nominal enums, and nested fixed arrays composed from supported elements.
  • Lists: List[T] over supported scalar integer/float/bool types, concrete structs, nominal enums, and compiler-known owned byte wrappers.
  • Atomics: Atomic[i32], Atomic[usize], Atomic[u64], and Atomic[bool].
  • Optional: T | None; float optionals are not part of this slice.
  • Union: A | B | C.
  • Nominal generics: Result[T, E], Box[T], etc.

Built-In Containers and Views

  • Fixed arrays and borrowed slices expose .len and indexing. Fixed arrays can be locals, by-value params/returns, and struct fields; arrays of structs also support indexed field reads/writes such as points[i].x. Borrowed slices support scalar integer/float/bool elements and concrete struct elements. Struct slices coerce from [Struct; N] and List[Struct]; shared views allow items[i].x reads, and mutable views allow items[i].x = value. By-value slices and slices over enums/options/owned dynamic wrappers are not supported. Mutable scalar slices can be indexed for writes when the borrow and range facts prove the access is valid. Simultaneous mutable borrows are accepted for disjoint constant or immutable-usize indexes and for non-overlapping half-open ranges; dynamic indexes/ranges without a static proof remain conservative.
  • List[T] supports empty literals with context (let xs: List[i32] = []), non-empty literals, .len, indexing, indexed assignment, .push(value), .clear(), .truncate(len), and borrowed-slice coercions such as view xs[:], view xs[lo:hi], or mut view xs[lo:hi] for scalar and struct element lists. .contains(value) -> bool and .index_of(value) -> usize | None are supported for i32/u8/u32/usize/u64/i64/bool lists and for List[String] searched by view str or a string literal. .sort() is supported for i32/u8/u32/usize/u64/i64 and String lists. Shared view List[T] parameter and annotation syntax is accepted as source sugar for the same read-only borrowed-slice view; mut view List[T] remains unsupported, so mutable list views should use an explicit list range. List[Enum] supports literals, .len, indexing for match/inspection, indexed whole-element assignment, .push(value), and borrowed-slice coercions to view [Enum] / mut view [Enum]. Moving an owned enum payload out through borrowed or indexed enum elements remains rejected; destructure copy payload fields or overwrite the whole element.
  • ByteBuf supports ByteBuf.new(), .len, .push(u8), .push_bytes(byte_source), .reserve(additional), .clear(), .truncate(len), indexed byte reads/writes (buf[i], buf[i] = value), .as_slice() -> view [u8], and .as_mut_slice() -> mut view [u8].
  • String supports String.new(), String.from_str(text), .push_str(text), width-suffixed .push_i32, .push_u8, .push_u32, .push_usize, .push_u64, .push_i64, .push_f32, .push_f64, .push_bool, .as_str() -> view str, and .as_bytes() -> view [u8].
  • PathBuf supports PathBuf.from_str(text), .push(component), .as_path() -> view Path, and .as_bytes() -> view [u8].
  • CString supports CString.from_str(text), CString.from_path(path), and .as_cstr() -> view CStr; construction rejects interior NUL bytes.
  • Structural mutations on owned containers are rejected while a borrowed view of the same storage is live, even when element/range borrows are otherwise proven disjoint.
  • Atomics use sequentially consistent methods in this slice: Atomic.new_i32(value), Atomic.new_u64(value), Atomic.new_usize(value), Atomic.new_bool(value), .load(), .store(value), .swap(value), .fetch_add(value), and .fetch_sub(value) where the method is valid for the element type.
  • SIMD construction and memory access are explicit: Simd[T; 4](a, b, c, d), Simd[T; 4].splat(value), Simd[T; 4].load(view xs[i:i + 4]), and value.store(mut view xs[i:i + 4]). Load/store require the borrowed slice length to equal the lane count at runtime. Simd[u8; N].load_prefix(view xs) accepts a byte slice with xs.len <= N, copies the slice prefix, and zeroes the remaining lanes. Arithmetic is lane-wise, comparisons produce Mask[N], masks are not bool, and mask results must be collapsed with .any(), .all(), or .to_bits() for masks up to 64 lanes. Mask[N].to_bits() -> u64 maps lane 0 to bit 0. Masks support bitwise &, |, ^, and ~, .prefix(len) to clear lanes >= len, and .compress_indexes(base, mut view out) for masks up to 64 lanes; compression writes ascending base + lane indexes to a mut view [usize], returns the count, and traps before writing if out is too short. Simd[u8; N], Simd[i32; N], and Simd[u32; N] support wrapping +, -, *, and bitwise &, |, ^; signedness controls ordered comparisons. Simd[u8; 16].lookup16(indexes) performs a byte-lane nibble table lookup where indexes is Simd[u8; 16], Simd[u8; 32], or Simd[u8; 64]: high-bit index lanes produce 0, and other lanes read table[index & 0x0f]. Masks do not support == or !=. mask.select(then_value, else_value) selects between two matching SIMD values lane by lane. SIMD values expose .extract(index) for a bounds-checked scalar lane read. Floating-point SIMD also exposes .reduce_add() for a deterministic left-to-right scalar sum. Integer SIMD division, remainder, shifts, integer reductions, wider integer lanes, SIMD containers, min/max or masked reductions, gather/scatter, and fast-math controls remain out of this slice.

Structs, Enums, and Methods

  • struct Name: declares named fields.
  • export struct Name: exports the type; fields remain private across modules unless written as export field: Type.
  • struct Name[T]: declares a generic struct.
  • enum Name: declares case Variant entries.
  • export enum Name: exports the enum type.
  • Enum payloads currently use one named payload: case Ok(value: T).
  • Nominal enum values can be stored in List[Enum], [Enum; N], function params/returns, and struct fields. Shared direct view Enum and borrowed view [Enum] / mut view [Enum] are supported for inspection, shared iteration, array/list coercions, and whole-element indexed assignment through mutable enum slices. Direct mut view Enum, moving owned payloads out through borrowed enum elements, by-value enum slices, and recursive owned nominal graphs through struct fields, enum payloads, fixed arrays, or lists remain rejected.
  • impl Type: declares associated functions and methods.
  • impl Box[T]: declares methods for every concrete generic struct instance requested by the program. Methods may use the impl type parameters after substitution.
  • Self is accepted inside an impl method signature, body annotation, associated call, or struct literal constructor and names the concrete impl receiver type.
  • Owned builder-style method chains are supported when each chained method takes self, self: Type, or self: Self by value and returns the next owned struct value. Borrowed receiver chaining from temporaries is reserved; bind the value to a local before calling view self or mut view self methods.
  • Consuming builder methods may move direct owned storage fields such as String, ByteBuf, and List[T] out of self when the containing builder type does not define drop.
  • Inside impl Type: the receiver type can be elided: write self for an owned receiver, self: view for a shared view, or self: mut view for a mutable view. Explicit Self or concrete receiver types remain accepted.
  • A -> None function or method may fall off the end without return None. Use bare return for an early no-value exit.
  • A destructor is exactly def drop(self: mut view) -> None: and cannot be called by user code.
export struct Point:
    x: i32
    export y: i32

enum Result[T, E]:
    case Ok(value: T)
    case Err(error: E)

impl Point:
    def origin() -> Self:
        return Self(x=0, y=0)

    def move_x(self: mut view, dx: i32) -> None:
        self.x = self.x + dx

Fields are private across module boundaries unless declared with export. Code inside the defining module can construct, read, write, and destructure private fields.

Statements

  • let name = expr declares an immutable local.
  • let mut name = expr declares a mutable local.
  • var name = expr is sugar for let mut name = expr.
  • let name: Type = expr adds a type annotation.
  • var name: Type = expr adds a type annotation to a mutable local.
  • place = expr assigns to a mutable local, field, index, or auto-deref target.
  • return expr, return, break, and continue control flow.
  • if condition:, elif condition:, and else: branch.
  • while condition: loops while a boolean condition is true.
  • for item in iterable: iterates shared array/slice elements. Struct loop items are shared element views, so item.x is readable and mutation through item is rejected.
  • match subject: is a statement match with block arms.
  • defer cleanup() registers a None-returning cleanup call for the current lexical scope. Deferred calls run in reverse source order on fallthrough, return, try propagation, loop break/continue, and panic cleanup. Deferred calls may borrow locals, but this first slice rejects moving non-copy owned values inside the deferred expression; prefer mut view self cleanup methods such as file.close_best_effort(). While a defer is active, the non-copy roots it needs for cleanup cannot be moved or replaced before scope exit.
  • use name = expr cleanup cleanup_call(): declares a resource local, registers a cleanup call for the resource block, and runs that cleanup on every block exit path. The cleanup expression must reference the resource binding.
  • use mut name = expr: is shorthand only for compiler-known std resource types with a safe best-effort cleanup method: currently std.fs.File, std.net.tcp.TcpListener, and std.net.tcp.TcpStream. Shorthand cleanup requires mut because closing invalidates the handle.
  • tasks: creates a structured task scope. Inside it, let t = spawn f(args) starts CPU work, let t = spawn_blocking f(args) starts known blocking work on the blocking pool, let t = spawn_io f(args) starts structured green-task work that may suspend on the internal runtime hook or Linux reactor I/O, and join t consumes a task handle. spawn_io f(args) is also accepted as a statement inside tasks: for None-returning suspending callees; this creates a scope-owned detached green child without retaining a handle, which is useful for dynamic accept loops. Task-scope cleanup waits for both unjoined handles and detached children. Detached child failures are propagated only when the lexical task scope exits; an intentionally never-ending server scope can record a child failure without surfacing it immediately. The full destruction, borrowed-capture, happens-before, and reactor-backend contract is documented in docs/concurrency-contract.md. The MIR interpreter resumes the internal hook immediately and sequentially but does not execute reactor I/O/timer suspend points; the native MLIR path uses the runtime resumable-task boundary. On Linux, std.net.reactor exposes nonblocking TCP operations, explicit listen backlog, TCP_NODELAY, and operation-specific stream timeouts backed by the runtime reactor, while std.time.reactor exposes reactor sleep helpers.
  • Handle-returning spawn, spawn_blocking, and spawn_io callees may return None, integer/bool scalars, owned std byte/string/path buffers (ByteBuf, String, PathBuf, CString), List[T] when T is TaskSend, and nominal structs/enums recursively composed from those TaskSend values. The same owned values may be moved into spawn, spawn_blocking, and spawn_io calls by passing them as ordinary by-value arguments. Detached statement-form spawn_io handlers must still return None. References, raw pointers, atomics, task handles, direct arrays, unions/optionals, floats, and custom user-drop values are not TaskSend in this milestone.
  • Values that remain live across a direct suspending call must be frame-lowerable. Supported live-across-suspend values include scalars, supported fixed-size arrays, references, task handles, supported owned dynamic values such as List[T], ByteBuf, String, PathBuf, and CString, optionals, and aggregates recursively composed from supported fields. Standalone raw pointers, atomics, slices, str, Path, and CStr are rejected as live-across-suspend frame values.
  • zmeu check --emit-suspend-frames file.zmeu prints the stable audit report for invisible suspend points. Function rows contain the exact native frame_bytes; suspend-point rows contain live locals and their ABI byte sum.
  • parallel for chunk in chunks(mut view xs[:], chunk_size): is the structured data-parallel loop surface for integer scalar slices. chunk_index can be bound with parallel for chunk, chunk_index in chunks(...):. The chunk size must be a positive compile-time usize literal or const, and chunks(...) is compiler-known only in the parallel for ... in header.
  • Parallel loop bodies may use the chunk binding, optional chunk_index binding, module constants/functions, locals declared inside the body, and read-only captures of enclosing immutable primitive scalars or shared primitive slice/list views. Mutable locals, owned containers, task handles, blocking/allocating/suspending values, and other captures are rejected before MIR/codegen. return, top-level break, top-level continue, and try are rejected inside the body; loop-local break/continue remain valid. defer keeps its normal per-chunk cleanup meaning.
  • parallel_for_chunks(mut view xs[:], chunk_size, worker) remains supported as the statement-only lower-level helper. The worker has shape def worker(chunk: mut view [T], chunk_index: usize) -> None.
use mut file = try fs.open_read(path) cleanup file.close_best_effort():
    let used: usize = try fs.file_read(file, buf)

use mut stream = try tcp.accept(listener):
    try tcp.stream_write_all(stream, b"HTTP/1.1 200 OK\r\n\r\n")

parallel for chunk, chunk_index in chunks(mut view xs[:], 8):
    let mut i: usize = 0
    while i < chunk.len:
        chunk[i] = chunk[i] + (chunk_index as i32)
        i = i + 1

Match Expressions and Patterns

  • Match expressions are currently accepted in let, assignment, and return positions.
  • Expression arms use case Pattern => expr.
  • Block arms use case Pattern: and must end with yield expr.
  • Statement matches use block arms and may include else:.
  • Guards use case Pattern if condition in statement and match-expression arms. Guard false falls through to the next source arm for the same top-level pattern, then to else: or the unmatched path. Guarded arms do not prove exhaustiveness; add an unguarded fallback arm when a pattern must be covered. Guards can read copy pattern bindings, but non-copy bindings are available only after the guard succeeds. Guards may shared-borrow the matched subject, but they cannot move, mutably borrow, or mutate it before payload binding.
let value: i32 = match result:
    case Ok(x) if x > 0 => x
    case Ok(x) => 0
    case Err(e):
        print_i32(0)
        yield 42

match optional:
    case Point { x, y: yy }:
        print_i32(x + yy)
    case None:
        return

Supported pattern forms:

  • None
  • Type
  • Type as name
  • Struct { field }
  • Struct { field: binding }
  • Variant
  • Variant(binding)
  • Variant(Struct { field })

Expressions

  • Literals: integers, hexadecimal integers, decimal floats such as 1.0 and 1e-3, strings, byte literals such as b'\n', byte strings such as b"HTTP\r\n", true, false, and None.
  • Names, fields, calls, method calls, indexing, and slicing: x, p.x, f(a), x.method(a), xs[i], xs[start:end], xs[:end], xs[start:], xs[:], and xs[..].
  • Array literals use either explicit elements ([1, 2, 3]) or copy-element repeats ([0; N]) in a fixed-size array context.
  • Method chains may continue on indented lines that start with . in expression-bearing statements such as let, var, assignment, return, and expression statements.
  • Generic calls require explicit type arguments: identity[i32](1) and result.unwrap_or[i32, bool](r, 0).
  • Struct literals and enum constructors use named payloads: Point(x=1, y=2), Ok(value=bytes).
  • Type constructors and associated calls are used for compiler-known SIMD forms such as Simd[i32; 4](...) and Simd[f64; 2].splat(0.0).
  • View expressions: view place and mut view place. &place and &mut place remain accepted compatibility syntax.
  • Raw extern views: raw ptr bytes, raw mut ptr buf, raw cstr "name", and raw cstr view.
  • Result propagation: try expr.
  • Casts: expr as Type.
  • Type tests: x is None, x is not None, x is i32, x is not Point.

Operators

Precedence is conventional:

  • Unary: -x, not x, ~x.
  • Multiplicative: *, /, %.
  • Additive: +, -.
  • Shifts: <<, >>.
  • Bitwise: &, ^, |.
  • Comparisons: <, <=, >, >=, ==, !=.
  • Boolean: and, or.

Integer and float arithmetic require matching operand types; numeric literals adapt to an expected type and otherwise default to i32 for integers and f64 for floats. Scalar integer +, -, *, and unary - wrap in the target integer width. % is scalar integer remainder, not Euclidean modulo; for non-trapping signed cases, a % b == a - (a / b) * b. Signed division and remainder trap on divisor zero and MIN / -1 or MIN % -1; unsigned division and remainder trap on divisor zero. % is not defined for floats or SIMD. Overshifts trap deterministically unless the checker/backend proves the shift amount is in range. Simd[f32; N] and Simd[f64; N] support lane-wise +, -, *, /, and comparisons. Simd[u8; N], Simd[i32; N], and Simd[u32; N] support wrapping lane-wise +, -, *, bitwise &, |, ^, and comparisons using unsigned u8, signed i32, or unsigned u32 ordering. .extract(index) returns one scalar lane and traps with the standard array-oob path when index >= N; float .reduce_add() returns a scalar left-to-right lane sum with default IEEE behavior and no fast-math flags. Comparison results are Mask[N]; use .any(), .all(), .to_bits(), or .select(...) instead of treating a mask as a scalar boolean or comparing masks directly. Const items support f32 and f64 in the same pure scalar expression subset as integers and bools. Float const arithmetic folds in the annotated target width and preserves default IEEE-style results such as nan, inf, and signed zero. Fast-math flags are not exposed in source.

Standard Library Surface

std is ordinary source using the same module visibility model as user code. Public APIs are exported from modules such as std.result, std.ascii, std.bytes, std.io, std.fs, std.process, std.cstring, std.time, std.fmt, std.math, std.bits, std.net.tcp, std.net.reactor, and std.time.reactor. std.sys is an internal export(package) unsafe capsule for std modules, not a project-code API. See docs/std-public-api.md for the current exported std surface, including std error-code conventions and borrowed error rendering helpers.

Current Rust-Shaped Syntax Worth Reviewing

  • let mut name = expr remains accepted for compatibility, but examples should prefer var name = expr for mutable locals.
  • &T, &mut T, &place, and &mut place remain accepted compatibility syntax. User-facing code should prefer view T, mut view T, view place, and mut view place.
  • *const T, *mut T, raw ptr, and raw mut ptr are intentionally explicit for FFI. The current unsafe model is narrow: std/sys capsules and raw extern-call authority only.
  • Explicit cleanup ... clauses expose the current compiler model. use resource blocks improve common cleanup ergonomics while still lowering through checked defer facts.
  • expr as Type is compact and familiar, but all casts must remain explicit. Integers and floats can be cast explicitly; integer-to-float casts round directly to the target float width, and float-to-integer casts truncate toward zero, map NaN to 0, and saturate out-of-range values.
  • Result[T, E], Ok(value=...), and Err(error=...) are clear but verbose. Future sugar could shorten enum construction without changing Result semantics.