Skip to content

SYX Language Quick Reference ​

简体中文

Syntax and standard-library cheat sheet for .sy source authors. Aligned with current syx-parser / syx-semantic capabilities; toolchain usage in 9_UsageGuide.md.


Table of contents ​

  1. Type system
  2. Variables and entry point
  3. Control flow
  4. Functions and access control
  5. Modules
  6. Strings
  7. Arrays
  8. Error handling do/catch
  9. Optional null safety
  10. Data class
  11. Extension
  12. Sealed class and switch
  13. Effects annotations
  14. Standard library File / Directory / HTTP
  15. Async / await (MVP)
  16. Borrowing and macros (Phase 7)
  17. CLI cheat sheet
  18. Diagnostic codes

Type system ​

Numeric types ​

TypeExamplesNotes
Int8 … Int6442i8, 1000i64Fixed-width signed integers
Int12842i128128-bit signed integer (Phase 38)
UInt8 … UInt64255u8Fixed-width unsigned integers
UInt1280xFFu128128-bit unsigned integer (Phase 38)
SIMD4<Int32>, etc.SIMD4.fromArray([1,2,3,4])Fixed-width SIMD vectors (Phase 38)
Int42Platform word signed integer (64-bit host → Int64, 32-bit → Int32)
UInt100uPlatform word unsigned integer
Float32 / Float3.14f3232-bit float
Float64 / Double3.1464-bit float (unsuffixed float literals default to Double)

Unsuffixed integer literals default to platform Int. Explicit suffixes (e.g. 42i8) pick fixed-width types.

Basic and collection types ​

TypeExamplesNotes
Booltrue / falseBoolean
String"hello"String
Array<T>[1, 2, 3]Dynamic array
Set<T>Set<Int>, assign [1,2,3] to SetDeduped set
[K: V] / Dictionary<K,V>["a": 1], [String: Int]Static dictionary (MVP keys must be String)
Objectlet o: Object = { "k": v }Dynamic heterogeneous bag (annotation required; unannotated dict → Dictionary)
T?nil / 42Optional type
Void—No return value

Type annotations: let x: Int = 10, let m: [String: Int] = ["a": 1], let s: Set<Int> = [1, 2, 3]

Note: SYX uses the func keyword and built-in print(). Prefer struct / class / enum (+ extension). public data class is removed (SA-2-04); non-public residual is for fixtures/@Codable only.


Variables and entry point ​

swift
var count = 0      // mutable
let name = "SYX"   // immutable
var x: Int = 10    // explicit type

func main() {      // program entry
    print("Hello")
}

Control flow ​

swift
// if — condition in parentheses
if (x > 0) {
    print("positive")
} else {
    print("non-positive")
}

// while — condition in parentheses
while (x > 0) {
    x = x - 1
}

// for-in — Array / String / readLines results
for item in [1, 2, 3] {
    print(item)
}
for ch in "abc" {
    print(ch)
}

// switch — colon after case; ranges and variants supported
switch value {
case 1:
    print("one")
case 0..<10:
    print("small")
default:
    print("other")
}
ConstructSyntax
if / whileCondition must be (expr)
for-infor name in iterable { }, no parentheses
switchcase pat: or default:; whole construct in { }
break / continueSupported

Functions and access control ​

swift
func add(a: Int, b: Int) -> Int {
    return a + b
}

public func exported() -> Int {
    return 1
}

internal func helper() -> Int {
    return 0
}

private func hidden() -> Int {
    return -1
}
ModifierVisibility
publicImportable across modules
internalWithin module (default)
privateFile/module private

Parameters: func f(a: Int, b: Int) — call f(a: 1, b: 2). No Swift-style _ label elision.


Modules ​

swift
// Math.sy
public func add(a: Int, b: Int) -> Int {
    return a + b
}

// main.sy
import Math

func main() {
    print(Math.add(1, 2))
}
RuleNotes
Importimport moduleName (name maps to .sy file or syx.toml dependency key)
ExportOnly public func callable from other modules
Cross-module internalCompile error S005
Project deps[dependencies] in syx.toml + syx add / syx update

