语法导览 - xlang

Lv.1 入门

Hello World

标准库默认可用，无需 import。print 和 println 是全局函数。

hello.xl

// 最简单的 xlang 程序
print("Hello, World!")

// 多参数输出
println("xlang", 6, true)

// main 函数是程序入口
func main(...) as int
    print("程序启动")
    return 0
end
        

注释使用 // 单行或 /* ... */ 多行（支持嵌套）。换行和 ; 都是语句分隔符。顶层可执行语句可与 func main 共存（先执行顶层，再调用 main）。模块级变量可在文件顶层声明。

Lv.1 入门

变量与类型

C 风格类型前置声明。var 是动态类型，auto 编译期推断。

变量声明

// 基础类型声明
int a = 42
int64 big = 1_000_000
float pi = 3.14
string name = "xlang"
bool ok = true
time now = time.now()
point ptr = null

// 整数细分类型
uint8 byte = 255
int32 coord = -100
float64 precise = 1.2e-3

// 动态类型 var — 运行时携带类型信息
var v = 123
v = "现在是字符串"
v = [1, 2, 3]

// 类型推断 auto
auto x = a + 1       // int
auto y = pi * 2.0    // float

// 常量
const int maxRetry = 3

// 类型别名
typedef i64 = int64
        

类型本身也是一等值：type t = type(42) 取得表达式的类型。UTF-8 标识符意味着你可以使用中文命名变量。

Lv.1 入门

字面量

xlang 支持丰富的字面量形式，包括六种字符串和时间字面量。

整数与浮点

// 整数（仅小写前缀）
42              // 十进制
1_000_000       // 下划线分隔
0x2A            // 十六进制
0o52            // 八进制
0b101010        // 二进制

// 浮点
3.14
1.0e10
1.2e-3
        

六种字符串形式

string a = "双引号，支持 \n 转义"
string b = '单引号，也支持转义'

// raw string — 不处理转义
string c = r"c:\temp\file.txt"

// 多行字符串
string d = """
第一行
第二行
"""

// f-string — 表达式插值
string name = "world"
print(f"Hello {name}!")         // Hello world!
print(f"{1 + 2}")                  // 3

// raw f-string — 插值生效，转义不处理
print(rf"c:\{name}\data")
        

时间字面量

time date = #2026-06-18#
time t = #12:30:45#
time dt = #2026-06-18 12:30:45#

print(time.year(date))       // 2026
print(time.format(dt))
        

Lv.1 入门

运算符

完整的算术、比较、逻辑、位运算和空值运算符。

运算符全集

// 算术
int a = 10 + 3 * 2     // 16
int b = 10 % 3         // 1
int c = 2 ** 10         // 1024

// 复合赋值
a += 5
a -= 5
a *= 2
a /= 3
a %= 3
a **= 2
// 比较
bool eq = a == b
bool ne = a != b
bool lt = a < b

// 逻辑（关键字形式）
if a > 0 and b < 10 then
    print("both true")
end

if not ok or a == 0 then
    print("failed")
end

// 位运算
int mask = 0xFF & 0x0F
int shifted = 1 << 8

// 空值与条件
auto x = maybeNull ?? "default"   // 空合并
auto y = cond ? 1 : 0               // 三元
field ?= value                        // 条件赋值（仅为 null 时赋值）

// 安全访问
print(obj?.field)                    // obj 为 null 时不崩溃
print(arr?[99])                       // 越界返回 null

// 成员判断
if "key" in dict then
    print("found")
end
        

Lv.1 入门

控制流

if/elseif/else、while、do-while、for-in，全部用 end 闭合块。

条件与循环

// if / elseif / else（必须有 then）
if score >= 90 then
    print("A")
elseif score >= 60 then
    print("B")
else
    print("F")
end

// while 循环
int i = 0
while i < 5
    print(i)
    i += 1
end

// do-while（条件后必须带 end）
do
    i += 1
while i < 10 end

// for-in + range
for n in range(0, 5)
    print(n)
end

// break / continue
for n in range(0, 100)
    if n == 5 then
        break
    end
    if n % 2 == 0 then
        continue
    end
    print(n)
end
        

Lv.1 入门

函数基础

as 声明返回类型，无 as 表示无返回值。支持默认参数、命名参数、可变参数。

函数声明

// 无返回值
func greet(string name)
    print(f"Hello, {name}!")
end

// 有返回值
func add(int a, int b) as int
    return a + b
end

// 默认参数
func log(string text, int level = 1)
    print(f"[{level}] {text}")
