so... jai :D
This commit is contained in:
agra
853
specs.md
Normal file
853
specs.md
Normal file
@@ -0,0 +1,853 @@
|
||||
# sx language specification
|
||||
|
||||
## 1. Lexical Structure
|
||||
|
||||
### Comments
|
||||
Line comments start with `//` and extend to end of line.
|
||||
```sx
|
||||
// this is a comment
|
||||
```
|
||||
|
||||
### Identifiers
|
||||
- Lowercase or mixed-case for variables, functions: `x`, `compute`, `main`
|
||||
- UPPER_SNAKE_CASE for constants: `SOME_INT`, `SOME_STR`
|
||||
- PascalCase for types: `Foo`
|
||||
|
||||
### Literals
|
||||
|
||||
| Kind | Examples | Type |
|
||||
|-----------|---------------------|---------|
|
||||
| Integer | `0`, `42`, `0xFF`, `0b1010` | `s32` |
|
||||
| Float | `0.3`, `0.9` | `f32` |
|
||||
| String | `"Hello"`, `"z: {z}"` | `string` |
|
||||
| Boolean | `true`, `false` | `bool` |
|
||||
| Enum | `.variant1` | inferred from context |
|
||||
| Undefined | `---` | context-dependent |
|
||||
|
||||
### Keywords
|
||||
`if`, `else`, `then`, `while`, `break`, `continue`, `true`, `false`, `enum`, `struct`, `union`, `case`, `return`, `defer`, `xx`, `and`, `or`
|
||||
|
||||
### Operators
|
||||
|
||||
| Operator | Meaning |
|
||||
|----------|------------------|
|
||||
| `+` | addition |
|
||||
| `-` | subtraction / negation |
|
||||
| `*` | multiplication |
|
||||
| `/` | division |
|
||||
| `==` | equality |
|
||||
| `!=` | inequality |
|
||||
| `<` | less than |
|
||||
| `>` | greater than |
|
||||
| `<=` | less or equal |
|
||||
| `>=` | greater or equal |
|
||||
| `and` | logical AND (short-circuit) |
|
||||
| `or` | logical OR (short-circuit) |
|
||||
| `+=` | add-assign |
|
||||
| `-=` | sub-assign |
|
||||
| `*=` | mul-assign |
|
||||
| `/=` | div-assign |
|
||||
|
||||
### Delimiters and Punctuation
|
||||
|
||||
| Token | Meaning |
|
||||
|--------|--------------------------------------|
|
||||
| `::` | constant binding / definition |
|
||||
| `:=` | variable binding (mutable, inferred) |
|
||||
| `:` | type annotation |
|
||||
| `=` | assignment (in typed var decl) |
|
||||
| `;` | statement terminator |
|
||||
| `,` | separator |
|
||||
| `.` | field access / enum literal prefix |
|
||||
| `->` | return type annotation |
|
||||
| `=>` | lambda arrow |
|
||||
| `$` | generic type parameter introduction |
|
||||
| `---` | undefined value |
|
||||
| `()` | grouping / params |
|
||||
| `{}` | blocks / bodies |
|
||||
|
||||
---
|
||||
|
||||
## 2. Type System
|
||||
|
||||
### Primitive Types
|
||||
- `s1`..`s64` — signed integers (1 to 64 bits). `s32` is the default for integer literals.
|
||||
- `u1`..`u64` — unsigned integers (1 to 64 bits).
|
||||
- `f32` — 32-bit floating point
|
||||
- `f64` — 64-bit floating point
|
||||
- `bool` — boolean (`true` / `false`)
|
||||
- `string` — string of characters
|
||||
- `Any` — type-erased value, represented as `{ i32, i64 }` (type tag + payload). Used for variadic arguments and runtime type dispatch.
|
||||
- `Type` — compile-time type value. At runtime, represented as an `i32` type tag (same tag space as `Any`).
|
||||
|
||||
### Enum Types
|
||||
User-defined sum types with named variants.
|
||||
```sx
|
||||
Foo :: enum {
|
||||
variant1;
|
||||
variant2;
|
||||
}
|
||||
```
|
||||
Variants are referenced with dot-prefix syntax: `.variant1`
|
||||
|
||||
### Struct Types
|
||||
User-defined product types with named fields.
|
||||
```sx
|
||||
Vec4 :: struct {
|
||||
x, y, z, w: f32;
|
||||
}
|
||||
```
|
||||
Fields are declared as `name1, name2: type;` (comma-separated names sharing a type, semicolon-terminated).
|
||||
|
||||
#### Field Defaults
|
||||
Fields may have default values. Fields without an explicit default have a zero-value default. `---` marks a field as explicitly undefined.
|
||||
```sx
|
||||
Foo :: struct {
|
||||
a : u2; // default is 0
|
||||
b : u8 = 42; // default is 42
|
||||
c : u8 = ---; // default is undefined
|
||||
}
|
||||
```
|
||||
|
||||
#### Struct Literals
|
||||
```sx
|
||||
// Positional (with type annotation — type inferred from annotation)
|
||||
v1 : Vec4 = .{ 1, 2, 3, 0 };
|
||||
|
||||
// Positional (with type prefix)
|
||||
v2 := Vec4.{ 4, 1, 1, 3 };
|
||||
|
||||
// Named fields (any order)
|
||||
v3 := Vec4.{ w=0, x=2, y=3, z=4 };
|
||||
|
||||
// Mixed named + shorthand (bare identifier = field name matches variable name)
|
||||
z := 5.0;
|
||||
w := 6.0;
|
||||
v4 := Vec4.{ y=3, x=9, w, z };
|
||||
```
|
||||
|
||||
#### Field Access and Assignment
|
||||
```sx
|
||||
v1.x // read field x of struct v1
|
||||
v1.x = 3.0; // assign to field x of struct v1
|
||||
```
|
||||
|
||||
#### Struct Interpolation
|
||||
Struct values in string interpolation print as `TypeName{field:value, ...}`:
|
||||
```sx
|
||||
print("{v1}"); // Vec4{x:1.0, y:2.0, z:3.0, w:0.0}
|
||||
```
|
||||
|
||||
### Union Types (Tagged Unions)
|
||||
Sum types where each variant can carry typed data or be void. Internally represented as `{ i32, [max_payload_size x i8] }`.
|
||||
|
||||
#### Declaration
|
||||
```sx
|
||||
Shape :: union {
|
||||
circle: f32; // typed variant
|
||||
rect: s32; // typed variant
|
||||
none; // void variant
|
||||
}
|
||||
```
|
||||
|
||||
#### Construction
|
||||
```sx
|
||||
s :Shape = .circle(3.14); // inferred from context
|
||||
s = .none; // void variant (enum literal syntax)
|
||||
s = Shape.rect(42); // explicit prefix
|
||||
```
|
||||
|
||||
#### Payload Access
|
||||
```sx
|
||||
r := s.circle; // load payload as f32 (undefined behavior if wrong variant active)
|
||||
```
|
||||
|
||||
#### Pattern Matching
|
||||
```sx
|
||||
if s == {
|
||||
case .circle: print("circle\n");
|
||||
case .rect: print("rect\n");
|
||||
case .none: print("none\n");
|
||||
}
|
||||
```
|
||||
|
||||
#### Union Interpolation
|
||||
Union values in string interpolation print as `<TypeName tag=N>`:
|
||||
```sx
|
||||
print("{s}"); // <Shape tag=0>
|
||||
```
|
||||
|
||||
### Array Types
|
||||
Fixed-size arrays with element type and length.
|
||||
```sx
|
||||
buffer : [5]f32 = .[0, 2, 3.5, 4, 0];
|
||||
val := buffer[2]; // 3.5
|
||||
```
|
||||
|
||||
### Vector Types (SIMD)
|
||||
LLVM SIMD vectors, parameterized by length and element type.
|
||||
```sx
|
||||
v := vec3(1, 3, 2); // Vector(3, f32)
|
||||
```
|
||||
|
||||
**Arithmetic**: Element-wise `+`, `-`, `*`, `/` on vectors of same dimensions.
|
||||
```sx
|
||||
add := v1 + v2; // element-wise addition
|
||||
```
|
||||
|
||||
**Scalar broadcast**: Scalar operands are broadcast to match the vector.
|
||||
```sx
|
||||
scaled := v * 2.0; // [2.0, 6.0, 4.0]
|
||||
```
|
||||
|
||||
**Negation**: Unary `-` negates each element.
|
||||
```sx
|
||||
neg := -v; // [-1.0, -3.0, -2.0]
|
||||
```
|
||||
|
||||
**Element access**: `.x`, `.y`, `.z`, `.w` (aliases `.r`, `.g`, `.b`, `.a`) extract single components.
|
||||
```sx
|
||||
v.x // first element
|
||||
v.z // third element
|
||||
```
|
||||
|
||||
**Index access**: `v[i]` extracts by index.
|
||||
```sx
|
||||
v[0] // first element
|
||||
```
|
||||
|
||||
**Built-in `sqrt`**: Calls LLVM `llvm.sqrt.f32`/`.f64` intrinsic.
|
||||
```sx
|
||||
s := sqrt(9.0); // 3.0
|
||||
```
|
||||
|
||||
### Function Types
|
||||
Expressed as `(param_types) -> return_type`.
|
||||
A function with no return type annotation returns void.
|
||||
```sx
|
||||
// type is (s32) -> s32
|
||||
compute :: (x: s32) -> s32 { x * x; }
|
||||
|
||||
// type is () -> void
|
||||
main :: () { }
|
||||
```
|
||||
|
||||
### Type Aliases
|
||||
A name bound to an existing type.
|
||||
```sx
|
||||
SOME_TYPE :: f64;
|
||||
```
|
||||
|
||||
### Generic Functions (Monomorphization)
|
||||
Functions can be parameterized over types using `$T` syntax. The `$` prefix introduces a type parameter; subsequent uses of the name reference it.
|
||||
```sx
|
||||
sum :: (a: $T, b: T) -> T {
|
||||
return a + b;
|
||||
}
|
||||
```
|
||||
- `$T` in a parameter type **introduces** type parameter `T`
|
||||
- Bare `T` (without `$`) **references** the introduced type parameter
|
||||
- At call sites, type arguments are **inferred** from actual argument types:
|
||||
```sx
|
||||
sum(40, 2) // T = s32
|
||||
sum(1.5, 2.5) // T = f32
|
||||
```
|
||||
- Each unique set of concrete types produces a **separate specialized function** (monomorphization)
|
||||
- Multiple type parameters are supported: `(a: $T, b: $U) -> T`
|
||||
|
||||
### Variadic Functions
|
||||
Functions can accept a variable number of arguments using `..Type` syntax:
|
||||
```sx
|
||||
print :: (fmt: string, args: ..Any) { ... }
|
||||
```
|
||||
- `..Any` means zero or more arguments, each boxed into `Any` (type tag + payload)
|
||||
- The variadic parameter must be the last parameter
|
||||
- At call sites, variadic arguments are automatically boxed: `print("x={}, y={}\n", x, y)`
|
||||
- Inside the function body, `args` is accessed as a slice-like sequence
|
||||
|
||||
### Type Inference
|
||||
- `::` bindings infer type from the right-hand side
|
||||
- `:=` bindings infer type from the right-hand side
|
||||
- Explicit annotation overrides inference: `NAME : f64 : 0.9;`
|
||||
- Integer literals default to `s32`
|
||||
- Float literals default to `f32`
|
||||
- Enum literals (`.variant`) infer their enum type from context (expected type)
|
||||
|
||||
### Type Conversions
|
||||
|
||||
**Implicit (widening)** — allowed without annotation:
|
||||
- Integer to wider integer of same signedness (`u8` → `u16`, `s8` → `s32`)
|
||||
- Unsigned to strictly wider signed (`u8` → `s16`)
|
||||
- Any integer to any float (`u8` → `f32`, `s32` → `f64`)
|
||||
- Float to wider float (`f32` → `f64`)
|
||||
- Integer and float literals can convert to any numeric type implicitly
|
||||
|
||||
**Explicit (narrowing)** — requires `xx` prefix:
|
||||
- Integer to narrower integer (`s32` → `u8`)
|
||||
- Signed to unsigned (`s32` → `u32`)
|
||||
- Float to narrower float (`f64` → `f32`)
|
||||
- Float to any integer (`f64` → `u16`)
|
||||
- Unsigned to signed of same or narrower width (`u8` → `s8`)
|
||||
|
||||
The `xx` prefix operator marks an expression for auto-conversion to the expected type from context (assignment, declaration, argument, return):
|
||||
```sx
|
||||
large: f64 = 5999.5;
|
||||
x : u16 = xx large; // f64 → u16
|
||||
d : u8 = #run xx resolve(5); // s32 → u8 at compile time
|
||||
```
|
||||
|
||||
Using `xx` outside a typed context (where the target type is known) is a compile error.
|
||||
|
||||
---
|
||||
|
||||
## 3. Declarations
|
||||
|
||||
### Constant Binding (immutable)
|
||||
|
||||
```sx
|
||||
// inferred type
|
||||
NAME :: value;
|
||||
|
||||
// explicit type
|
||||
NAME : type : value;
|
||||
```
|
||||
|
||||
The `::` operator creates an immutable binding. The value is evaluated at compile time when possible.
|
||||
|
||||
Examples:
|
||||
```sx
|
||||
SOME_INT :: 0; // s32
|
||||
SOME_STR :: "Hello"; // string
|
||||
SOME_FLOAT :: 0.3; // f32
|
||||
SOME_DOUBLE : f64 : 0.9; // f64 (explicit)
|
||||
SOME_FUNC :: () => 42; // () -> s32
|
||||
SOME_TYPE :: f64; // type alias
|
||||
```
|
||||
|
||||
### Variable Binding (mutable)
|
||||
|
||||
```sx
|
||||
// inferred type
|
||||
name := value;
|
||||
|
||||
// explicit type
|
||||
name : type = value;
|
||||
|
||||
// default-initialized (type required)
|
||||
name : type;
|
||||
|
||||
// undefined (type required)
|
||||
name : type = ---;
|
||||
```
|
||||
|
||||
The `:=` operator creates a mutable binding. The type is inferred unless explicitly annotated.
|
||||
|
||||
`name : type;` initializes using the type's defaults: zero for primitives, per-field defaults for structs (see Field Defaults).
|
||||
|
||||
`name : type = ---;` leaves the value undefined (uninitialized memory). Reading before writing is undefined behavior.
|
||||
|
||||
Examples:
|
||||
```sx
|
||||
x := 42; // s32, mutable
|
||||
x := if true then 1 else 2;
|
||||
z : Foo = .variant2; // Foo, mutable, explicit type
|
||||
a : Foo; // Foo, default-initialized (a=0, b=42, c=undef)
|
||||
b : Foo = ---; // Foo, entirely undefined
|
||||
```
|
||||
|
||||
### Function Definition
|
||||
|
||||
```sx
|
||||
name :: (params) -> return_type {
|
||||
body
|
||||
}
|
||||
```
|
||||
|
||||
- Parameters: `name: type` separated by commas
|
||||
- Return type: `-> type` (omit for void)
|
||||
- Body: block of statements; last expression is the implicit return value
|
||||
- No `return` keyword needed (last expression = return value)
|
||||
|
||||
Examples:
|
||||
```sx
|
||||
compute :: (x: s32) -> s32 {
|
||||
x * x;
|
||||
}
|
||||
|
||||
main :: () {
|
||||
// void return, no -> annotation
|
||||
}
|
||||
|
||||
// Bare-block shorthand (equivalent to no-arg void function):
|
||||
main :: {
|
||||
// same as main :: () { ... }
|
||||
}
|
||||
```
|
||||
|
||||
### Enum Definition
|
||||
|
||||
```sx
|
||||
Name :: enum {
|
||||
variant1;
|
||||
variant2;
|
||||
}
|
||||
```
|
||||
|
||||
Defines a new enum type with the given variants. Trailing comma is allowed.
|
||||
|
||||
---
|
||||
|
||||
## 4. Expressions
|
||||
|
||||
Everything in `sx` is expression-oriented where possible.
|
||||
|
||||
### Operator Precedence
|
||||
|
||||
| Prec | Operators | Notes |
|
||||
|------|-----------|-------|
|
||||
| 6 (highest) | `*`, `/` | multiplication, division |
|
||||
| 5 | `+`, `-` | addition, subtraction |
|
||||
| 4 | `<`, `<=`, `>`, `>=`, `==`, `!=` | comparisons (chainable) |
|
||||
| 2 | `and` | logical AND (short-circuit) |
|
||||
| 1 (lowest) | `or` | logical OR (short-circuit) |
|
||||
|
||||
### Arithmetic
|
||||
Standard infix: `+`, `-`, `*`, `/` with usual precedence (`*`/`/` before `+`/`-`).
|
||||
```sx
|
||||
x * x
|
||||
x + 2
|
||||
```
|
||||
|
||||
### Chained Comparisons
|
||||
Comparison operators can be chained. Each operand is evaluated exactly once.
|
||||
```sx
|
||||
0 <= x <= 100 // equivalent to: 0 <= x and x <= 100
|
||||
1000 > x >= -100 // equivalent to: 1000 > x and x >= -100
|
||||
a == b == c // equivalent to: a == b and b == c
|
||||
```
|
||||
Mixed operators are allowed: `a < b <= c > d` means `a < b and b <= c and c > d`.
|
||||
|
||||
### Logical Operators
|
||||
`and` and `or` are short-circuit boolean operators. The right operand is not evaluated if the left operand determines the result.
|
||||
```sx
|
||||
if 0 <= x <= 100 and 0 <= y <= 100 {
|
||||
print("contained");
|
||||
}
|
||||
```
|
||||
|
||||
### If Expression (inline form)
|
||||
```sx
|
||||
if condition then consequent else alternate
|
||||
```
|
||||
Both branches are single expressions. The whole form produces a value.
|
||||
```sx
|
||||
x := if true then 1 else 2;
|
||||
```
|
||||
The `else` branch is optional. Without it, the form is a statement (no value):
|
||||
```sx
|
||||
if i == 2 then continue;
|
||||
if done then break;
|
||||
if err then return;
|
||||
```
|
||||
|
||||
### If Expression (block form)
|
||||
```sx
|
||||
if condition {
|
||||
stmts
|
||||
} else {
|
||||
stmts
|
||||
}
|
||||
```
|
||||
Each branch is a block. The last expression in each block is the branch's value. Can be used inline within other expressions:
|
||||
```sx
|
||||
y := x + if false {
|
||||
7;
|
||||
} else {
|
||||
12;
|
||||
};
|
||||
```
|
||||
|
||||
### Pattern Matching
|
||||
```sx
|
||||
if subject == {
|
||||
case pattern: body
|
||||
case pattern: body
|
||||
else: body // optional default arm
|
||||
}
|
||||
```
|
||||
Matches `subject` against each `case`. Patterns can be:
|
||||
- **Enum literals**: `.variant` — matches a specific enum variant.
|
||||
- **Integer/bool literals**: `42`, `true` — matches a specific value.
|
||||
- **Type categories**: `struct`, `enum`, `union` — matches all types in that category (used with `type_of` values).
|
||||
|
||||
`break` exits a case arm without producing a value. The optional `else:` arm matches when no `case` pattern matches.
|
||||
```sx
|
||||
if z == {
|
||||
case .variant1: break;
|
||||
case .variant2:
|
||||
print("z: {z}");
|
||||
else:
|
||||
print("unknown");
|
||||
}
|
||||
```
|
||||
|
||||
#### Type Category Matching
|
||||
When switching on a `Type` value (from `type_of`), category keywords match all registered types of that category:
|
||||
```sx
|
||||
type := type_of(val);
|
||||
if type == {
|
||||
case int: result = int_to_string(xx val);
|
||||
case struct: result = struct_to_string(cast(type) val);
|
||||
case enum: result = enum_to_string(cast(type) val);
|
||||
}
|
||||
```
|
||||
Available categories: `int`, `float`, `bool`, `string`, `struct`, `enum`, `union`.
|
||||
|
||||
Inside a category arm, `cast(type) val` performs **runtime generic dispatch**: the compiler generates a switch over all types in the category, monomorphizing the callee for each concrete type.
|
||||
|
||||
### While Loop
|
||||
```sx
|
||||
while condition {
|
||||
body
|
||||
}
|
||||
```
|
||||
Repeats `body` as long as `condition` is true. `break;` exits the loop. `continue;` skips to the next iteration.
|
||||
```sx
|
||||
i := 0;
|
||||
while i < 10 {
|
||||
i += 1;
|
||||
if i == 5 { continue; }
|
||||
if i == 8 { break; }
|
||||
print("{i}\n");
|
||||
}
|
||||
```
|
||||
|
||||
### For Loop
|
||||
```sx
|
||||
for iterable {
|
||||
// `it` is the current element
|
||||
// `it_index` is the current index (s32)
|
||||
print("{it}\n");
|
||||
}
|
||||
```
|
||||
Iterates over arrays and slices. The loop body has two implicit variables:
|
||||
- `it` — the current element value
|
||||
- `it_index` — the current index (s32, starting at 0)
|
||||
|
||||
`break;` exits the loop. `continue;` skips to the next iteration.
|
||||
```sx
|
||||
arr : [5]s32 = .[1, 2, 3, 4, 5];
|
||||
for arr {
|
||||
if it_index == 2 { continue; }
|
||||
print("{it}\n");
|
||||
}
|
||||
```
|
||||
|
||||
### Lambda
|
||||
```sx
|
||||
(params) => expr
|
||||
(params) -> return_type => expr
|
||||
```
|
||||
Anonymous function. Produces a function value. Supports the same parameter features as named functions: `$` generic type params, `..` variadic params, and optional return type annotation.
|
||||
```sx
|
||||
SOME_FUNC :: () => 42; // () -> s32
|
||||
double :: (x: $T) -> T => x + x; // generic lambda with return type
|
||||
```
|
||||
|
||||
### Function Call
|
||||
```sx
|
||||
callee(args)
|
||||
```
|
||||
```sx
|
||||
compute(6)
|
||||
print("hello")
|
||||
```
|
||||
|
||||
### Field Access
|
||||
```sx
|
||||
object.field
|
||||
```
|
||||
Used for module access (`std.print`) and struct member access.
|
||||
|
||||
### Enum Literal
|
||||
```sx
|
||||
.variant_name
|
||||
```
|
||||
The enum type is inferred from context (expected type from declaration or parameter).
|
||||
|
||||
### String Interpolation
|
||||
Curly braces inside string literals interpolate expressions:
|
||||
```sx
|
||||
"z: {z}"
|
||||
```
|
||||
The expression inside `{}` is evaluated and formatted according to its type:
|
||||
- `s32` — decimal integer
|
||||
- `f64` — decimal float
|
||||
- `string` — as-is
|
||||
|
||||
---
|
||||
|
||||
## 5. Statements
|
||||
|
||||
Statements are terminated by `;`.
|
||||
|
||||
- **Declaration**: `name :: value;` / `name := value;`
|
||||
- **Assignment**: `name = value;` / `name += value;` (and other compound assignments). Also supports field targets: `obj.field = value;`
|
||||
- **Expression statement**: `expr;` — evaluates the expression (last in a block = return value)
|
||||
- **Return**: `return expr;` — returns from the enclosing function with the given value. `return;` returns void.
|
||||
- **Break**: `break;` — exits a match arm or while loop
|
||||
- **Continue**: `continue;` — skips to the next iteration of a while loop
|
||||
- **Defer**: `defer expr;` — defers execution of `expr` until the enclosing block exits (LIFO order)
|
||||
|
||||
---
|
||||
|
||||
## 6. Blocks, Scoping, and Implicit Returns
|
||||
|
||||
A block `{ ... }` contains zero or more statements. The last expression in a block is its value (implicit return).
|
||||
|
||||
In function bodies, the last expression becomes the return value:
|
||||
```sx
|
||||
compute :: (x: s32) -> s32 {
|
||||
x * x; // this is returned
|
||||
}
|
||||
```
|
||||
|
||||
### Scope Blocks
|
||||
|
||||
Bare blocks can be used as statements to introduce a new lexical scope. Variables declared inside a scope block are local to that block. No trailing `;` is required.
|
||||
|
||||
```sx
|
||||
main :: {
|
||||
x := 42;
|
||||
{
|
||||
x := 6; // shadows outer x
|
||||
print("inner: {x}"); // prints 6
|
||||
}
|
||||
print("outer: {x}"); // prints 42
|
||||
}
|
||||
```
|
||||
|
||||
### Variable Shadowing
|
||||
|
||||
A variable declaration (`name :=`) inside an inner scope shadows any variable with the same name from outer scopes. The outer variable is restored when the inner scope exits.
|
||||
|
||||
### Defer
|
||||
|
||||
`defer expr;` schedules `expr` to execute when the enclosing scope block exits. Multiple defers in the same scope execute in reverse order (LIFO).
|
||||
|
||||
```sx
|
||||
{
|
||||
defer print("second");
|
||||
defer print("first");
|
||||
}
|
||||
// prints: first, then second
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Built-in Functions
|
||||
|
||||
Built-in functions are declared in `std.sx` with the `#builtin` suffix, which tells the compiler to generate the implementation internally rather than looking for a function body.
|
||||
|
||||
### I/O
|
||||
- `write(str: string) -> void` — write a string to standard output
|
||||
- `print(fmt: string, args: ..Any)` — formatted print. Parses `{}` placeholders in the format string and substitutes arguments. When all argument types are statically known, the compiler specializes the call at compile time (no `Any` boxing).
|
||||
|
||||
### Math
|
||||
- `sqrt(x: $T) -> T` — square root (maps to LLVM intrinsic)
|
||||
|
||||
### Memory
|
||||
- `alloc(size: s32) -> string` — allocate `size` bytes of memory, returned as a string slice
|
||||
- `size_of($T: Type) -> s32` — size of type `T` in bytes
|
||||
|
||||
### Type Introspection
|
||||
- `type_of(val: $T) -> Type` — returns the runtime type tag of a value
|
||||
- `type_name($T: Type) -> string` — returns the name of type `T` as a string (e.g., `"Point"`)
|
||||
- `field_count($T: Type) -> s32` — returns the number of fields (struct), variants (enum), or elements (vector) in type `T`
|
||||
- `field_name($T: Type, idx: s32) -> string` — returns the name of the `idx`-th field (struct) or variant (enum) of type `T`
|
||||
- `field_value(s: $T, idx: s32) -> Any` — returns the `idx`-th field (struct) or element (vector) of `s`, boxed as `Any`
|
||||
|
||||
### Type Conversion
|
||||
- `cast(Type) expr` — prefix operator that converts `expr` to `Type`. Examples: `cast(s32) 3.14`, `cast(f64) n`. When `Type` is a runtime `Type` value inside a type-category match arm, the compiler generates a dispatch switch over all types in the category, monomorphizing the callee for each concrete type.
|
||||
|
||||
### Vectors
|
||||
- `Vector($N: int, $T: Type) -> Type` — returns an LLVM vector type of `N` elements of type `T`
|
||||
|
||||
---
|
||||
|
||||
## 8. Compile-time Evaluation
|
||||
|
||||
### `#run` Directive
|
||||
|
||||
`#run expr` evaluates `expr` at compile time using lazy JIT execution. It can appear in two contexts:
|
||||
|
||||
**Compile-time constants** — bind a compile-time value to a name:
|
||||
```sx
|
||||
compute :: (x: s32) -> s32 { x * x; }
|
||||
x :: #run compute(5); // x = 25, evaluated at compile time
|
||||
```
|
||||
|
||||
Comptime globals are resolved lazily: the JIT executes only when the value is first referenced during code generation. Chained dependencies are resolved automatically.
|
||||
|
||||
**Side effects** — execute code at compile time for its side effects:
|
||||
```sx
|
||||
#run print("compiling...");
|
||||
```
|
||||
|
||||
### `#insert` Directive
|
||||
|
||||
`#insert expr;` evaluates `expr` at compile time to obtain a string, then parses and compiles that string as inline code at the insertion point.
|
||||
|
||||
```sx
|
||||
generate :: () -> string {
|
||||
return "print(\"hello from the other side\");";
|
||||
}
|
||||
|
||||
main :: () {
|
||||
#insert #run generate();
|
||||
// equivalent to: print("hello from the other side");
|
||||
}
|
||||
```
|
||||
|
||||
The inserted string must contain valid `sx` statements (including semicolons). The statements are parsed and compiled in the same scope as the `#insert` site.
|
||||
|
||||
---
|
||||
|
||||
## 9. Modules / Imports
|
||||
|
||||
### `#import` Directive
|
||||
|
||||
The `#import` directive brings declarations from another `.sx` file into the current file. Paths are resolved relative to the importing file's directory.
|
||||
|
||||
**Flat import** — splices all declarations from the imported file into the current scope:
|
||||
```sx
|
||||
#import "modules/std/math.sx";
|
||||
```
|
||||
|
||||
**Namespaced import** — wraps all declarations under a namespace name:
|
||||
```sx
|
||||
std :: #import "modules/std.sx";
|
||||
```
|
||||
|
||||
Namespaced declarations are accessed with dot notation:
|
||||
```sx
|
||||
std.print("hello");
|
||||
```
|
||||
|
||||
### Import Resolution
|
||||
|
||||
- Imports are resolved after parsing and before code generation.
|
||||
- Paths are relative to the directory of the file containing the `#import`.
|
||||
- Nested imports are supported (imported files may themselves contain `#import`).
|
||||
- Circular imports are detected and silently skipped (each file is imported at most once).
|
||||
- Generic functions in namespaced imports are supported (e.g., `std.mul(5, 2)` where `mul` is generic).
|
||||
|
||||
### Intra-module References
|
||||
|
||||
Functions within a namespaced import can call each other without the namespace prefix. When generating code for a namespaced module, unresolved function names are automatically tried with the namespace prefix.
|
||||
|
||||
### Example
|
||||
|
||||
```sx
|
||||
// modules/std/math.sx
|
||||
mul :: (base: $T, exp: T) -> T { base * exp; }
|
||||
|
||||
// modules/std/std.sx
|
||||
print :: (str: string) -> void #builtin;
|
||||
|
||||
// main.sx
|
||||
std :: #import "modules/std.sx";
|
||||
#import "modules/std/math.sx";
|
||||
|
||||
main :: () -> s32 {
|
||||
std.print("hello there");
|
||||
mul(5, 2);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Program Structure
|
||||
|
||||
A program is a sequence of top-level declarations and `#import` directives. Execution begins at `main`.
|
||||
|
||||
```sx
|
||||
main :: () {
|
||||
// entry point
|
||||
}
|
||||
```
|
||||
|
||||
`main` takes no arguments and returns void. The process exit code is 0 unless otherwise specified.
|
||||
|
||||
---
|
||||
|
||||
## 11. Grammar (informal)
|
||||
|
||||
```
|
||||
program = top_level*
|
||||
top_level = decl | import_decl
|
||||
import_decl = '#import' STRING ';'
|
||||
| IDENT '::' '#import' STRING ';'
|
||||
decl = const_decl | var_decl | fn_decl | enum_decl | struct_decl
|
||||
const_decl = IDENT '::' expr ';'
|
||||
| IDENT ':' type ':' expr ';'
|
||||
var_decl = IDENT ':=' expr ';'
|
||||
| IDENT ':' type '=' expr ';'
|
||||
| IDENT ':' type ';'
|
||||
fn_decl = IDENT '::' '(' params? ')' ('->' type)? block
|
||||
| IDENT '::' block
|
||||
enum_decl = IDENT '::' 'enum' '{' (IDENT ';')* '}'
|
||||
struct_decl = IDENT '::' 'struct' '{' field_group* '}'
|
||||
field_group = IDENT (',' IDENT)* ':' type ('=' expr)? ';'
|
||||
params = param (',' param)*
|
||||
param = IDENT ':' type
|
||||
block = '{' stmt* '}'
|
||||
stmt = decl | assignment ';' | return_stmt | defer_stmt | insert_stmt
|
||||
| break_stmt | continue_stmt | expr ';'
|
||||
return_stmt = 'return' expr? ';'
|
||||
break_stmt = 'break' ';'
|
||||
continue_stmt = 'continue' ';'
|
||||
defer_stmt = 'defer' expr ';'
|
||||
insert_stmt = '#insert' expr ';'
|
||||
assignment = lvalue ('=' | '+=' | '-=' | '*=' | '/=') expr
|
||||
lvalue = IDENT | postfix '.' IDENT
|
||||
expr = if_expr | match_expr | while_expr | for_expr | lambda | binary
|
||||
while_expr = 'while' expr block
|
||||
for_expr = 'for' expr block
|
||||
binary = unary (binop unary)*
|
||||
unary = ('-' | '!' | 'xx' | 'cast' '(' type ')') postfix
|
||||
| postfix
|
||||
postfix = primary ('(' args? ')' | '.' IDENT | '.{' field_init_list '}')*
|
||||
primary = INT | HEX_INT | BIN_INT | FLOAT | STRING | BOOL | IDENT | '---'
|
||||
| '.' IDENT | '.' '{' field_init_list '}'
|
||||
| '(' expr ')' | block | '#run' expr
|
||||
field_init_list = field_init (',' field_init)*
|
||||
field_init = IDENT '=' expr | IDENT | expr
|
||||
if_expr = 'if' expr 'then' expr ('else' expr)?
|
||||
| 'if' expr block ('else' block)?
|
||||
match_expr = 'if' expr '==' '{' case_arm* else_arm? '}'
|
||||
case_arm = 'case' pattern ':' (stmt* | 'break' ';')
|
||||
else_arm = 'else' ':' stmt*
|
||||
pattern = '.' IDENT | INT | BOOL | IDENT
|
||||
lambda = '(' params? ')' ('->' type)? '=>' expr
|
||||
args = expr (',' expr)*
|
||||
type = '$' IDENT | 's32' | 'f32' | 'f64' | 'bool' | 'string'
|
||||
| 'Any' | 'Type' | '..' type | '[' expr ']' type | IDENT
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. Open Questions
|
||||
|
||||
These are inferred gaps — things not shown in the readme that need decisions:
|
||||
|
||||
- **`return`**: Both `return expr;` and implicit return (last expression) are supported.
|
||||
- **Else in match**: Is there a default/else arm in pattern matching?
|
||||
- **Nested functions**: Can functions be defined inside other functions?
|
||||
- **Mutability of params**: Are function parameters immutable by default?
|
||||
- **Array/list types**: Not shown — deferred.
|
||||
- **Struct types**: Implemented — named struct types with positional/named/shorthand literals.
|
||||
- **Imports/modules**: `#import` directive supports flat and namespaced imports (see Section 8).
|
||||
- **Operator overloading**: Not shown — presumably no.
|
||||
- **Semicolons**: Required on all statements? What about the last expression in a block?
|
||||
- **Top-level expressions**: Are bare expressions allowed at the top level or only declarations?
|
||||
Reference in New Issue
Block a user