Strings ​

swift
let name = "World"
print("Hello, \(name)!")                    // interpolation

"a,b,c".split(",")                          // → Array
"  hi  ".trim()
"ABC".lowercased() / "abc".uppercased()
"file.txt".hasPrefix("file")
"hello".substring(0, 3)                     // [start, end)
"foo".replacingOccurrences("bar", "foo")    // (new, old)
"abc123".matches("\\d+")                    // regex → Array
"text".count                               // character count
MethodReturns
.split(sep)Array
.matches(pattern)Array (match strings)
.replacingOccurrences(with, of)String

Arrays ​

swift
let nums = [10, 20, 30]
print(nums.count)

var sum = 0
for x in nums {
    sum = sum + x
}
MethodNotes
.countInt
.contains(item)Bool
.sorted()Array (ascending)
.reverse()Array
.joined(sep)String
.map / .filter / .reduce✅ Closures supported (see p4_hof.sy)

Set and Dictionary ​

swift
let scores: [String: Int] = { "a": 1, "b": 2 }
print(scores.count)          // 2

var tags: Set<Int> = [1, 2, 2, 3]
print(tags.count)            // 3 (deduped)
print(tags.insert(4))        // true (ADR-224 write-back)
print(tags.contains(4))      // true
print(scores.containsKey("a")) // true
TypeMethodsReturns
Set.count / .contains / .insert / .remove (mutations ADR-224); .union / .intersectionBool / Int
[String: V].count / .containsKey / .remove / .keys / .valuesSee stdlib

Ranges and readLine ​

swift
print((1..<10).contains(5))
let line = readLine()

Error handling do/catch ​

SYX uses Swift-shaped do { } catch (SA-2-01). Expression try / try? / try! call throws functions. Signatures use throws -> T.

swift
// statement block
do {
    File.write("/tmp/x.txt", "data")
    let content = File.read("/tmp/x.txt")
    print(content)
} catch (err) {
    print("failed")
}

// expression-level try
let text = try File.read(path)

Host functions (File, HTTP, etc.) raise VM exceptions on failure; catch handles them.


Optional null safety ​

swift
let a: Int? = nil
print(a ?? 99)              // nil coalescing

let b: Int? = 7
print(b!)                   // force unwrap; nil → R007

let s: String? = "hello"
print(s?.hasPrefix("he"))   // optional chain; nil short-circuits

if let y = b {               // bind when non-nil
    print(y)
}

guard let z = b else {       // failure → else branch
    return
}
print(z)
OperatorMeaning
T?Optional type
nilNull value
??Left if non-nil, else right
!Force unwrap
?.Optional member chain

Protocols and equality (Equatable / Hashable) ​

Built-in types automatically implement Equatable, Hashable, CustomStringConvertible, and CustomDebugStringConvertible (numeric types, Bool, String, Array, Set, Dictionary, Object).

Operator / memberMeaning
== / !=Structural equality (numeric promotion; deep collection equality)
=== / !==Identity equality (class instances compare __object_id; value types same as ==)
.descriptionUser-facing string
.debugDescriptionDebug string (with type prefix)
hash(into:)Built-in witness via Hasher host
TypeNotes
HasherHasher.newHasher() / Hasher.combine / Hasher.finalize
ObjectIdentifierHasher.objectId(obj)

Using == on types that are not Equatable → S016.


Struct (data carrier) ​

swift
struct Point {
    var x: Int
    var y: Int
}

func main() {
    let p = Point(x: 3, y: 4)
    print(p.x)
}

SA-2-04: public data class is rejected. Use struct / class / enum …: Error.

CapabilityStatus
Construct Type(x:a, y:b)✅
Field access p.x✅
Caseless enum namespace + static var✅ SA-2-03

Extension ​

swift
extension Int {
    func doubled() -> Int {
        return self + self
    }
}

func main() {
    print(5.doubled())   // desugar → Int_doubled(5)
}

Sealed class and switch ​