end

log("hello")          // level 默认 1
log("error", 3)       // level = 3

// 命名参数（可乱序）
func move(int x, int y)
    print(x, y)
end

move(y = 2, x = 1)        // 命名参数乱序调用

// 数组可变参数 ...（通过 arg 访问）
func sum(...) as int
    int total = 0
    for v in arg
        total += v as int
    end
    return total
end

print(sum(1, 2, 3, 4))      // 10

// 字典可变参数 ***（通过 arg 访问）
func configure(string name, ***) as var
    return arg["mode"]
end

auto mode = configure("app", mode = "debug", port = 8080)
        

Lv.2 基础

容器

四种静态泛型容器：array、dict、set、list。字面量简洁直观。

数组与字典

// 数组 — [] 字面量
array<int> nums = [1, 2, 3]
auto more = array<int>[4, 5, 6]

print(nums[0])              // 1
nums[0] = 99
print(nums?[99])             // 安全索引，越界返回 null

// 字典 — {} 字面量
dict<int> scores = {"alice": 90, "bob": 85}
scores["carol"] = 78

// 集合
set<int> unique = set<int>{1, 2, 3}

// 列表 — int64 稀疏索引
list<string> sparse = list<string>[0: "a", 5: "b"]
        

遍历容器

// 遍历数组
for value in [10, 20, 30]
    print(value)
end

// 遍历字典（键值对）
for key, value in {"a": 1, "b": 2}
    print(key, value)
end

// 遍历字符串（UTF-8 字符迭代）
for i, ch in "你好xlang"
    print(i, ch)
end
        

Lv.2 基础

字符串进阶

44 个标准库函数，UTF-8 原生支持。

string 标准库

string text = "Hello, xlang!"

// 基本操作
print(string.len(text))           // UTF-8 字符数
print(string.byteLen(text))       // 原始字节数
print(string.upper(text))         // HELLO, XLANG!
print(string.lower(text))

// 查找与判断
print(string.contains(text, "xlang"))   // true
print(string.startsWith(text, "Hello")) // true
print(string.indexOf(text, ","))         // 5

// 分割与拼接
array parts = string.split("a,b,c", ",")
print(string.join(parts, "-"))            // a-b-c

// 截取
print(string.slice(text, 0, 5))        // Hello
print(string.trim("  hi  "))            // hi

// 替换与重复
print(string.replace(text, "xlang", "World"))
print(string.repeat("ab", 3))              // ababab
        

Lv.2 基础

多返回值与解构

函数可以返回多个值，调用方使用解构声明接收。

多返回值

// 返回多个值
func divmod(int a, int b) as (int, int)
    return a / b, a % b
end

// 解构声明
int quotient = 0
int remainder = 0
quotient, remainder = divmod(17, 5)
print(quotient, remainder)     // 3 2

// 配合 auto 推断
auto q, r = divmod(100, 7)
        

Lv.2 基础

闭包与函数值

函数是一等公民，支持匿名函数、闭包捕获和函数值类型。

匿名函数与闭包

// 匿名函数（箭头体）
auto inc = func(int a) as int => a + 1
print(inc(41))                    // 42

// 闭包捕获外层变量
int base = 100
auto adder = func(int x) as int => base + x
print(adder(5))                  // 105

// 函数值类型
func add(int a, int b) as int
    return a + b
end

func(int, int) as int proc = add
print(proc(3, 4))                 // 7

// 函数重载（同名不同参数）
func process(int v) as int
    return v * 2
end

func process(string s) as int
    return string.len(s)
end
        

Lv.3 进阶

类与对象

class 定义字段、方法、构造函数。self 引用当前实例。

class 定义

class Point
    int x = 0
    int y = 0

    create(int x, int y)
        self.x = x
        self.y = y
    end

    func length2() as int
        return self.x * self.x + self.y * self.y
    end
end

// 构造实例
Point p = Point(3, 4)
print(p.x, p.y)              // 3 4
print(p.length2())            // 25
        

Lv.3 进阶

参数传递模式

class 和容器默认按引用传递；基础类型默认按值。byval / byref / out 显式控制。

byval / byref / out

class Box
    int count
end

// 默认共享引用
func shared(Box value)
    value.count = 10       // 对调用方可见
end

// byval — 仍共享同一对象，参数重新绑定只影响局部
func byvalExample(byval Box value)
    value.count = 20       // 对调用方可见
    value = Box()          // 只重新绑定局部参数
end

// 独立副本必须显式 copy() / clone()
func makeCopy(Box value)
    Box independent = copy(value)
    independent.count = 30
