Surface Syntax

Status: in progress

This article covers surface syntax foundations. The dual-surface section (.cssl vs. .csl notation) will be expanded as spec content is exported from the compiler repo.

Sigil’s syntax is Rust-adjacent for the CPU-side semantics and adopts a more declarative style for GPU shaders. Both share the same type system and effect model.

Declarations

Functions

// Basic function
fn add(a: f32, b: f32) -> f32 {
    a + b
}

// With effect annotation
fn read_file(path: &str) -> Result<String> !io {
    // ...
}

// GPU shader (vertex)
#[shader(vertex)]
fn vs_main(v: Vertex) -> Vec4<Clip> !gpu {
    // ...
}

// Generic function with constraint
fn lerp<T: Differentiable>(a: T, b: T, t: f32) -> T {
    a * (1.0 - t) + b * t
}

Types

// Product type
struct Vertex {
    position: Vec3<World>,
    normal:   Vec3<World>,
    uv:       Vec2,
}

// Sum type
enum Shape {
    Sphere { center: Vec3<World>, radius: f32 },
    Box    { min: Vec3<World>, max: Vec3<World> },
    Plane  { normal: Vec3<World>, d: f32 },
}

// Newtype (phantom wrapper)
struct Meters(f32);
struct Pixels(f32);

Bindings

// Immutable (default)
let x: f32 = 3.14;

// Mutable
let mut count: u32 = 0;
count += 1;

// Destructuring
let Vec3 { x, y, z } = position;

// Type inference
let scale = 2.0;   // inferred: f32

Expressions

Blocks and returns

// Blocks are expressions
let value = {
    let a = compute_a();
    let b = compute_b();
    a + b   // last expression is the block's value
};

// Explicit return
fn early_out(n: i32) -> i32 {
    if n < 0 { return 0; }
    n * n
}

Pattern matching

match shape {
    Shape::Sphere { center, radius } => sdf_sphere(p, center, radius),
    Shape::Box    { min, max }       => sdf_box(p, min, max),
    Shape::Plane  { normal, d }      => sdf_plane(p, normal, d),
}

Closures

let square = |x: f32| x * x;

// With captured context and effect
let threshold = 0.5_f32;
let classify = |v: f32| !pure {
    if v > threshold { Class::High } else { Class::Low }
};

The two syntactic surfaces

Sigil has two syntactic surfaces that target different audiences:

Surface	File extension	Audience	Style
High-level	.cssl	Language users	Rust-like, inferred effects, full syntax sugar
Low-level / spec	.csl	Compiler contributors, spec authors	Dense, CSLv3-adjacent, explicit IR structure

As a language user, you write .cssl. The .csl notation appears in:

• Compiler internals (specs/*.csl)
• Spec source blocks in this KB
• Error messages from the type checker (sometimes)

You don’t need to read .csl to use Sigil. You do need it to understand the spec or contribute to the compiler.

See also

• §B.2 Type System — the full type lattice
• §B.3 Effect System — effect rows in detail
• Spec source: 09_SYNTAX.csl, 16_DUAL_SURFACE.csl