swift
sealed class Result {
    ok(value: Int)
    err(message: String)
}

func describe(r: Result) {
    switch r {
    case .ok(let x):
        print(x)
    case .err(let msg):
        print(msg)
    }
}

Variant definitions omit the case keyword; switch arms use .variant(let binding) forms (see 2_SyntaxAnalysis.md §5.5).

PatternExample
Integercase 42:
Half-open rangecase 0..<13:
Variantcase .ok(let x):

Extended syntax (§11 implemented) ​

swift
enum Result {
    ok(value: Int)
    err(msg: String)
}

class Greeter {
    var name: String
    init(name: String) { self.name = name }
    func hello() { print(self.name) }
}

class Counter: IteratorProto {
    func next() -> Int { return 1 }
}

actor Counter {
    var value: Int
    init(value: Int) { self.value = value }
    func increment() { self.value = self.value + 1 }
}

func id<T>(x: Int) -> Int { return x }  // monomorphized to id_Int

@available(iOS 13)
@Main
func app() { print("hi") }

let evens = [1,2,3].filter({ |x| x % 2 == 0 })
let sum = [1,2,3].reduce({ |a, b| a + b })

let base = 10
let mapped = [1].map({ |x| x + base })  // closure capture

throw "failed"
repeat { print(1) } while (false)
x += 1

See 2_SyntaxAnalysis.md §5 / §11.


Effects annotations ​

Function declarations may append requires Pure or requires IO after the return type; Pure functions must not perform I/O (including print, File/HTTP).

swift
func compute(x: Int) -> Int requires Pure {
    return x * 2
}

func loadConfig() -> String requires IO {
    return File.read("config.txt")
}

Violating Pure → compile-time error (syx-meta).


Standard library File / Directory / HTTP ​

Invoked via static type methods and instance methods (Host Functions).

File ​

MethodNotes
File.read(path)Read entire file → String
File.readLines(path)By line → Array
File.write(path, content)Write
File.append(path, content)Append
File.exists(path)→ Bool
File.delete(path)Delete
File.copy(from, to)Copy
File.move(from, to)Move

Directory ​

MethodNotes
Directory.create(path)Create directory
Directory.list(path)List entries → Array
Directory.exists(path)→ Bool

HTTP ​

Client uses reqwest (blocking + rustls) with HTTPS. See 11_NetworkStdlib.md.

MethodNotes
HTTP.fetch(url, options)Generic request (method / headers / body / query / timeout_ms)
HTTP.get(url)GET → response object
HTTP.post(url, body)POST; body String or dictionary
HTTP.put/patch/delete(url, body?)Matching HTTP verbs
HTTP.serve(addr, port, handler)Blocking HTTP server (handler function name)
HTTP.response(status, body)Build server response object
Response methodNotes
status()HTTP status code
ok()2xx → true
text() / body()Response body string
json()Parse JSON → object
header(name)Single response header
headers()All response headers

URL ​

MethodNotes
URL.parse(text)Parse → { href, protocol, host, port, path, query }
URL.encodeQuery(dict)Dictionary → query string
URL.build(base, path, query)Build URL
swift
import HTTP

do {
    let resp = HTTP.fetch("https://httpbin.org/get", { "timeout_ms": 10000 })
    if resp.ok() {
        print(resp.json())
    }
} catch (e) {
    print("network error")
}

Globals ​

NameNotes
print(expr)Write to stdout

Available: readLine() reads one line from stdin.
Not available: exit(), assert(), and similar globals.


Async / await (MVP) ​

swift
async func fetch() -> String {
    let resp = await HTTP.get("https://example.com")
    return "ok"
}

// Structured Task (thread-pool spawn today)
let t = Task {
    work()
}
__syx_task_join(t)

// Explicit parallelism
Task.detached {
    __syx_task_sleep(50)
}

// Detach with args (Concurrency or host)
__syx_task_detach("worker", [42])

syx.toml strict mode:

toml
[concurrency]
strict = true   # enable C001–C003 static checks
Host / APINotes
__syx_task_detach(name) / Concurrency.detach(name)Thread-pool detached task
__syx_task_detach(name, args)Spawn with arguments
__syx_task_join / cancel / sleepJoin / cancel / sleep
__syx_task_group_*TaskGroup create / add / wait (isolated by group id)
__syx_channel_create/send/recvPhase 8 async channel MVP (VM host)
__syx_channel_try_recvPhase 15 non-blocking recv (nil = empty) (p15_channel_try_recv.sy)
__syx_channel_create(cap) / __syx_channel_try_sendBounded channel + backpressure (ADR-267 / m3_a04_backpressure; full buffer trySend→false)
__syx_channel_select([...])Multi-arm select + RR fairness (ADR-268 / m3_a04_fairness; select-fair-v1:round-robin; leaf ADR-269)
Task { } / Task.detached { }Syntax sugar (generates __task_body_N)
LimitNotes
await state machineMulti-await functions insert __syx_async_state; await __syx_task_sleep lowered inside async
async letasync let x = f() → detach + later await join (p7_async_let.sy)
Scopeawait only inside async func
Lintasync function with no await → L005

Borrowing and macros (Phase 7) ​

Borrowing ​

swift
func bump(x: &mut Int) {
    x = x + 1
}

func read_only(x: &Int) -> Int {
    return x
}
RuleDiagnostic
At most one active &mut T per scopeS011
Use after moveS011 (moved value)

Fixtures: p6_borrow_*, p7_borrow_mut.sy, p7_borrow_mut_fail.sy.

Macros ​

swift
#if(DEBUG, print("debug on"))
#for(3, print("x"))
#assert(x > 0)
#macro twice(x) { print(x); print(x) }
let s = #stringify(1 + 1)
@Equatable
data class P(x: Int, y: Int)

Expanded by syx-macro::expand_module; depth exceeded → E002. See books/language-guide/19-macros.md.


CLI cheat sheet ​

bash
cargo build --release              # build syx
syx run file.sy                   # compile and run on VM (full stdlib)
syx run .                          # project (syx.toml)
syx check .                        # type-check only
syx build --native .               # MIR → app (LLVM sole; --object for .o only)
syx build --wasm .                 # MIR → main.wasm (experimental)
syx emit file.sy --format syxbc   # VM bytecode text → file.syxbc
syx emit . --format all -o emit/ # write six IR/bytecode artifacts to emit/
syx run file.sy                   # single MIR path (Phase 12 default)
syx format . / syx lint . / syx doc .
syx test .                         # run tests/**/*.sy
syx repl

Diagnostic codes ​

Lexer / parser ​

CodeMeaning
L001Unclosed string / invalid character (lexer)
P001Unexpected token / syntax error

Semantic (compile time) ​

CodeMeaning
S001Undefined type
S002Undefined identifier
S003Type mismatch
S004Duplicate declaration
S005Invalid access level (cross-module internal)
S006Protocol not satisfied (e.g. Iterator missing next())
S007Non-exhaustive enum switch (by case name set)
S008Cross-actor direct instance field access
S009Unknown protocol constraint in where clause
S010Generic argument fails where protocol constraint
S011Borrow conflict / use-after-move

Concurrency (strict or @concurrent context) ​

CodeMeaning
C001Call @MainActor function outside MainActor (main is implicit MainActor)
C002Cross-actor synchronous method call
C003Task.detached / detach captures non-Sendable type (strict or module has class)
C004Task cancelled
C005Task channel closed
C006Actor mailbox closed
C009Actor sync same-instance reentrancy rejected (serial-no-reenter)
C010Channel closed (send after close)

Runtime ​

CodeMeaning
R001File read failure / registry semver conflict
R002File/directory write failure
R003HTTP request failure
R004HTTP POST failure
R005JSON parse failure
R006Invalid regex
R007Force unwrap nil
R011HTTP request timeout
R012HTTP serve bind failure
R013URL parse failure

Lint (syx lint) ​

CodeRule summary
L001–L012Naming, empty bodies, public return types, async/await, line width, etc.