end

// byref — 可改写调用方变量
func replace(byref Box value)
    value = Box()          // 改写调用方变量槽
end

// out — 必须赋值后返回
func create(out Box value)
    value = Box()
end

Box box = Box()
shared(box)
replace(byref box)
create(out box)
        

byval 对 class 和容器不创建独立副本，只保留同一受管理引用。需要独立对象时必须显式 copy() / clone()。byref 和 out 的调用点必须显式写出标记。

Lv.3 进阶

继承与访问控制

extends 单继承，base() 调用父类构造。public/private 控制访问，static 定义类级成员。

继承与 base 调用

class Base
    int seed = 0

    create(int seed)
        self.seed = seed
    end

    func describe() as string
        return f"seed={self.seed}"
    end
end

class Child extends Base
    int extra = 0

    create(int seed, int extra)
        base(seed)              // 调用父类构造
        self.extra = extra
    end

    func sum() as int
        return self.seed + self.extra
    end
end

auto c = Child(10, 20)
print(c.describe())           // seed=10
print(c.sum())                // 30
        

访问控制与 static

class Entity
    private int raw = 0       // 仅类内部可访问
    static int total = 0      // 类级字段

    static func of(int v) as Entity
        Entity.total += 1
        Entity e = Entity()
        e.raw = v
        return e
    end
end

auto e = Entity.of(42)
print(Entity.total)            // 1
        

Lv.3 进阶

属性 get / let

get 定义读取属性，let 定义写入属性。支持多维参数重载。

属性

class Meter
    private array<int> values = [0, 0, 0]

    // 零维属性
    get first() as int
        return self.values[0]
    end

    let first(int v)
        self.values[0] = v
    end

    // 多维属性 — 像索引一样使用
    get value(int idx) as int
        return self.values[idx]
    end

    let value(int idx, int v)
        self.values[idx] = v
    end
end

auto m = Meter()
m.first = 42
print(m.first)                // 42
m.value[1] = 99
print(m.value[1])              // 99
        

Lv.3 进阶

泛型

泛型函数与泛型 class，支持约束语法和 ::<T> 显式实例化。

泛型函数

// 泛型函数
func max<T>(T a, T b) as T
    if a > b then
        return a
    end
    return b
end

// 显式实例化
int biggest = max::<int>(10, 20)

// 带约束的泛型（is 关键字）
func serialize<T is json>(T obj) as string
    return json.stringify(obj)
end

// 多约束用 and 组合
class Map<K is comparable and cloneable, V is json and cloneable>
    // ...
end
        

Lv.4 高级

多态 virtual / override / final

virtual 声明可重写方法，生成 vtable 支持动态派发。override 重写，final 禁止再重写。

多态

class Shape
    virtual func area() as float
        return 0.0
    end
end

class Circle extends Shape
    float radius = 0

    create(float r)
        self.radius = r
    end

    override func area() as float
        return math.pi * self.radius * self.radius
    end
end

class Square extends Shape
    float side = 0

    create(float s)
        self.side = s
    end

    override final func area() as float
        return self.side * self.side
    end
end

// 动态派发
Shape s1 = Circle(5.0)
Shape s2 = Square(4.0)
print(s1.area())              // 78.54...
print(s2.area())              // 16.0
        

Lv.4 高级

协议与运算符重载

双下划线协议方法实现运算符重载、索引、调用、迭代等自定义行为。

运算符协议

class Vec3
    float x = 0
    float y = 0
    float z = 0

    create(float x, float y, float z)
        self.x = x
        self.y = y
        self.z = z
    end

    // 加法
    func __add__(Vec3 other) as Vec3
        return Vec3(self.x + other.x, self.y + other.y, self.z + other.z)
    end

    // 相等
    func __eq__(Vec3 other) as bool
        return self.x == other.x and self.y == other.y and self.z == other.z
    end

    // 取负
    func __neg__() as Vec3
        return Vec3(-self.x, -self.y, -self.z)
    end
end

auto a = Vec3(1, 2, 3)
auto b = Vec3(4, 5, 6)
auto c = a + b               // Vec3(5, 7, 9)
auto n = -a                  // Vec3(-1, -2, -3)
        

索引 / 调用 / 迭代协议

class Grid
    int base = 0

    create(int base)
        self.base = base
    end

    // 索引读取
    func __item__(int x, int y) as int
        return self.base + x * 10 + y
    end

    // 索引写入
    func __setItem__(int x, int y, int value)
        self.base = value + x * 10 + y
    end

    // 成员判断 in
    func __contains__(int value) as bool
        return value == self.base
    end

    // 调用 obj(...)
    func __call__(int add) as int
        return self.base + add
    end
end

auto g = Grid(100)
print(g[2, 3])               // 123
g[2, 3] = 7
print(30 in g)              // false
print(g(5))                  // 105
        

可用的运算符协议：__add__ __sub__ __mul__ __div__ __mod__ __pow__ __neg__ __pos__ __not__ __eq__ __ne__ __lt__ __le__ __gt__ __ge__

Lv.4 高级

derive 自动派生

一行 derive 自动生成 copy/clone/json 等协议实现，告别手写样板代码。

derive 全家桶

class Config
    derive copy             // 浅复制
    derive clone            // 深复制
    derive json             // JSON 序列化
    derive xson             // XSON 序列化
    derive value            // xvalue 互转
    derive hash             // 哈希
    derive equals           // 相等比较

    int id = 0
    string name = ""
end

auto cfg = Config()
cfg.id = 1
cfg.name = "production"

// 自动复制
auto copied = copy(cfg)

// JSON 序列化
string text = json.stringify(cfg, true)
print(text)

// JSON 反序列化
auto restored = json.parse::<Config>(text)
        

@json 字段注解

class User
    derive json

    int id = 0

    // 重命名 JSON 字段
    string name @json("user_name") = ""

    // 跳过持久化
    string internalToken @persist(skip) = ""
end
        

Lv.4 高级

类型操作 is / as

is 运行时类型判断返回 bool，as 显式向下转换。

is / as

var value = 123

// 运行时类型判断
if value is int then
    print("是整数")
end

if value is null then
    print("是空值")
end

// 向下转换（从 var 转出具体类型）
int n = value as int
print(n + 1)
        

class 继承关系判断

class Base
end

class Child extends Base
end

Child child = Child()
var boxed = child

// is 支持 class 继承关系
if boxed is Base then
    Base base = boxed as Base
    print("转换成功")
end

// 取类型值
type t = type(child)
print(t)
        

Lv.5 并发

异步 async / await

原生 async/await，future<T> 异步值，task.all/race 组合编排。

基本异步

async func addAsync(int a, int b) as int
    return a + b
end

// await 等待结果
future<int> f = addAsync(20, 22)
int result = await f
print(result)                 // 42

// auto 推断
auto autoFuture = addAsync(1, 2)
auto value = await autoFuture
        

task.all / task.race

// 并发等待全部完成
future<int> a = addAsync(1, 2)
future<int> b = addAsync(3, 4)
future<int> c = addAsync(5, 6)

array<int> all = await task.all([a, b, c])
print(all)                    // [3, 7, 11]

// 竞速 — 取最快完成的
int winner = await task.race([a, b, c])

// 取消
task.cancel(c)

// Future 链式 continuation
func plusOne(int value) as int
    return value + 1
end

future<int> mapped = a.then(plusOne)
future<int> recovered = mapped.catch(func(error e) as int => 0)
func cleanup()
    println("done")
end

future<int> finalized = recovered.finally(cleanup)

// TaskGroup 管理一组 future
TaskGroup group = task.group()
group.add(finalized)
group.waitTimeout(5000)
group.close()
        

Lv.5 并发

生成器

yield 惰性求值，generator<T> 类型化。通过 for-in 消费。

生成器

func fibonacci(int count) as generator<int>
    int a = 0
    int b = 1
    int i = 0
    while i < count
        yield a
        int temp = a + b
        a = b
        b = temp
        i += 1
    end
end

// for-in 自动消费
for val in fibonacci(10)
    print(val)
end
// 输出: 0 1 1 2 3 5 8 13 21 34
        

Lv.5 并发

Channel

channel<T> 线程间安全通信。支持 int、float、bool、string、time、point 等可按值复制类型。

channel

// 创建带缓冲的 channel
channel<int> ch = channel::<int>(2)

// send 是阻塞发送（满时等待）
ch.send(123)

// trySend 是非阻塞发送（满时立即返回 false）
if not ch.trySend(456) then
    print("队列已满")
end

// 阻塞接收
int received = 0
if ch.recvInto(received) then
    print(received)           // 123
end

// 非阻塞接收
if not ch.tryRecvInto(received) then
    print("暂无数据")
end

// channel<string> 也支持（复制 UTF-8 字节）
channel<string> texts = channel::<string>(2)
texts.send("你好")

ch.close()
        