Main differences from Swift (cheat sheet) ​

SwiftSYX
do { try } catchdo { try … } catch { } (SA-2-01)
if cond {if (cond) { (parens optional in many forms)
struct as data carrierstruct / class (public data class removed)
import Moduleimport Math (PascalCase embedded stdlib module names)
print(_:separator:)print(expr)
@mainfunc main()
throws -> Tthrows -> T (SA-2-05)

Ecosystem and IDE (Phase 11 / SYX 4.5) ​

  • Single MIR path: user modules always go through MIR (Phase 12; SYX_USE_MIR removed)
  • LSP v4: code actions, semantic tokens, inlay hints
  • Embed: compile_and_run_embedded (see ADR-003)
Env var / pathNotes
SYX_REGISTRYProduction registry default URL (https://packages.sy.dev); overrides [registry].default
SYX_REGISTRY_STAGINGStaging registry URL when no [registry].default
SYX_PUBLISHER_SIGNING_KEYPublish: 32-byte Ed25519 seed (64 hex); syx publish → syx1:ed25519:<pk>:<sig> (C-05)
SYX_REGISTRY_VERIFY_KEYInstall: 64 hex pin matching publisher verifying key; embedded pk must match (C-02); mismatch P011
SYX_REGISTRY_REQUIRE_SIGNATURE=1Install requires ed25519 signature; Phase 5 rejects syx1:stub
SYX_REGISTRY_ALLOW_STUB=1Tests only: accept syx1:stub even when signatures required
SYX_EMBED_DENY_UNKNOWN=1Embed v8: reject unknown capabilities in SYX_EMBED_CAPABILITIES (default on)
SYX_EMBED_CAPABILITIESEmbed capability allowlist (wasmtime,print,inprocess)
SYX_WASI=1Enable wasmtime WASI preview1 (path_open + real fd_read/fd_write temp dir mapping)
SYX_WASI_GC_PHASE22=1WASI GC Phase 22: syx_gc.alloc noop arena host hook
SYX_WASI_GC_PHASE23=1WASI GC Phase 23: bump arena + mark-clear smoke
SYX_REGISTRY_CDN_PHASE6=1Registry CDN Phase 6: staging signed URL install
SYX_EMBED_SECCOMP=1Embed v9: seccomp/Job Object MVP hardening
SYX_ATTACHED_HYGIENIC_V2=1@attached hygienic v2 templates ({type}:{name})
SYX_LLVM_RELEASE_BLOCKER=1Optional LLVM strict parity PR release blocker (ADR-019)
SYX_LLVM_STRICT_GREEN_WEEKS=NADR-017 promotion counter (≥4 green weeks for promotion)
SYX_LLVM_PARITY_GATE=strictLLVM Top-300 runtime parity + symbol strict gate (CI Phase 34)
SYX_LLVM_AOT_PHASE9=0Disable LLVM AOT Phase 9 IR path (unified remembered-set GC IR / ADR-044 gate)
SYX_LLVM_AOT_PHASE8=0Disable LLVM AOT Phase 8 IR path (VM/native remembered-set GC IR / ADR-042 gate)
SYX_LLVM_AOT_PHASE7=0Disable LLVM AOT Phase 7 IR path (WASM/native GC intrinsics IR / ADR-040 gate)
SYX_LLVM_AOT_PHASE6=0Disable LLVM AOT Phase 6 IR path (GC intrinsics / guest heap / exec_op → 0% gate)
SYX_LLVM_AOT_PHASE5=0Disable LLVM AOT Phase 5 IR path (CallHost/JSON / exec_op < 1% gate)
SYX_LLVM_AOT_PHASE4=0Disable LLVM AOT Phase 4 IR path (ADR-028 Phase 4 / exec_op < 5% gate)
SYX_LLVM_AOT_PHASE3=0Disable LLVM AOT Phase 3 IR path (ADR-028 Phase 3 / exec_op gate)
SYX_LLVM_AOT_PHASE2=0Disable LLVM AOT Phase 2 IR path (ADR-028 Phase 2)
SYX_REGISTRY_CDN_PHASE9=1Registry CDN Phase 9: failover retries + health probe
SYX_REGISTRY_CDN_PHASE8=1Registry CDN Phase 8: multi-region URLs + failover
SYX_UNIFIED_GC_LTS=1Unified generational GC prod across three backends (VM + WASM + native; ADR-045)
SYX_UNIFIED_GC_LTS_PROD=1Unified GC LTS prod default: remembered set + promotion on all backends
SYX_WASI_GC_PHASE33=1WASI GC Phase 33: guest remembered set prod default on + VM --run linkage (ADR-043)
SYX_WASI_GC_PHASE33_PROD=1WASI GC Phase 33 prod default: guest + VM/native generational default on
SYX_VM_NATIVE_GC_PHASE33=1VM/native generational GC prod (syx run + native codegen; ADR-043)
SYX_VM_NATIVE_GC_PHASE33_PROD=1VM/native GC Phase 33 prod default: remembered set prod default on
SYX_WASI_GC_PHASE32=1WASI GC Phase 32: guest remembered set full generational GC prod default on (ADR-041)
SYX_WASI_GC_PHASE32_PROD=1WASI GC Phase 32 prod default: remembered set guest default on
SYX_WASI_GC_PHASE31=1WASI GC Phase 31: guest generational relocating GC prod default on (ADR-039)
SYX_WASI_GC_PHASE31_PROD=1WASI GC Phase 31 prod default: generational guest default on
SYX_WASI_GC_PHASE30=1WASI GC Phase 30: guest relocating GC prod default on (ADR-037)
SYX_WASI_GC_PHASE29=1WASI GC Phase 29: guest relocating GC MVP prod default on (ADR-035)
SYX_INKWELL_SPIKE=0Explicitly disable inkwell path, fall back to clang text IR (opt-out when Phase 34 ADR-044 prod default on)
SYX_INKWELL_SPIKE=1LLVM inkwell hello IR compile (Phase 32 opt-in; optional after Phase 33+ ADR-042/044 default GA)
SYX_BORROW_COQ_LEAN_PROOF_PROD=1Borrow Coq/Lean machine-checked proof prod (obligation replay + external tool hook; Phase 34)
SYX_BORROW_COQ_LEAN_EXPORT=1Borrow Coq/Lean external proof scaffold (.v/.lean export + replay; Phase 33)
SYX_REGISTRY_CDN_PHASE15=1Registry CDN Phase 15: global CDN multi-active write + edge signature E2E
SYX_REGISTRY_CDN_PHASE14=1Registry CDN Phase 14: edge cache + offline install signature E2E
SYX_DIST_ACTOR_WIN_PIPE_PROD=1Distributed Actor Windows Named Pipe real API (Phase 32 CreateNamedPipe/ConnectNamedPipe)
SYX_DIST_ACTOR_RUSTLS_CRATE=1Distributed Actor rustls crate cert chain / pin E2E (Phase 32)
SYX_BORROW_MACHINE_PROOF=1Borrow region graph machine proof harness (Phase 32 obligation export)
SYX_DIST_ACTOR_WIN_PIPE_NAMED_IO=1Distributed Actor Windows Named Pipe real I/O (Phase 31 ER2; Phase 32 real API above)
SYX_WASI_GC_PHASE28=1WASI GC Phase 28: guest unified heap prod default on
SYX_WASI_GC_PHASE27=1WASI GC Phase 27: guest unified heap wiring (evaluation gate)
SYX_WASI_GC_PHASE27_EVAL=1WASI GC Phase 27 default-on evaluation scaffold
SYX_NET_STREAM_TLS=1Net stream backpressure + TLS layering (ADR-032)
SYX_NET_TCP_STREAM=1Net stream() full-duplex MVP (ADR-030)
editors/vscode-syx/VS Code extension: LSP + type: "syx" DAP debug; install/breakpoints in 12_BackendDebuggingGuide.md

SYX · Apache-2.0