channel 离开作用域时自动关闭队列并释放未消费消息。send 是阻塞语义（满时等待空间），trySend 是非阻塞（满时立即返回 false）。

Lv.5 并发

线程与同步原语

thread 线程封装、mutex / sem / cond / rwlock 同步原语。

线程

func worker() as int
    print("working...")
    return 7
end

thread t = thread(worker)
t.wait()
print(t.exitCode())          // 7
        

同步原语

// 互斥锁
mutex m = mutex()
m.lock()
// 临界区...
m.unlock()

// 信号量
sem gate = sem(0, 2)
gate.post()
gate.waitTimeout(100)

// 读写锁
rwlock rw = rwlock()
rw.readLock()
rw.readUnlock()
rw.writeLock()
rw.downgrade()
rw.readUnlock()

// 条件变量
cond c = cond()
c.signal()
c.broadcast()
        

Lv.6 系统级

C 互操作

extern 声明 C 函数、export 导出给 C、native-backed class 对接 C handle。

extern / export

// extern 声明 C 函数进入 xlang
extern "printf" func printf(string fmt, ...) as c_int

// 使用 C ABI 精确类型
extern "malloc" func malloc(c_size size) as point
extern "free" func free(point ptr)

// export 导出 xlang 函数给 C
export "xl_greet" func greet(c_int times) as c_int
    int i = 0
    while i < times
        print("Hello from xlang!")
        i += 1
    end
    return 0
end
        

native-backed class

// 对接 C opaque handle 的完整生命周期
class Counter
    native point handle                      // C 不透明指针

    extern "counter_open" create(int seed)
    extern "counter_close" destroy()
    extern "counter_add" func add(int value) as int
    extern "counter_value" func value() as int
end

// 使用就像普通 class
auto c = Counter(40)
print(c.add(2))                     // 42
print(c.value())                    // 42
        

混合编译：xl build main.xl helper.c -o app.exe。CLI 参数 --inc-path / --lib-path / --link / --loadlib 注入 C 依赖。

export 变量与常量

// 导出 package 符号（不进入 C 头文件）
export int counter = 0
export const int version = 6

// 同时导出 package 符号和 C ABI 符号
export "app_counter" int appCounter = 0

// 声明 C 全局变量
extern "errno" int errno

// 将 C 全局变量以 package 符号重新导出
export extern "host_flag" int hostFlag
        

Lv.6 系统级

错误处理

try / catch / finally 结构化错误处理。

异常与断言

func risky(int x) as int
    if x < 0 then
        throw "x 不能为负数"
    end
    return x * 2
end

try
    int r = risky(-1)
catch e
    print(e.kind)                  // "Error"
    print(e.message)               // "x 不能为负数"
finally
    print("清理完成")
end

// 断言
int x = 1
assert x > 0
assert x > 0, "x 必须为正数"
        

Lv.6 系统级

文档注释

#doc ... #end 文档块，进入 ABI 元数据。

文档注释

#doc
desc:
    计算两个整数的最大值。
param a:
    第一个值。
param b:
    第二个值。
return value:
    a 和 b 中的较大者。
example:
    print(max(1, 2))  // 2
#end
func max(int a, int b) as int
    if a > b then
        return a
    end
    return b
end
        

doc 字段：desc: param name: return name: note: example:，内容按缩进收集多行文本。

Lv.6 系统级

union 值聚合

C 风格联合体，按 C 兼容布局生成。DEMO6 不提供公开 struct 语句。

union

union NumberBits
    int64 integer
    float64 real
end

// 使用
NumberBits nb
nb.integer = 42
print(nb.real)       // 以 float64 视角读取同一内存
        

union 按值传递，适合与 C 库交互或手动位布局。字段共享同一起始地址，大小为最大字段对齐。

Lv.6 系统级

SDK 嵌入 API

xl.dll / xlc.dll 提供 76 个公开 C API，支持 C 宿主嵌入 xlang 运行时。

C 宿主嵌入示例

// C 侧嵌入 xlang
XL_ContextOptions opts = xlDefaultContextOptions();
XL_Context* ctx = xlCreateContext(&opts);

// 运行脚本
xlRunScriptFile(ctx, "app.xl");

// 运行字符串脚本并传参
xvalue arg = /* array 类型 */;
xlRunScriptStringArg(ctx, source, arg);

// 编译到 exe
xlCompileScriptFileToExe(ctx, "app.xl", "app.exe");

// 注册 C 函数
xlRegisterCFunction(ctx, "my_c_func", &my_c_func);

xlDestroyContext(ctx);
        