前言

欢迎阅读 Toka 编程语言指南。

本书是学习 Toka 的全面指南——Toka 是一门为安全性、简洁性和高性能而设计的现代系统编程语言。

Toka 由 YiZhonghua 创建。官方语言仓库位于 github.com/tokalang/toka —— 欢迎访问以探索编译器、标准库及更多内容。

本书适合谁阅读

• 初学者 — 想要学习自己的第一门系统编程语言
• 有经验的开发者 — 来自 C、Rust、Go 或其他语言的从业者
• 语言爱好者 — 对 Hat Principle 和 PAL Checker 感到好奇的人

你将学到的内容

1. 快速入门 — 安装 Toka 并编写你的第一个程序
2. 语言基础 — 变量、类型、函数、控制流
3. Hat Principle — Toka 独特的内存安全方案
4. 高级特性 — 泛型、错误处理、并发编程
5. 标准库概览 — 字符串、集合、IO、网络等
6. 动手项目 — 构建 CLI 工具、HTTP 服务器和正则引擎

如何使用本书

如果你刚接触 Toka，建议从头开始按顺序阅读。每一章都建立在前一章的基础之上。

如果你是有经验的开发者，可以直接通过侧边栏导航跳转到感兴趣的主题。

语言版本对齐

本书会随 Toka 编译器的开发保持更新。当前文档版本对齐：

• 编译器版本：v0.9.8
• Toka Commit：aadfd52（完成太极三轨文本体系、废除 while 统一为 loop、标准分代 Slab 分配器重构以及 forge 并行增量构建引擎）
• Tag：v0.9.8-03

作者的话

Toka 是一门年轻但充满雄心的语言。这本指南伴随语言的开发同步编写，旨在帮助早期采用者快速上手。随着 Toka 的演进，本书也会一同成长。

[!NOTE] 由于 Toka 仍处于活跃的开发与高速迭代中，本书中的部分表述和特性在稳妥起见下可能与编译器实际行为存在些许出入。若有疑问，请始终以 官方编译器及标准库的实际代码实现 为准。

祝你编码愉快！

— lumicore-dev

快速入门

欢迎使用 Toka！Toka 是一门现代系统级编程语言，旨在提供内存安全、高运行效率以及直观的开发体验。它通过 Hat Principle（帽子原则） 来实现编译时内存安全，无需垃圾回收器，也无需手动标注生命周期。

为了让您以最快的速度上手，本章被划分为三个由浅入深的步骤。我们建议您按顺序阅读和实践：

🧭 您的 Toka 学习路线

1. 安装 Toka 在您的系统上安装并配置 Toka 编译器与工具链。我们为 Linux、macOS 和 Windows 提供了单命令快速安装脚本，同时提供了从源码编译的详细说明。

2. Hello, Toka！ 编写、编译并运行您的第一个 Toka 程序。您将学习如何直接调用编译器，并理解一个最基本的 Toka 可执行程序的内部构造。

3. 项目结构 从简单的单文件脚本过渡到结构化、专业的多文件包管理。了解 Toka 内置的包管理器、如何通过 package.tk 定义项目元数据、如何添加依赖以及如何组织库项目。

现在，让我们从在您的机器上安装 Toka 开始吧！

安装 Toka

在你的系统上安装 Toka 只需几秒钟。

快速安装

安装 Toka 最简单的方式是通过官方安装脚本：

curl -fsSL https://tokalang.dev/install.sh | bash

该脚本会自动：

1. 检测你的操作系统和 CPU 架构
2. 下载最新的稳定版本
3. 安装到 ~/.toka/bin/ 目录
4. 配置环境变量

配置环境

安装完成后，将以下内容添加到你的 ~/.bashrc 或 ~/.zshrc 中：

export PATH="$HOME/.toka/bin:$PATH"
export TOKA_LIB="$HOME/.toka/lib"

重新加载你的 shell：

source ~/.bashrc

验证安装

tokac --version

你应该会看到类似如下的输出：

toka version 0.9.7 (Built: May 21 2026)

从源码编译

如果你想使用最新的开发版本：

git clone https://github.com/tokalang/toka.git
cd tokalang
make -C build -j8

支持平台

Hello, Toka！

让我们编写你的第一个 Toka 程序。创建一个名为 hello.tk 的文件：

import std/io::println

fn main() -> i32 {
    println("Hello, Toka!")
    return 0
}

运行程序

Toka 提供了两种方式来运行你的代码：

方式一：一步运行

toka run hello.tk

这会在一个命令中完成编译和执行。

方式二：先构建再运行

tokac build hello.tk -o hello
./hello

这会生成一个可以分发的独立二进制文件。

预期输出

Hello, Toka!

代码解析

让我们逐一拆解每部分的作用：

• import std/io::println — 从标准库的 IO 模块中导入 println 函数。
• fn main() -> i32 — 声明程序的入口点。每个 Toka 可执行文件都需要一个 main 函数。-> i32 表示它返回一个整数（退出码）。
• println("Hello, Toka!") — 将字符串打印到标准输出。
• return 0 — 返回退出码 0，表示成功。

快速一行测试

如果想快速测试而不创建文件，也可以直接使用：

echo 'import std/io::println fn main() -> i32 { println("Hello, Toka World!") return 0 }' > hello.tk
toka run hello.tk

下一步

在下一节中，我们将探索标准项目结构，以及如何组织更大的 Toka 项目。

项目结构

理解 Toka 的项目结构有助于你有效地组织代码。

单文件程序

对于快速原型开发或简单的脚本，一个单独的 .tk 文件就足够了。正如我们在 Hello, Toka！ 一节中所见，您可以将所有代码编写在一个文件（如 hello.tk）中，并通过以下命令立即执行它：

toka run hello.tk

多文件项目

对于大型项目，使用 toka init 初始化一个项目。这会创建一个 package.tk 文件：

// package.tk
pub const PACKAGE = (
    name = "my_project",
    version = "0.1.0",
    dependencies = ()
)

目录结构：

my-project/
├── package.tk      # 项目配置和依赖管理
├── src/
│   ├── main.tk     # 入口文件
│   ├── utils.tk    # 工具函数
│   └── models.tk   # 数据模型
└── lib/
    ├── config.tk   # 库配置
    └── helpers.tk  # 辅助函数

添加依赖

你可以通过 toka add 命令轻松添加第三方包到项目中：

toka add toka_ink

该命令会自动查询 Toka Registry，将包解析为其对应的 GitHub 仓库和版本标签，并更新你的 package.tk：

// package.tk
pub const PACKAGE = (
    name = "my_project",
    version = "0.1.0",
    dependencies = (
        toka_ink = "github.com/lumicore-dev/toka_ink:v0.2.1",
    )
)

在执行 toka build 时，编译器会自动将这些依赖拉取到 .toka/packages 目录中。

库项目

对于可复用的库项目，toka new my-lib --lib 会生成一个不含 main.tk 可执行入口点的库结构。package.tk 的配置格式保持一致。

导入系统

// 从标准库导入
import std/io::println

// 从项目源码导入
import src/utils::{helper_fn}

// 从本地库导入
import lib/config::{Config}

// 使用别名导入
import std/time as time_lib

构建输出

运行 toka run 或 tokac build 会生成：

my-project/
└── target/
    ├── debug/
    │   └── my-project    # 调试版二进制
    └── release/
        └── my-project    # 发布版二进制（添加 --release 参数）

🛠️ 增量构建与 Forge 引擎

自 Toka v0.9.8-03 起，官方引入了高吞吐量、并行的增量构建引擎 forge。它通过解析项目根目录下的 build.tk 拓扑依赖声明，实现多模块的并行增量编译，并将构建状态持久化存储于本地。

1. 声明构建配置 build.tk

在项目的根目录下创建一个 build.tk 文件，使用内置的 build 工具链来定义你的可执行文件或库：

import build::{Executable, run_build}

fn main() -> i32 {
    // 实例化一个构建工程，Executable::make(二进制名称, 入口源文件)
    // 由于 Executable::make 底层是对 C-FFI 的高层封装，我们需要显式传递 FFI 裸指针。
    auto proj# = Executable::make("my-project".as_cstr().raw_ptr(), "src/main.tk".as_cstr().raw_ptr())
    return run_build(proj)
}

2. 使用 Forge 开启增量并发构建

在终端中执行：

# 开启并行构建，-j 指定并发线程数（默认为 4）
forge -j 8

forge 引擎将自动：

• 扫描并解析 src/main.tk 及其所有 import 子模块的静态依赖拓扑 DAG。
• 比对源文件的最新修改时间，将文件状态索引保存于本地 .forge_cache 数据库中。
• 智能增量跳过：对没有发生代码变更的源文件，利用增量缓存技术瞬时绕过，从而将大型多模块项目的自举编译耗时压缩到毫秒级别！

语言基础

现在你已经安装了 Toka 并编写了第一个程序，让我们深入了解这门语言的核心概念。

Hello World 回顾

最简单的 Toka 程序只需要两样东西：一个标准库的 import 和一个 main 函数：

import std/io::println

fn main() -> i32 {
    println("Hello, Toka!")
    return 0
}

运行方式：

toka run hello.tk

核心原则

Toka 围绕几个核心原则设计：

1. 默认安全 — 变量默认不可变，除非显式标记。
2. 无隐藏运行时 — 你写什么就执行什么。没有垃圾回收器，没有虚拟机。
3. 类 C 性能 — 基于 LLVM 20，Toka 生成优化的原生代码。
4. 现代语法 — 简洁、可读性强，配备直观的模式匹配和错误处理。

注释语法

Toka 中的注释使用标准的 // 语法：

// 这是单行注释

/* 这是
   多行注释 */

下一步

在接下来的章节中，我们将详细探索变量、类型、函数和控制流。

变量与类型

Toka 是一门具有丰富类型系统的静态类型语言。让我们来探索变量和类型是如何工作的。

变量声明

使用 auto 关键字声明变量：

auto x = 10          // i32（默认整数类型）
auto y = 3.14        // f64（默认浮点类型）
auto name = "Toka"   // str（字符串切片）

命名规则与连字符（-）消歧

Toka 对连字符（-）字符有一套严格而优雅的规则，在实现模块化命名便利性的同时，确保数学语法没有歧义。

包名与命名空间

包名和导入的命名空间可以自由使用连字符。这在导入嵌套文件夹或遵循 kebab-case 目录结构的外部库时很常见。你可以导入它们并使用连字符命名空间调用函数：

import std/io::println

// 包名和命名空间可以包含连字符（但在模块标识符中建议使用下划线对齐真实标准）
import ./nested/toka-ink as toka_ink

fn main() -> i32 {
    toka_ink::render()
    return 0
}

变量与函数

普通变量名、常量名、shape/结构体名和函数定义不能包含连字符。它们必须遵循标准的字母数字/下划线命名规则（如 camelCase 或 snake_case）：

fn main() -> i32 {
    auto max_size = 1024       // OK（snake_case）
    auto maxSize = 1024        // OK（camelCase）
    // auto max-size = 1024    // 错误：变量名中不允许使用连字符
    return 0
}

无歧义的减法运算

由于连字符在变量名和函数名中是严格禁止的，减法运算符（-）完全没有歧义。不带空格的普通减法表达式始终能被无歧义地解析：

import std/io::println

fn main() -> i32 {
    auto sub1 = 10
    auto sub2 = 3
    
    // 不需要空格！始终被解析为减法
    auto result = sub1-sub2    // OK：解析为 sub1 - sub2
    auto value = 10-3          // OK：解析为 10 - 3
    println("Result: {}, Value: {}", result, value)
    return 0
}

显式类型标注

你可以使用冒号显式指定类型：

auto x: u64 = 10
auto y: f32 = 3.14:f32
auto flag: bool = true

基本类型

Toka 的类型系统在 lib/core/types.tk 中定义，包含：

平台相关类型

pub alias usize = u64   // 指针大小的无符号整数
pub alias isize = i64   // 指针大小的有符号整数

在 64 位系统上，usize 是 u64；在 32 位系统上，它会是 u32。

类型别名

Toka 支持两种类型别名：

弱别名（Weak alias） — 语义上完全相同，对编译器透明：

pub alias usize = u64

强类型（Strong type） — 内存布局相同，但需要显式转换：

pub type Addr = u64
pub type OAddr = u64

常量

使用 const 声明编译时常量值：

pub const MAX_SIZE = 1024:u64
pub const NAME = "Toka"

常量在编译时内联展开——不分配内存，不能获取其地址。

可变性

变量默认不可变。使用 # 后缀使其可变。# 标记仅在两个地方需要：

1. 声明时 — 标记变量为可变
2. 调用可变方法前 — 在变量上出示守卫

import std/io::println

pub shape List(data: i32)
impl List {
    pub fn sort(self#) {}
    pub fn push(self#, val: i32) {}
}

fn main() -> i32 {
    auto y = List(data = 10)  // 不可变
    auto x# = List(data = 10) // 可变 — 声明时加 #

    // 读取和赋值不需要 #
    x = List(data = 20)       // OK — 普通赋值
    println("{}", x.data)     // OK — 普通读取

    // 调用可变方法需要在变量上加 #
    x#.sort()                 // OK — 调用 .method() 之前在变量上加 #
    x#.push(5)                // OK
    return 0
}

这是 Toka 属性标记系统（Attribute Token System） 的一个例子——# 后缀表示灵魂的可变性，在声明变量或调用其可变方法时放在变量上。

函数

在 Toka 中，函数是一等公民。它们遵循简洁、可读的语法。

基本函数语法

fn add(x: i32, y: i32) -> i32 {
    return x + y
}

• fn 关键字声明一个函数
• 参数使用 name: Type 语法进行类型标注
• 返回类型跟在 -> 之后
• 函数体用 { } 包裹

入口点：main

每个 Toka 可执行文件都需要一个返回退出码的 main 函数：

import std/io::println

fn main() -> i32 {
    println("Hello, Toka!")
    return 0
}

返回 0 表示成功，非零表示错误。

多个参数

函数可以接受多个不同类型的参数：

fn greet(name: str, age: i32, formal: bool) -> str {
    if formal {
        return "Good day"
    }
    return "Hey"
}

可变参数

参数默认不可变。在声明时使用 # 标记来表示可变参数。在函数体内部，访问参数时不需要 #：

fn increment(x#: i32) {
    x = x + 1       // 函数体内部不需要 #
}

无返回值的函数

如果函数不返回任何值，省略 ->：

import std/io::println

fn log_message(msg: str) {
    println("{}", msg)
}

方法语法

函数可以通过 impl 块附加到类型上：

pub shape Number(val: i32)

impl Number {
    pub fn double(self) -> i32 {
        return self.val * 2
    }
}

fn main() -> i32 {
    auto result = Number(val = 5).double()  // result = 10
    return 0
}

控制流

Toka 提供了现代的控制流结构，帮助你构建清晰、富有表现力的程序。

If / Else

import std/io::println

fn check_temp(temp: i32) {
    if temp > 35 {
        println("天气热！")
    } else if temp < 10 {
        println("天气冷！")
    } else {
        println("天气温和。")
    }
}

Loop 循环

Toka 彻底废除了传统的 while 循环，并将所有的循环语义统一收拢在 loop 关键字下。这极大简化了编译器控制流分析，消除了语法歧义。

条件循环使用 loop condition {} 语法结构：

import std/io::println

auto count# = 0
loop count < 5 {
    println("计数: {}", count)
    count = count + 1
}

遍历数组

Toka 支持在数组上进行迭代：

import std/io::println

for auto i in [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] {
    println("{}", i)
}

目前 Toka 暂不支持原生范围区间运算符（如 ..）。你可以在数组上进行迭代，或使用 loop 实现自定义迭代逻辑。

遍历集合

import std/io::println

auto items = ["苹果", "香蕉", "樱桃"]
for auto item in items {
    println("{}", item)
}

带索引遍历：

import std/io::println

auto items2 = ["苹果", "香蕉", "樱桃"]
auto i# = 0
for auto item in items2 {
    println("{}: {}", i, item)
    i = i + 1
}

Break 和 Continue

使用标准关键字控制循环流程：

import std/io::println

auto iter# = 0
loop iter < 100 {
    if iter == 50 {
        break        // 完全退出循环
    }
    if iter % 2 == 0 {
        iter = iter + 1
        continue     // 跳到下一次迭代
    }
    println("{}", iter)  // 打印奇数: 1, 3, 5, ..., 49
    iter = iter + 1
}

Match（模式匹配）

Toka 使用 match 表达式提供直观的模式匹配支持：

fn describe(value: i32) -> str {
    return match value {
        0 => pass "零"
        1 => pass "一"
        auto v if v >= 2 && v <= 10 => pass "较小"
        auto v if v >= 11 && v <= 100 => pass "中等"
        _ => pass "较大"
    }
}

_ 通配符匹配任意值，作为默认情况使用。

字符串

Toka 1.0 构建了极其严密、高性能的太极三轨文本与字节流系统。它将“文本观察视角”与“物理二进制操纵”在类型系统上进行了正交解耦，同时消除了二义性的隐式语境推导，为系统开发提供极致的内存安全与性能。

🏛️ 一、 字符串与视图类型

Toka 中的字符串分为拥有堆内存所有权的动态容器，以及零拷贝的借用视图。由于内置于 Prelude 零导入作用域，你无需任何 import 即可直接使用这些类型：

⚖️ 二、 三轨宇宙终极正交转换矩阵

Toka 恪守**【开销诚实命名法典】**：

• as_xxx 家族：表示零开销、零分配的视图借用转换，其借出视图生命周期受编译期严格镇守，死死绑定于宿主。
• to_xxx 家族：表示涉及物理拷贝或堆分配的所有权转换，明确昭示所有权与物理分配的分离。

🚀 三、 核心流转与实战

1. 默认的零拷贝字面量

在 Toka 中，常规双引号 "..." 字面量在没有调用碰撞时，默认推导为静态只读的 str：

import std/io::println

fn main() -> i32 {
    // 默认推导为 str 类型，常驻 .rodata 静态段，100% 静态安全
    auto greeting: str = "Hello, Toka!"
    println("Greeting: {}", greeting)
    return 0
}

2. 动态 string 构建与拼接

string 是独占的动态堆容器。你可以通过 push_str 修改它。

import std/io::println

fn main() -> i32 {
    // 零导入 prelude 直接调用 string::from
    auto full# = string::from("你好，")
    full#.push_str("世界！")
    
    println("{}", full.as_str()) // 零开销借出 str 视图打印
    return 0
}

3. str 与 bytes 的双轨视角转换

str 负责高级文本操作，而 bytes 负责底层的二进制和字节索引：

import std/io::println
import core/option::Option
import core/result::Result

fn main() -> i32 {
    auto s: str = "Toka 1.0"
    
    // 1. O(1) 零开销降级为 bytes 视图
    auto b = s.bytes()
    
    // 2. 边界检查的 O(1) 字节索引
    auto b0 = b.at(0:usize)
    if b0.is_some() {
        println("Byte 0: {}", b0.unwrap() as i64) // 84 ('T')
    }
    
    // 3. 校验并升级回 str
    auto res = b.try_to_str()
    if res.is_ok() {
        auto s_back = res.unwrap()
        println("Recovered: {}", s_back)
    }
    return 0
}

🛡️ 四、 FFI 物理拷贝隔离带

由于动态 str 切片并不保证以 \0 结尾，为绝对防范跨越 C-FFI 边界时发生内存越界，str 被严格禁止隐式退化为 cstr 或裸指针。 如果动态 str 确实需要跨越 FFI，必须显式调用 to_string() 在堆上创建带有 \0 尾符的临时副本：

// 声明 FFI 接口
pub fn puts(s: cstr)

fn main() -> i32 {
    auto my_str: str = "Hello C-FFI"
    
    // 显式声明物理拷贝和 \0 封口以确保安全
    auto temp_c = my_str.to_string()
    unsafe {
        puts(temp_c.as_cstr())
    }
    return 0
}

Hat Principle（帽子原则）

Hat Principle（帽子原则） 是 Toka 内存安全模型背后的核心设计哲学。与强制开发者编写繁琐生命周期标注（如 Rust）或依赖运行时垃圾回收器（如 Go 或 Java）的传统方式不同，Toka 引入了称为**“帽子（Hats）”**的直观语法标记，在编译期静态追踪所有权、生命周期与访问权限。

什么是帽子？

在 Toka 中，**帽子（Hat）**是直接附加在标识符上的语法标记符号（sigil）。这种显式标注能向开发者和编译器的安全分析引擎清晰宣告资源的存储方式、所有权归属以及访问模式。

Toka 定义了四种基础的帽子类型学：

手柄 vs. 灵魂：隐式解引用设计

帽子原则在设计上的一个重要特点是将指针容器与底层数据进行了严格的语法分立：

• 手柄（Handle，即帽子）：带有标记符号的标识符（^ptr, *ptr, ~ptr）表示指针容器本身（保存地址的元数据内存）。
• 灵魂（Soul，即数据）：不带标记符号的标识符（ptr）表示底层数据（实际值本身）。

通过直接对灵魂（省略帽子标记）进行操作，Toka 彻底消除了 C 语言中 *p 或 Rust 中 *p 这种繁琐的显式解引用运算符。例如，ptr.x = 42 会直接修改堆底层的结构体数据，无需进行显式解引用。

指针分析层（PAL）

编译器的 指针分析层（Pointer Analysis Layer，简称 PAL Checker） 在编译时审查帽子的使用方式，以静态强制执行以下核心安全保证：

1. 严格的移动语义：独占指针（^）在赋值时会自动转移所有权。PAL Checker 会静态拦截任何对原句柄的“移动后使用（use-after-move）”。
2. 确定性析构：当拥有的指针（^ 或最后一个 ~）离开其声明的作用域时，其绑定的堆资源会被自动、安全地释放。
3. 严苛的借用检查：借用指针（&）会接受严格的生命周期检查，确保其绝不比所指向的“灵魂”存活得更久，从源头上杜绝悬垂指针。
4. 数据竞争防护：PAL Checker 确保可变访问（#）是排他的，而共享访问则是完全只读的。

学习路线

要彻底掌握帽子原则，请依次深入探索以下子章节：

• 灵魂与身份：精通手柄与灵魂的分立、隐式解引用，以及成员链借用（包括标准括号与标志性的帽子终端形态）的语法规则。
• 所有权与帽子：深入剖析四种所有权模型、默认移动与拷贝、cede 关键字，以及局部变量可变声明与方法调用接收者可变标注的编译器设计。
• 内存安全与 PAL：深度剖析指针分析层静态安全分析器如何实现零开销的编译期安全验证。

灵魂与身份（Soul & Identity）

Toka 的帽子原则在指针的**手柄（Handle，语法容器）与其灵魂（Soul，底层数据）**之间引入了严格且清晰的分立。理解并掌握这一设计是理解 Toka 内存管理模式的关键。

手柄 vs. 灵魂

在 Toka 中，每个指针标识符在语法和内存层面上都具有两个截然不同的面相：

• 手柄（Handle，即帽子）：带有指针标记符号的标识符（如 ^p、*p、~p）。它在内存中代表指针容器本身——即保存目标内存地址的元数据槽。
• 灵魂（Soul，即数据）：不带指针标记符号的标识符（如 p）。它代表被指向的底层数据或资源本身。

fn handle_soul_example() {
    auto ^p# = new Point(x=10, y=20)
    p.x = 30
    auto sum = p.x + p.y
    println("sum: {}", sum)
}

在上面的例子中，^p# 是可变的独占手柄，而 p.x 则直接访问底层 Point 灵魂的字段。

优雅的隐式解引用

Toka 彻底摒弃了传统系统级语言中繁琐的显式解引用运算符（例如 C 语言中的 *p / p->，或 Rust 中的 *p）。

每当你需要读取、修改指针背后的数据或访问其内部字段时，你只需直接操作其灵魂（即不带帽子标记的标识符）。Toka 编译器会在后台自动将其解析为解引用操作，具有零运行时开销：

fn implicit_deref_example() {
    unsafe {
        auto *p# = alloc i32
        p = 100
        auto val = p
        println("val: {}", val)
    }
}

这种隐式解引用机制为高性能系统编程带来如脚本语言般纯净、清爽的语法，极大地提升了代码的易读性。

身份：取地址运算符 *expr

为了获取局部变量或资源的原始物理内存地址，Toka 提供了 *expr 语法。该运算会返回一个指向该变量内存位置的原始指针 *T：

fn address_of_example() {
    auto a# = 42
    auto *raw_ptr = *a
    println("addr: {}", raw_ptr)
}

[!NOTE] 帽子标记符号（如 ^ 或 ~）并不代表“取地址”。帽子是严格的指针手柄类型修饰符，而 *expr 才是用于在运行时提取内存地址的运算符。

借用指针 & 与引用

**借用指针（&）**是一种安全的引用机制，允许在不转移所有权的前提下，临时、且接受编译器静态检查地访问某个灵魂（Soul）的数据。

干净的局部变量借用

当借用一个普通的、非数组成员的局部变量时，完全不需要加括号。直接在灵魂标识符前添加 & 即可创建借用指针：

auto x = 42
auto &y = &x // y 是指向 x 灵魂的借用指针，无需冗余括号

成员访问链借用的视觉歧义限制

当你试图借用结构体或 Shape 内部的特定字段（即成员访问链）时，如果直接写成 &pt.x，会产生语法歧义。这在视觉上无法辨清你究竟是想借用整个成员链 &(pt.x)，还是想在已借用的指针上访问成员 (&pt).x。

为了确保代码的明确性与类型安全，Toka 编译器会拒绝无括号的 &pt.x 编译，并提供两种清晰且合法的写法：

1. 方案 A（标准括号式）：显式地为成员链加括号：&(pt.x)。
2. 方案 B（帽子终端形态，Hat-Terminal Morphology）：将 & 借用符号直接嵌入点运算符和终端字段名之间：pt.&x。

pt.&x 是一种直观的表达形式，使借用操作能够直接融入到成员访问链之中。

fn borrow_example() {
    auto x = 42
    auto &y = &x // Clean local variable borrow, no parentheses needed!
    
    auto pt = Point(x = 10, y = 20)
    
    // Member borrow Path A: standard parentheses
    auto &rx1 = &(pt.x)
    
    // Member borrow Path B: Hat-Terminal Morphology (Toka's signature aesthetic)
    auto &rx2 = pt.&x
    
    println("y: {}, rx1: {}, rx2: {}", y, rx1, rx2)
}

所有权与帽子

Toka 中的所有权完全由帽子原则（Hat Principle）支配。与将内存分配掩盖在泛型类型系统之下的传统做法不同，Toka 使用独特的帽子标记符号（sigil），在语法上将值的所有权模型、拷贝/移动语义以及访问权限昭示得一清二楚。

四种所有权模型

Toka 定义了四种指针类型学，每种对应不同的资源生命周期管理策略：

1. * — 原始指针（人工管理生命周期）

底层原始指针提供零编译期安全保障，必须在 unsafe 块中进行手动分配与释放：

fn raw_ptr_example() {
    unsafe {
        auto *p# = alloc i32
        p = 99
        println("raw: {}", p)
    }
}

2. ^ — 独占指针（独占堆所有权）

独占指针强制执行严格的独占所有权。在任何时刻，一个堆资源只能有一个 ^ 手柄指向它。当独占指针离开其声明的作用域时，其绑定的内存会被自动、即时地释放：

fn unique_ptr_example() {
    auto ^p = new i32(42)
    auto ^q = ^p
    println("unique: {}", q)
}

3. ~ — 共享指针（引用计数共享所有权）

共享指针允许多个手柄通过线程安全的引用计数共享对同一堆资源的所有权。当最后一个指向它的 ~ 手柄离开作用域时，资源才会被自动释放：

shape Point(x: i32, y: i32, z: i32)
auto ~s1# = new Point(x = 100, y = 200, z = 0)
auto ~s2# = ~s1  // 共享拷贝（引用计数增加）
s2.x = 300       // 直接修改底层灵魂（Soul）的数据

4. & — 借用指针（引用语义）

借用指针是由指针分析层（PAL Checker）静态受检的、对现有灵魂的临时引用，它不持有资源所有权。

移动 vs. 拷贝

Toka 拥有清晰的规则来区分数据的“拷贝”与所有权的“转移”：

默认拷贝语义

默认情况下，Toka 中的普通赋值执行的是拷贝。对于简单标量类型（如 i32、bool）执行按值拷贝，对于复杂的 Shape 结构体执行浅拷贝：

fn move_copy_example() {
    auto a# = 42
    auto b = a
    a = 99
    println("a: {}, b: {}", a, b)
}

默认移动语义（独占指针）

移动语义在默认情况下仅适用于独占指针（^）。将一个独占指针赋值给另一个，会自动将堆资源的独占所有权从源转移到目标，这会使源手柄立即失效：

shape Point(x: i32, y: i32, z: i32)
auto ^p1 = new Point(x = 10, y = 20, z = 0)
auto ^p2 = ^p1  // 所有权自动转移（移动）至 p2；p1 之后不再有效！

使用 cede 进行显式移动

对于其他普通类型（如自定义 Shape 或 string），默认执行的是拷贝语义。为了显式转移所有权（从而避免拷贝开销），必须使用 cede 关键字。cede 操作会强制将资源移动到目标，并使原变量立即失效：

auto s1 = string::from("hello")
auto s2 = cede s1 // 显式移动：s1 之后不再有效

函数参数：零拷贝引用捕获

在 Toka 中，函数形参默认是不可变的，并且是通过极其高效的 “零拷贝隐式引用捕获机制” 进行传递的。

编译器会自动在底层以引用形式传递参数，带来零运行时开销和零拷贝。因此，对于标准的函数参数传递，你完全不需要编写任何特殊的指针标记符号，除非你明确打算传递或重绑定指针手柄本身：

fn process(data: i32) {
    println("data: {}", data)
}

fn borrow_func_example() {
    auto val = 10
    process(val)
    println("val: {}", val)
}

可变性标记 # 与权限视图（Permission View）

Toka 引入了 # 标记来声明和追踪可变访问权限。它的使用受到编译器生存周期的严苛规范，既消除了冗余的语法噪声，又最大化地提供了视觉安全度。

1. 声明可变性

要在局部变量声明时指定其为可变，必须在声明点的标识符尾部追加 #：

fn mutable_local_example() {
    auto val# = 42
    val = 99 // Everyday context assignment: NO '#' suffix allowed here!
    println("val: {}", val)
}

2. Everyday 上下文（赋值表达式）中严禁标注

一旦变量在声明时被指定为 mutable，其可变状态便已在类型系统的 权限视图（Permission View） 中注册完毕。因此，在日常的赋值表达式或普通使用中，绝对不允许在变量名后追加 # 后缀：

auto val# = 42
val = 99 // Everyday 赋值：禁止写为 val# = 99！否则会引发编译器错误。

这极大地避免了在常规书写中引入无意义的语法噪声。

3. 可变方法调用点（接收者后缀）强制要求

Toka 的一项重要安全设计在于：任何会发生状态修改的方法调用，都必须在调用点进行显式标示。

当调用一个会修改 Shape 状态的方法时，编译器要求在接收者对象（Receiver）后追加 # 后缀（例如 obj#.mutate()）。这使得状态的可变性在代码中直观易见，方便代码阅读与后续审计：

shape Counter (
    val#: i32 = 0
)


impl Counter@encap {
    pub fn clone(self) -> Counter {
        return Counter(val = self.val)
    }

    fn drop(self#) {}

    pub fn increment(self#) {
        self.val = self.val + 1
    }
}



fn mutable_method_example() {
    auto c# = Counter(val = 10) // Declaration: '#' is required for mutability
    c#.increment()             // Mutation Site: '#' receiver suffix is required and highly visible!
    println("c.val: {}", c.val)
}

通过将 # 限制在“变量声明点”与“方法接收者可变调用点”，Toka 保持了语法的直观性，并提供了明确的安全可视度。

内存安全与 PAL

Toka 在编译时静态实现严苛的内存安全，既不需要运行时垃圾回收器（Garbage Collector）沉重的性能开销，也无需编写繁琐、复杂的显式生命周期标注。

这得益于编译器核心的 指针分析层（Pointer Analysis Layer，简称 PAL Checker），它作为一个高效的静态验证引擎，负责在编译期审查帽子指针类型学和访问权限修饰符的使用。

PAL 检查器的工作原理

PAL Checker 在编译时执行静态数据流分析，以追踪 codebase 中每个资源在类型系统中的权限视图（Permission View）与活动生命周期区间（Active Scope/Region）。

通过要求显式的指针修饰符（如 ^、~、& 等帽子标记）和强可视化的修改意图标示（如变量声明时的 # 以及方法调用接收者尾部的 #），编译器获得了极其完备的语义信息，得以自动化地进行严格的安全检查。

它在编译期提供四大核心内存安全支柱保证：

1. 移动后不可使用（Use After Move）

独占指针 ^ 代表堆资源的独占所有权。当它被赋值给另一个句柄时，原句柄会在编译器状态机中被标记为“已移动（moved-from）”。PAL Checker 会静态拦截任何后续对该失效原变量的读写操作：

fn no_use_after_move_example() {
    auto ^p = new i32(42)
    auto ^q = ^p
    println("q: {}", q)
}

2. 无悬垂引用（Dangling References）

借用指针 & 的生命周期绝不能超过其所指向的“灵魂（Soul）”。PAL Checker 会静态跟踪 underlying soul 的生命区间，一旦发现借用指针的持有时间超过了灵魂的生存范围（例如试图返回局部借用），将立刻拒绝编译并报错。

3. 无双重释放（Double Free）

对于拥有资源所有权的手柄（如 ^ 独占指针或最后一个 ~ 共享指针），编译器会在其离开声明的作用域时，自动、确定性地注入析构与内存回收调用。而已被移动或被 cede 的手柄会被静态绕过，从根本上消除了双重释放的可能。

4. 无数据竞争 / 别名违规（Data Races & Aliasing Violations）

为了彻底杜绝并发数据竞争与读写冲突，Toka 强力推行借用别名核心准则：在任何给定的时间点，对于同一个灵魂，你只能拥有唯一的可变借用，或者拥有多个只读借用，但绝不能两者并存。

由于 Toka 强制要求在调用任何可变方法时显式标注接收者（如 obj#.mutate()），PAL Checker 能够以极高的效率和安全性，在编译期轻而易举地对每一次方法调用边界进行排他性可变借用校验。

零拷贝实参安全

Toka 的函数参数传递采用的是 “零拷贝隐式引用捕获机制”。当实参被传入函数时，PAL Checker 会自动在底层以引用形式捕获参数，带来零拷贝与零运行时开销。

由于函数内部的形参默认是不可变的（immutable），因此调用方传入的实参绝无被篡改的风险：

fn show(x: i32) {
    println("x: {}", x)
}

fn borrowing_safe_example() {
    auto val = 10
    show(val)
    println("val: {}", val)
}

如果函数需修改参数，需在函数签名中将参数显式声明为可变（#），此时 PAL Checker 将在调用点强制执行排他性的可变借用规则校验。

PAL 静态保障一览表

PAL Checker 在编译阶段对内存安全进行静态分析与检查：

通过将内存安全的检查工作转移到编译器的指针分析层（PAL），Toka 在无需手动标注生命周期的同时，为开发者提供了兼顾运行效率与内存安全的开发体验。

高级特性

在掌握了变量、控制流等语言基础，并深刻理解了 帽子原则（Hat Principle） 关于灵魂（Soul）与肉身（Handle）的管理之后，你已经跨过了 Toka 最陡峭的学习曲线。现在，我们将进入 Toka 的高级特性世界。

Toka 的高级特性是为了在保持零拷贝隐式引用捕获和运行性能的前提下，为开发者提供高层次的抽象表达力。在这里，你将看到强类型系统与代数数据类型的结合。

本章知识图谱

本章将带你深入探索以下四个系统开发的核心利器：

flowchart TD
    Root("Toka 高级特性与抽象表达")

    Generics("**泛型 Generics**")
    Error("**错误处理 Error**")
    Pattern("**模式匹配 Pattern**")
    Async("**并发编程 Async**")

    GenericsDesc("零开销多态表达<br>规避“灵魂塌陷”约束")
    ErrorDesc("代数数据类型契约<br>短路机制 (!) 传播")
    PatternDesc("解构 Shape 实体<br>配合 if 条件守卫")
    AsyncDesc("安全轻量协程<br>多核并发并行")

    Root --> Generics & Error & Pattern & Async
    
    Generics --> GenericsDesc
    Error --> ErrorDesc
    Pattern --> PatternDesc
    Async --> AsyncDesc

    style Root fill:#1e1b4b,stroke:#a855f7,stroke-width:2px,color:#fff;
    style Generics stroke:#3b82f6,stroke-width:1.5px;
    style Error stroke:#10b981,stroke-width:1.5px;
    style Pattern stroke:#f59e0b,stroke-width:1.5px;
    style Async stroke:#ec4899,stroke-width:1.5px;

1. 泛型（Generics）

在强类型安全的前提下，提供零运行开销的多态表达。你将学习到独特的 Morphic 泛型类型（如 'A），以及在定义 Shape 时如何通过对应的 'first 单引号字段前缀来规避 “灵魂塌陷（Soul Collapse）” 的底层约束规则。

2. 错误处理

Toka 摒弃了运行时异常抛出机制，而是通过 Option<T> 和 Result<T, E> 代数数据类型来表达和传递错误。配合简洁的 ! 短路操作符，让你的错误处理流程比传统的嵌套匹配更加清晰、直接。

3. 模式匹配

模式匹配允许你以直观的方式解构 Shape、分发逻辑。这里你将明确为何 Toka 强制使用 Variable Pattern 判定，并学习如何结合 if 条件守卫进行精细的范围与边界过滤。

4. 并发编程

Toka 提供了协程与线程基元，用于在内存安全的前提下构建并发系统。

[!TIP] 心智模型转换提醒 在阅读本大章时，请关注传统面向对象语言中继承体系和运行时多态的替代方案。Toka 的多态是通过 Shape 解构、Trait 约束和模式匹配 在编译期完成的。用好帽子原则，你的代码将兼具安全与高效的运行性能。

泛型（Generics）

泛型允许你编写灵活、可复用的代码，适用于任何类型，同时保持编译时安全性。

在 Toka 中，定义自定义泛型时通常使用直观的 T（不带单引号）形式。带单引号的 'T（Morphic 泛型）仅在编写通用容器场景下需要，用以动态兼容灵魂元素与指针元素。

泛型函数

使用标准的 T 语法定义泛型函数：

fn identity<T>(value: T) -> T {
    return value
}

auto x = identity(42)      // 适用于整数
auto y = identity("hello") // 适用于字符串

泛型约束

使用 trait 约束泛型：

fn max<T: @PartialOrd>(a: T, b: T) -> T {
    if a > b {
        return a
    }
    return b
}

该函数适用于任何实现了 @PartialOrd 的类型。

泛型数据结构

pub shape Pair<'A, 'B>(
    'first: 'A,
    'second: 'B
)

impl<'A, 'B> Pair<'A, 'B> {
    pub fn new(first: 'A, second: 'B) -> Pair<'A, 'B> {
        return Pair('first = first, 'second = second)
    }
    
    pub fn first(self) -> 'A {
        return self.first
    }
    
    pub fn second(self) -> 'B {
        return self.second
    }
}

当定义具有 Morphic 泛型类型（那些带有单引号前缀的类型，如 'A）的 Shape 时，Toka 强制执行一条严格规则：对应的字段名称也必须带有单引号前缀（例如 'first: 'A）。这表明这些字段能够动态接受不同的指针形态状态，从而规避“灵魂塌陷”。但是，在调用方法或获取字段值时，应像往常一样使用常规字段名称进行引用（例如使用 self.first，而不是 self.'first）。

Morphic 泛型与普通泛型的选择

在定义自定义泛型或泛型参数时，Toka 支持带单引号（如 'T）和不带单引号（如 T）两种写法。它们的核心区别和应用场景如下：

• T（普通泛型，不带单引号）：一般自定义泛型时仅需要 T 这种形式。无论你是编写高层业务逻辑、自定义普通数据结构，还是编写普通的辅助函数，均直接推荐使用标准泛型 T。它完全消除了单引号的语法噪点，最符合日常开发直觉。
• 'T（Morphic 泛型，带单引号）：仅在开发底层通用容器或极少数基础库组件（如 Vec、HashMap、Slab 或并发通道 Channel）时，才需要使用 'T 参数写法。因为通用容器必须同时兼容灵魂元素（裸结构体值类型）与指针元素（如 ^ 独占指针或 ~ 共享指针等），Morphic 泛型能够通过多态形态自适应避免“灵魂塌陷”，确保极高效率。

[!NOTE] 在大多数日常编程中，你只需要像传统编程语言那样使用 T 即可，这极大地简化了代码的可读性。

类型推断

在大多数情况下，Toka 可以推断泛型类型，因此你很少需要显式指定：

fn pair<'A, 'B>(a: 'A, b: 'B) -> Pair<'A, 'B> {
    return Pair::new(a, b)
}

auto p = pair(1, "world")  // Pair<i32, str>

泛型要求

使用 trait 约束来指定泛型类型必须支持的操作：

错误处理

Toka 通过 Result 和 Option 类型提供类型安全错误处理能力。这种基于代数数据类型（ADT）的错误处理模型可追溯到 ML 语言家族（如 Standard ML、OCaml）以及 Haskell，后由 Rust 引入现代系统级编程中。Toka 采用这一模型，并通过用于错误传播的 ! 操作符，使其更加简洁直观。

Option 类型

使用 Option 表示可能存在或不存在的值：

import core/option::{Option}
import std/io::println

fn find_user(id: i32) -> Option<string> {
    if id == 1 {
        return Option<string>::Some(string::from("Alice"))
    }
    return Option<string>::None
}

fn main() -> i32 {
    auto result = find_user(1)
    match result {
        auto Option<string>::Some(&name) => println("找到：{}", name)
        auto Option<string>::None => println("未找到用户")
    }
    return 0
}

Result 类型

使用 Result 表示可能成功或失败的操作：

import core/result::{Result}

fn divide(a: f64, b: f64) -> Result<f64, string> {
    if b == 0.0 {
        return Result<f64, string>::Err(string::from("除数不能为零"))
    }
    return Result<f64, string>::Ok(a / b)
}

Result 类型有两个泛型参数：

• T — 成功值的类型
• E — 错误值的类型

对 Result 进行模式匹配

import core/result::{Result}
import std/io::println

fn divide(a: f64, b: f64) -> Result<f64, string> {
    if b == 0.0 {
        return Result<f64, string>::Err(string::from("除数不能为零"))
    }
    return Result<f64, string>::Ok(a / b)
}

fn main() -> i32 {
    match divide(10.0, 2.0) {
        auto Result<f64, string>::Ok(value) => println("结果：{}", value)
        auto Result<f64, string>::Err(&msg) => println("错误：{}", msg)
    }
    return 0
}

使用 ! 进行短路传播

使用 ! 运算符自动传播错误：

import core/result::{Result}

fn read_file(path: string) -> Result<string, string> {
    return Result<string, string>::Ok(path)
}

fn parse(content: string) -> Result<string, string> {
    return Result<string, string>::Ok(content)
}

fn format_result(parsed: string) -> string {
    return parsed
}

fn process_file(path: string) -> Result<string, string> {
    auto content = read_file(path)!  // 出错时提前返回
    auto parsed = parse(content)!    // 同上
    return Result<string, string>::Ok(format_result(parsed))
}

这比嵌套的 match 语句要干净得多。

使用 or 设置默认值

在出错时提供默认值：

auto value = parse_int("42").unwrap_or(0)  // 如果解析失败则使用 0

自定义错误类型

你可以定义结构化的错误类型：

import core/result::{Result}

pub shape Config()

pub shape ParseError(
    line: i32,
    col: i32,
    message: string
)

fn parse_config(text: string) -> Result<Config, ParseError> {
    if text.len() == 0 {
        return Result<Config, ParseError>::Err(ParseError(line = 0, col = 0, message = string::from("空输入")))
    }
    return Result<Config, ParseError>::Ok(Config())
}

模式匹配

模式匹配是 Toka 最富有表现力的特性之一，允许你简洁地解构和匹配值。

基本 Match

fn describe(n: i32) -> str {
    return match n {
        0 => pass "零"
        1 => pass "一"
        _ => pass "许多"
    }
}

_ 通配符匹配任意值——它是默认情况。

范围模式

对范围进行匹配：

auto score = 85
auto grade = match score {
        auto s if s >= 0 && s < 60 => { pass "不及格" }
        auto s if s >= 60 && s < 70 => { pass "D" }
        auto s if s >= 70 && s < 80 => { pass "C" }
        auto s if s >= 80 && s < 90 => { pass "B" }
        auto s if s >= 90 && s <= 100 => { pass "A" }
        _ => { pass "无效分数" }
}

请注意，Toka 不支持原生范围模式匹配（如 0..10）。相反，应使用带有 if 守卫表达式的变量来进行范围检查。

匹配 Option

import std/io::println
import core/option::Option

fn main() -> i32 {
    auto id = 1
    auto opt: Option<str> = Option<str>::None
    match opt {
        auto Option<str>::Some(&name) => { println("找到：{}", name) }
        auto Option<str>::None => { println("未找到用户") }
    }
    return 0
}

匹配 Result

import std/io::println
import core/result::Result

fn main() -> i32 {
    auto res: Result<f32, str> = Result<f32, str>::Ok(5.0)
    match res {
        auto Result<f32, str>::Ok(value) => { println("结果：{}", value) }
        auto Result<f32, str>::Err(&msg) => { println("错误：{}", msg) }
    }
    return 0
}

解构 Shape

对自定义 shape 进行模式匹配：

import std/io::println

pub shape Point(x: i32, y: i32)

fn origin(p: Point) {
    match p {
        auto pt if pt.x == 0 && pt.y == 0 => { println("在原点上") }
        auto pt if pt.y == 0 => { println("在 X 轴上") }
        auto pt if pt.x == 0 => { println("在 Y 轴上") }
        _ => { println("在其他位置") }
    }
}

Match 作为表达式

Match 返回一个值，因此可以在赋值中使用：

auto score = 85
auto grade = match score {
    auto s if s >= 90 && s <= 100 => pass "A"
    auto s if s >= 80 && s < 90 => pass "B"
    auto s if s >= 70 && s < 80 => pass "C"
    auto s if s >= 60 && s < 70 => pass "D"
    _ => pass "F"
}

不支持基于类型的匹配

Toka 不支持直接对类型进行模式匹配（例如在 match 表达式内部书写 i32 => ... 或 str => ...）。在分支中若使用不带标准语法的类型名称，将被视为一个新的变量绑定模式（Variable Pattern），这会匹配任意值并遮蔽其他分支，从而导致编译错误或不可达分支。

并发编程

Toka 通过任务（task）和消息传递提供轻量级的并发能力，实现高效的并行执行。

任务

使用 task 模块创建并发任务：

import std/io::println
import std/thread::thread_spawn

fn worker(id: i32) -> i32 {
    println("Worker {} 开始工作", id)
    // 执行任务...
    println("Worker {} 完成", id)
    return 0
}

fn main() -> i32 {
    auto t1# = thread_spawn<i32>({ => return cede worker(1) })
    auto t2# = thread_spawn<i32>({ => return cede worker(2) })
    
    t1#.join()
    t2#.join()
    return 0
}

MPSC 通道

使用 MPSC（多生产者，单消费者）通道在任务间通信：

import std/channel::channel
import std/thread::thread_spawn
import std/io::println

fn main() -> i32 {
    auto pair# = channel<i32>()
    
    auto tx# = cede pair.tx
    auto rx# = cede pair.rx
    
    thread_spawn<i32>({ [cede tx] => 
        tx#.send(cede 42)
        return cede 0
    })
    
    thread_spawn<i32>({ [cede rx] =>
        auto res_opt = rx#.recv()
        println("收到一条消息！")
        return cede 0
    })
    
    return 0
}

原子操作

使用原子类型实现无锁并发访问：

import std/atomic::*

fn main() -> i32 {
    auto counter = AtomicI32::new(0)
    counter.fetch_add(1, Ordering::SeqCst)
    return 0
}

Mutex / 同步

用于共享可变状态：

import std/sync::Mutex

fn main() -> i32 {
    auto lock# = Mutex<i32>::new(0:i32)
    
    auto g = lock#.lock().unwrap()
    // 安全访问共享数据
    // g 在离开作用域时自动释放
    return 0
}

安全保障

Toka 的并发模型防止：

• 数据竞争：两个任务不能同时写入同一内存
• 死锁：编译器分析锁的顺序
• Send/Sync 违规：非线程安全的类型不能在任务间共享

标准库概览

Toka 的标准库提供了全面的模块集，满足日常编程任务的需求。

模块结构

标准库分为四个层级：

lib/core/ — 核心语言原语

这些模块提供了语言本身所依赖的基础类型和 trait：

lib/sys/ — 底层系统原语

这些模块提供了与操作系统和底层运行时的直接绑定与原语：

lib/std/ — 标准库

面向应用程序开发的即用型标准模块：

lib/stdx/ — 实验性 / 扩展库 (stdx)

仍在演进中的新模块或可选扩展：

设计理念

Toka 的标准库遵循以下原则：

1. 零依赖 — 所有内容都使用纯 Toka 和 LLVM 后端构建
2. 一致的 API — 不同模块之间采用相似的模式
3. 错误感知 — 每个可能失败的操作都返回 Result 或 Option
4. 高性能 — 编译为原生代码，无隐藏开销

IO 与文件系统

Toka 的 IO 模块提供文件操作、控制台输出和流处理——全部通过简洁一致的 API 实现。

控制台输出

import std/io::{println, print}

println("Hello with newline")  // 打印并换行
print("No newline here")       // 打印不换行

读取文件

import std/fs
import core/result::Result
import std/io::IoStringResult

fn read_config(path: string) -> IoStringResult {
    return fs::read_to_string(path)
}

写入文件

import std/fs
import core/result::Result

fn save_data(path: string, data: string) -> Result<bool, string> {
    return fs::write_string(path, data.as_str())
}

文件系统操作

fs 模块提供标准的文件操作：

import std/fs
import std/io::println
import core/option::Option

fn manage_files() {
    auto path = string::from("output")
    if fs::exists(path.clone()) {
        fs::remove_dir(path)
    }
    
    fs::create_dir(string::from("output"))
    
    auto dir# = fs::read_dir(string::from("."))
    loop {
        auto entry = dir#.next()
        if entry.is_none() { break }
        println("{}", entry.unwrap())
    }
}

路径操作

import std/io::println
import std/path

fn example() {
    auto full = path::join(string::from("dir"), string::from("file.txt"))
    println("{}", full.c_str())
    
    auto ext = path::extension(string::from("data.json"))
    println("{}", ext.c_str())
    
    auto stem = path::file_stem(string::from("data.json"))
    println("{}", stem.c_str())
}

环境变量

import std/io::println
import std/env
import core/option::Option

fn example() {
    auto home_opt = env::var(string::from("HOME"))
    auto home = home_opt.unwrap_or(string::from("/tmp"))
    println("Home directory: {}", home)
    
    env::set_var(string::from("MY_APP_DEBUG"), string::from("true"))
}

集合（Collections）

Toka 提供丰富的数据结构，用于高效存储和组织数据。

Vec（动态数组）

import std/io::println
import std/vec::Vec

fn example() {
    auto numbers# = Vec<i32>::new()
    
    numbers#.push(1)
    numbers#.push(2)
    numbers#.push(3)
    
    println("{}", numbers.at(0))  // 1
    
    auto i# = 0:usize
    loop i < numbers.len() {
        println("{}", numbers.at(i))
        i = i + 1:usize
    }
}

Map（哈希映射）

import std/io::println
import std/hashmap::HashMap
import core/option::Option
import core/primitives

fn example() {
    auto scores# = HashMap<i32, i32>::new()
    
    scores#.insert(1, 95)
    scores#.insert(2, 87)
    
    match scores.get(1) {
        auto Option<i32>::Some(score) => { println("ID 1: {}", score) }
        auto Option<i32>::None => { println("未找到") }
    }
}

BTreeMap（有序映射）

import std/io::println
import std/btreemap::BTreeMap
import core/primitives

fn example() {
    auto items# = BTreeMap<str, i32>::new()
    
    items#.insert("apple", 5)
    items#.insert("banana", 3)
    items#.insert("cherry", 8)
    
    println("迭代完成")
}

BTreeSet（有序集合）

import std/io::println
import std/btreeset::BTreeSet
import core/primitives

fn example() {
    auto unique# = BTreeSet<i32>::new()
    
    unique#.insert(3)
    unique#.insert(1)
    unique#.insert(2)
    unique#.insert(1)  // 重复值，被忽略
    
    println("{}", unique.len())
}

Deque（双端队列）

import std/io::println
import std/deque::VecDeque

fn example() {
    auto queue# = VecDeque<str>::new()
    
    queue#.push_back("first")
    queue#.push_back("second")
    queue#.push_front("priority")
    
    queue#.pop_front()
    println("{}", queue.len())
}

Slab（分代插槽分配器）

Toka 彻底剔除了链表以拥抱现代 CPU 的 contiguous 物理内存拓扑模型。作为替代，标准库引入了分代插槽分配器 std/slab::Slab。它在连续的内存空间（Vec）中以插槽（Slot）形式管理对象，支持 $O(1)$ 快速插入、删除与查询，并使用 SlabID 分代（Generation）检查技术，从根本上杜绝了 ABA 悬空指针/失效索引引用的安全隐患。

Slab 的查询方法（get 与 get_mut）采用了高级的生命周期依赖声明（<- self），返回具有零拷贝特性的 Option<&'T> 和 Option<&#'T> 借用。

import std/slab::{Slab, SlabID}
import std/io::{println}
import core/option::{Option}

shape Entity (
    name: string,
    val: i32
)

fn main() -> i32 {
    auto slab# = Slab<Entity>::new()

    // 1. 插入元素，返回含有 index 与 generation 的 SlabID
    auto id1 = slab#.insert(Entity(name = string::from("alpha"), val = 10))
    auto id2 = slab#.insert(Entity(name = string::from("beta"), val = 20))

    // 2. 零拷贝安全读取借用视图
    auto e1_opt = slab.get(id1.clone())
    if e1_opt.is_some() {
        auto &e1 = e1_opt.unwrap()
        println("ID1 val: {}", e1.val as i64) // 10
    }

    // 3. 删除元素并归还插槽
    auto removed = slab#.remove(id1.clone())

    // 4. 再次插入元素：Slab 将自动复用刚刚释放的插槽 (Slot 0)
    // 但分代数（Generation）会自动递增至 2！
    auto id3 = slab#.insert(Entity(name = string::from("gamma"), val = 30))

    // 5. 此时使用旧的已失效 id1 去获取数据将安全地返回 None，完美拦截 ABA 问题！
    auto old_opt = slab.get(id1)
    assert(old_opt.is_none(), "generational ID should prevent ABA stale read")

    return 0
}

Heap（优先队列）

import std/io::println
import std/heap::BinaryHeap
import core/primitives

fn example() {
    auto max_cmp: fn(i32, i32) -> bool = { a, b => a > b }
    auto heap# = BinaryHeap<i32>::new(max_cmp)
    heap#.push(5)
    heap#.push(10)
    heap#.push(3)
    
    heap#.pop()
    println("10")
}

Set（哈希集合）

import std/io::println
import std/hashset::HashSet
import core/primitives

fn example() {
    auto tags# = HashSet<i32>::new()
    tags#.insert(1)
    tags#.insert(2)
    tags#.insert(3)
    
    if tags.contains(2) {
        println("找到 2！")
    }
}

网络编程

Toka 的网络模块提供 TCP、UDP 和 HTTP 能力，用于构建网络应用。

HTTP 客户端

使用 stdx/net/http 模块发起 HTTP 请求：

import core/result::Result

// 注意：HTTP 客户端正在开发中
fn fetch(url: string) -> Result<string, string> {
    // auto response = http::get(url)!
    // return Ok(response.body)
    return Result<string, string>::Ok(string::from("Response"))
}

HTTP 服务器

使用 stdx/net/http 模块构建简单的 HTTP 服务器：

import stdx/net/http::{HttpResponse, HttpRequest}

// 注意：HTTP 服务器通过将 std/net 与 stdx/net/http 集成构建
fn main() -> i32 {
    // auto listener# = TcpListener::bind(addr)
    // auto stream# = listener#.accept()
    // auto req# = parse_http_request(req_str)
    return 0
}

TCP 连接

使用 net 模块进行原始 TCP 通信：

import std/net::TcpStream
import std/io::println
import core/result::Result

fn handle_client(stream#: TcpStream) {
    auto buf: [u8; 1024] = [0:u8; 1024]
    auto *buf_ptr# = &buf[0] as *u8
    auto res = stream#.read(*buf_ptr, 1024:usize)
    match res {
        auto Result<usize, string>::Ok(n) => {
            println("收到 {} 字节", n)
            stream#.write_string(string::from("ACK"))
        }
        auto Result<usize, string>::Err(&e) => {
            println("错误")
        }
    }
}

WebSocket

对于实时双向通信，使用 stdx/websocket 模块：

import std/io::println

// 注意：WebSocket 正在开发中
fn echo_server() {
    // auto ws = websocket::Server::new()
    // ws.on_message(|msg| => println("Got: {}", msg))
    // ws.listen(9000)
}

URL 解析

import std/io::println
import core/result::Result
import stdx/net/url::{Url, parse_url}

fn example() {
    auto url_res = parse_url(string::from("https://api.example.com:8080/data?id=1#top"))
    match url_res {
        auto Result<Url, string>::Ok(&url) => {
            println("主机：{}", url.host)
            println("端口：{}", string::from_int(url.port as i32))
        }
        auto Result<Url, string>::Err(&err) => {
            println("错误：{}", err)
        }
    }
}

时间与数学

Toka 提供全面的时间处理和数学函数，适用于科学计算和系统编程。

获取当前时间

import std/time::{SystemTime}
import std/io::println

fn example() {
    auto now = SystemTime::now()
    // println("Current timestamp: {}", now.unix())
}

时间格式化

import std/time::{SystemTime}
import std/io::println

fn format_date() {
    auto now = SystemTime::now()
    // auto formatted = now.format("%Y-%m-%d %H:%M:%S")
    // println("Date: {}", formatted)
}

持续时间和计时器

import std/time::{Instant}
import std/io::println

fn measure() {
    auto start = Instant::now()
    
    // 执行一些工作...
    
    auto elapsed = start.elapsed()
    println("耗时：{} 毫秒", elapsed.as_millis())
}

数学函数

import std/math
import std/io::println

fn calculations() {
    auto x = 3.14159
    
    println("{}", math::sin(x))       // 正弦
    println("{}", math::cos(x))       // 余弦
    println("{}", math::sqrt(16.0))   // 平方根 → 4.0
    // println(str(math::abs(-5)))      // 绝对值 → 5
    // println(str(math::pow(2.0, 8)))  // 幂运算 → 256.0
}

随机数

import stdx/rand/rand::{Random}
import std/io::println

fn gen_random() {
    auto rng# = Random::new(123:u64, 1:u64)
    auto dice = rng#.next_u32() % 6 + 1
    println("你掷出了：{}", dice)
    
    // 注意：secure_bytes 正在开发中
    // auto secure = rand::secure_bytes(32)
}

数学常量

// 数学极限值（来自 lib/core/types.tk）
pub const MY_LIMITS = (
    u8 = (min = 0, max = 255, bits = 8),
    i32 = (min = -2147483648, max = 2147483647, bits = 32),
    u64 = (min = 0, max = 18446744073709551615, bits = 64),
    f32 = (
        min_positive = 1.17549435e-38,
        epsilon = 1.19209290e-07,
        bits = (nan = 0x7fc00000, infinity = 0x7f800000, neg_zero = 0x80000000)
    )
)

fn dummy_limits() {}

序列化

Toka 提供对数据序列化和反序列化的内置支持，开箱即用支持 JSON。

JSON 编码

将数据序列化为 JSON：

import stdx/serde/json
import std/io::println

pub shape Person(
    name: string,
    age: i32,
    active: bool
)

fn encode() {
    auto person = Person(name = string::from("Alice"), age = 30, active = true)
    // auto json_str = json::to_json(person)
    // println("{}", json_str)  // {"name":"Alice","age":30,"active":true}
}

JSON 解码

将 JSON 解析回 Toka 类型：

import stdx/serde/json
import std/io::println
import core/result::Result

pub shape Person(
    name: string,
    age: i32,
    active: bool
)

fn decode() {
    auto data = "{\"name\":\"Bob\",\"age\":25,\"active\":false}"
    // auto person_res = json::deserialize_shape<Person>(data)
}

Base64 编码

import stdx/encoding/base64
import std/io::println

fn example() {
    auto original = string::from("Hello, Toka!")
    auto encoded = base64::encode_str(original.as_str())
    println("{}", encoded)  // SGVsbG8sIFRva2Eh
    
    // 注意：base64::decode 正在开发中
    // auto decoded = base64::decode(encoded)!
}

Hex 编码

import stdx/encoding/hex
import std/io::println

fn example() {
    auto bytes: [u8; 5] = [0x48, 0x65, 0x6C, 0x6C, 0x6F]
    auto hex_str = hex::encode_hex(*bytes as *[u8], 5:usize)
    println("{}", hex_str)  // 48656C6C6F
    
    // 注意：hex::decode 正在开发中
    // auto decoded = hex::decode(hex_str)!
}

自定义序列化

为自定义类型实现 @Serialize trait：

import stdx/serde/json::{@ToJson}

pub shape Person(name: string, age: i32, active: bool)

impl Person@ToJson {
    pub fn write_json(self, buf#: string) -> string {
        buf#.push_str("{\"name\":\"")
        buf#.push_str(self.name.as_str())
        buf#.push_str("\",\"age\":")
        buf#.push_str(string::from_int(self.age).as_str())
        buf#.push_str("}")
        return buf
    }
}

密码学

Toka 提供标准的密码学模块，支持常用的哈希算法。

MD5 哈希

import std/io::println
import stdx/crypto/md5::Md5

fn example() {
    auto md5# = Md5::new()
    md5#.update("Hello, Toka!")
    auto hash = md5#.finalize_hex()
    println("MD5: {}", hash)
}

SHA-1

import std/io::println
import stdx/crypto/sha1::Sha1

fn example() {
    auto sha1# = Sha1::new()
    sha1#.update("Hello, Toka!")
    auto hash = sha1#.finalize_hex()
    println("SHA1: {}", hash)
}

SHA-256

import std/io::println
import stdx/crypto/sha256::Sha256

fn example() {
    auto sha256# = Sha256::new()
    sha256#.update("Hello, Toka!")
    auto hash = sha256#.finalize_hex()
    println("SHA256: {}", hash)
}

文件哈希

对文件内容进行哈希：

import std/fs
import stdx/crypto/sha256::Sha256
import core/result::Result

fn verify_file(path: string) -> Result<bool, string> {
    auto content = fs::read_to_string(path).unwrap()
    auto sha256# = Sha256::new()
    sha256#.update(content.as_str())
    auto computed = sha256#.finalize_hex()
    
    return Result<bool, string>::Ok(computed.len() > 0:usize)
}

安全随机数

用于密码学应用：

import stdx/rand/rand::Random

fn generate_key() -> u64 {
    // 伪随机字节（不安全，仅用于演示）
    auto rng# = Random::new(12345:u64, 1:u64)
    return rng#.next_u64()
}

密码学模块适用于：

• 密码哈希和验证
• 文件完整性检查
• 数据签名和验证
• 安全随机数生成

实战项目

将理论付诸实践，是真正掌握一门系统级编程语言的最佳途径。在完成了 Toka 语言基础、帽子原则和高级抽象的学习之后，本章将带领你通过三个精心设计的实战项目，完成从“语法学习者”到“系统开发者”的华丽蜕变。

这些项目绝非脱离现实的“玩具代码”，而是直击底层软件工程最核心的三个支柱：系统工具开发、高性能并发网络、语言与文本解析。

项目实战阶梯

本章包含的三个项目呈阶梯状递进，帮助你逐步建立起健壮 of 系统级开发心智：

flowchart TD
    Step1("**阶梯一：命令行工具**<br>熟悉官方 stdx/cli/flag 标准扩展 API")
    Step2("**阶梯二：HTTP 服务器**<br>打通原始 TCP 与 Hat Concurrency 并发安全")
    Step3("**阶梯三：手写正则引擎**<br>锻炼字符 Token 流控制与树状模式匹配算法")
    Champ("🏆 **进阶为系统级全能开发者**")

    Step1 --> Step2 --> Step3 --> Champ

    style Champ stroke:#a855f7,stroke-width:2px;

1. 用 stdx/cli/flag 构建 CLI 工具

• 工程价值：这是你的第一个实战项目。你将摆脱陈旧的多层链式调用，学习如何使用官方标准的内置 stdx/cli/flag 扩展包，通过非链式可变 self# API 优雅地解析命令行标志、处理布尔选项，以及利用模式匹配安全地收集和过滤定位参数（Positional Arguments）。

2. 高性能 HTTP 服务器

• 工程价值：如何利用 Toka 构建高并发、底层的网络服务？在这个项目中，你将从最底层的 TCP 监听（TcpListener）和连接接受（accept()）开始，结合多线程并发技术，手工编写一个符合 RFC 标准的高并发 HTTP 响应服务器。这是对帽子并发安全机制和 I/O 模块的一次全面大考。

3. 正则匹配引擎

• 工程价值：文本匹配和编译器前端是系统开发非常迷人的一环。你将挑战亲手实现一个微型的正则表达式引擎。在这个项目中，你将深入锻炼对 Token 字符流的控制、状态机的转移、树状数据结构的深层表示，以及如何利用 Toka 优雅的 match 模式匹配进行复杂的词法与句法分支匹配。

[!IMPORTANT] 开发须知与调试准备 在开始每个项目前，请确保你已经正确配置了 toka 命令行环境，并且编译器 tokac 可以正常工作。你可以通过以下基础命令快速运行和调试你的项目：

toka run src/main.tk -- -n Toka

在每个项目章节中，贤弟都为你准备了详细的单元测试和运行示例。建议你亲自动手敲下每一行代码，观察编译器的报错输出，这会让你对 Toka 的“肉身（Handle）”和“灵魂（Soul）”重绑定规则拥有更深骨髓的直觉。

用 stdx/cli/flag 构建 CLI 工具

在这个项目中，我们将使用 Toka 以及标准的 stdx/cli/flag 参数解析库来构建一个命令行工具。

项目设置

创建一个新项目：

toka init my-cli
cd my-cli

由于 stdx/cli/flag 是 Toka 中的标准库扩展，你不需要通过包管理器添加任何外部依赖。它开箱即用！

定义参数

import stdx/cli/flag::{Parser, ParsedArgs}
import std/env
import std/io

fn main() -> i32 {
    // Parser::new 接收程序名称和简短的描述
    auto parser# = Parser::new(string::from("my-cli"), string::from("一个用 Toka 构建的示例 CLI 工具"))
    
    // 向解析器中添加选项
    parser#.add_string(string::from("name"), 110:char, string::from("World"), string::from("你的名字"))
    parser#.add_bool(string::from("verbose"), 118:char, false, string::from("启用详细输出"))

    auto args = env::args()
    auto res = parser.parse(args)
    match res {
        auto Result<ParsedArgs, string>::Ok(parsed) => {
            auto who = parsed.get_string(string::from("name"))
            io::println("Hello, %s!", who.c_str())
            
            if parsed.get_bool(string::from("verbose")) {
                io::println("[Verbose] 正在以调试模式运行")
            }
        }
        auto Result<ParsedArgs, string>::Err(&err) => {
            if err == string::from("help requested") {
                parser.print_help()
                return 0
            }
            io::println("Error: %s", err.c_str())
            return 1
        }
    }
    return 0
}

运行

toka run src/main.tk -- -n Toka
# 输出：Hello, Toka!

toka run src/main.tk -- -n Toka -v
# 输出：Hello, Toka!
# [Verbose] 正在以调试模式运行

高级参数处理

Toka 目前的 stdx/cli/flag 库提供了基本的选项和标志解析，支持 bool、i64、f64 和 string 等类型。

定位参数（Positional arguments）会被自动捕获，并可以通过已解析参数的 positionals() 方法来获取：

auto pos_args = parsed.positionals()
// pos_args 是一个 Vec<string>，包含所有不匹配任何标志或选项的参数

对于需要嵌套子命令（如 git status 或 docker run）的复杂命令行界面，你可以手动对 pos_args 进行模式匹配，以将执行分发给不同的解析器配置。

HTTP 服务器

使用 Toka 的现代网络库构建一个功能完整的 HTTP 服务器。

基本服务器

Toka 的 HTTP 引擎位于 stdx/net/http 中。你可以通过绑定 std/net 中的 TcpListener 并处理传入连接来构建轻量级 HTTP 服务器：

import std/io::{println}
import stdx/net/http::{HttpRequest, HttpResponse, parse_http_request}
import std/net::{TcpListener, TcpStream, Ipv4Addr, SocketAddrV4}
import core/result::{Result}

fn handle_client(stream#: TcpStream) {
    auto buf: [char; 1024] = [0 as char; 1024]
    auto *buf_ptr# = &buf[0] as *u8
    
    auto read_res = stream#.read(*buf_ptr, 1024:usize)
    match read_res {
        auto Result::Ok(n) => {
            if n > 0:usize {
                auto req_str = string::from_with_len(&buf[0] as *char, n as i32)
                auto req# = parse_http_request(req_str)
                
                auto resp# = HttpResponse::not_found()
                if req.path.eq(string::from("/")) {
                    resp = HttpResponse::html(string::from("<h1>Hello, Toka!</h1>"))
                }
                
                auto resp_str = resp#.to_string()
                auto *ptr = resp_str.c_str() as *u8
                stream#.write(*ptr, resp_str.len() as usize)
            }
        }
        _ => {}
    }
    stream#.close()
}

fn main() -> i32 {
    // 演示服务器设置
    return 0
}

带 JSON 响应的 API

你可以使用 stdx/serde/json 中的 @ToJson trait 自动序列化自定义 shape 对象，并以 JSON 响应返回：

import stdx/net/http::{HttpResponse}
import stdx/serde/json::{serialize_shape, to_json, @ToJson}

pub shape Message(text: string, status: string)

impl Message@ToJson {
    pub fn write_json(self, buf#: string) -> string {
        return serialize_shape(self, buf)
    }
}

fn api_status() -> HttpResponse {
    auto msg = Message(
        text = string::from("服务器正在运行"),
        status = string::from("ok")
    )
    auto json_body = to_json(msg)
    return HttpResponse(
        status_code = 200,
        content_type = string::from("application/json"),
        body = json_body
    )
}

fn main() -> i32 {
    return 0
}

路由参数

你可以轻松地手动匹 URL 路径中的动态部分来提取路由参数：

import stdx/net/http::{HttpRequest, HttpResponse}

fn handle_user_route(req: HttpRequest) -> HttpResponse {
    // 匹配动态路径 "/api/users/<id>"
    if req.path.as_str().starts_with("/api/users/") {
        auto user_id = req.path.substr(11, req.path.len() - 11)
        auto body# = string::from("用户 ID: ")
        body#.push_view(user_id)
        return HttpResponse(
            status_code = 200,
            content_type = string::from("text/plain"),
            body = body
        )
    }
    return HttpResponse::not_found()
}

fn main() -> i32 {
    return 0
}

中间件

包装你的路由处理器以注入自定义中间件功能，例如请求日志或执行计时：

import stdx/net/http::{HttpRequest, HttpResponse}
import std/io::{println}

fn logger_middleware(req: HttpRequest, next: fn(HttpRequest) -> HttpResponse) -> HttpResponse {
    println("请求路径：{}", req.path)
    auto res = next(req)
    println("响应状态码：{}", string::from_int(res.status_code))
    return res
}

fn main() -> i32 {
    return 0
}

静态文件

使用 std/fs 模块动态读取文件来提供本地资源：

import stdx/net/http::{HttpResponse}
import std/fs::{read_to_string}
import core/result::{Result}

fn serve_static_file(path: string) -> HttpResponse {
    auto file_content = read_to_string(path)
    match file_content {
        auto Result::Ok(&content) => {
            return HttpResponse(
                status_code = 200,
                content_type = string::from("text/html"),
                body = content.clone()
            )
        }
        _ => return HttpResponse::not_found()
    }
}

fn main() -> i32 {
    return 0
}

完整示例

一个完整的 HTTP 服务器，包含路由、HTML 渲染和自定义 API JSON 响应：

import std/io::{println}
import stdx/net/http::{HttpRequest, HttpResponse, HttpMethod, parse_http_request}
import std/net::{TcpListener, TcpStream, Ipv4Addr, SocketAddrV4}
import core/result::{Result}

fn route_request(req: HttpRequest) -> HttpResponse {
    auto is_get# = false
    match req.method {
        auto HttpMethod::GET => { is_get = true }
        _ => {}
    }
    
    if is_get && req.path.eq(string::from("/status")) {
        return HttpResponse(
            status_code = 200,
            content_type = string::from("application/json"),
            body = string::from("{\"status\":\"ok\"}")
        )
    }
    
    if is_get && req.path.eq(string::from("/")) {
        return HttpResponse::html(string::from("<h1>Toka HTTP Server</h1>"))
    }
    
    return HttpResponse::not_found()
}

fn handle_connection(stream#: TcpStream) {
    auto buf: [char; 1024] = [0 as char; 1024]
    auto *buf_ptr# = &buf[0] as *u8
    
    auto read_res = stream#.read(*buf_ptr, 1024:usize)
    match read_res {
        auto Result::Ok(n) => {
            if n > 0:usize {
                auto req_str = string::from_with_len(&buf[0] as *char, n as i32)
                auto req# = parse_http_request(req_str)
                auto resp# = route_request(req)
                auto resp_str = resp#.to_string()
                
                auto *ptr = resp_str.c_str() as *u8
                stream#.write(*ptr, resp_str.len() as usize)
            }
        }
        _ => {}
    }
    stream#.close()
}

fn main() -> i32 {
    // 演示服务器设置
    return 0
}

正则引擎

使用 toka-regex 库构建一个正则表达式引擎，它实现了 Thompson NFA（非确定性有限自动机）。

什么是 Thompson NFA？

Thompson NFA 将正则表达式模式编译成一个状态机，可以高效地匹配字符串。它的工作方式如下：

1. 编译 — 将模式转换成一个状态图
2. 模拟 — 同时模拟所有可能的路径
3. 接受 — 如果任意路径到达接受状态，则匹配成功

基本用法

import regex::{Regex}

import std/io::println

fn example() {
    auto re = Regex::new("hello|world")
    
    if re.test(string::from("hello world")) {
        println("找到匹配！")
    }
}

模式语法

该引擎支持标准的正则表达式模式：

匹配

import std/io::println
import core/option::Option

fn example() {
    auto re = Regex::new("\\d+")  // 一个或多个数字
    
    match re.find(string::from("订单 #42")) {
        auto Option::Some(m) => println("找到：{}", m.text),
        auto Option::None => println("未匹配")
    }
}

替换

import std/io::println

fn example() {
    auto re = Regex::new("\\s+")
    auto result = re.replace(string::from("hello    world"), string::from(" "))
    println("{}", result)  // "hello world"
}

引擎架构

正则引擎完全用纯 Toka 构建：

• 模式编译器 — 将正则字符串解析为 NFA 状态
• 状态模拟器 — 对输入文本运行 NFA
• 匹配器 — 处理捕获组和位置追踪

这使得它成为展示 Toka 如何使用清晰、安全的代码实现非平凡算法的一个很好的例子。

附录

为了帮助你全方位地掌握 Toka 语言，本书的附录部分为你准备了丰富的参考资料与实用的开发工具库。

对于带着其他主流语言（如 C++、Rust、Go）背景来到 Toka 的开发者，附录提供了实用的语言转换与平滑迁移指南。

附录参考指南

本附录包含以下三个核心参考模块：

1. Toka 与其他语言对比

• 指南内容：Toka 吸收了多门现代语言的设计灵感，但也引入了独特的创新设计（如解引用的“戴帽与摘帽”与 C++ 恰恰相反）。本章通过清晰的特性对比表格和代码示例，横向对比了 Toka 与 C/C++、Rust、Go 之间的核心语法差异与设计哲学考量，帮助你迅速建立起精准的横向认知。

2. 迁移指南

• 指南内容：如何将现有的逻辑平滑地迁移到 Toka？本章专为经验丰富的工程师编写，重点介绍如何将传统的“面向对象”或“指令式/指针传递”逻辑，改写为符合 Toka Shape 实体解构、帽子重绑定与零拷贝隐式引用捕获 规范的高效系统级代码。

3. 常见问题（FAQ）

• 指南内容：汇总了社区和开发者常见的问题。从新手容易困惑的“为什么不能用大括号定义 Shape”，到深层次的“在方法调用中如何理解指针的重绑定”，本章收集了直观的解答和 Diagnostic 编译错误诊断解读，帮助分析编译问题。

[!NOTE] 终书学习与社区支持 编程语言是一门实践的艺术，而 Toka 正在蓬勃发展中。如果你在日常编码或阅读本书时遇到了任何未尽之言，或者发现了新的错误，我们非常欢迎你向官方仓库提交 Issue 或 Pull Request。希望这本手册能成为你探索底层系统世界的得力助手！

Toka 与其他语言对比

在系统编程领域，Toka 与其他语言相比如何？

Toka vs Rust

Toka vs Go

Toka vs C

Toka vs Zig

迁移指南

从其他语言迁移到 Toka？以下是你需要了解的内容。

从 Rust 迁移

所有权模型：

• Rust：Borrow Checker + 'a 生命周期
• Toka：Hat Principle + ^ 语法——无需生命周期标注

错误处理：

• Rust：Result<T, E> + ? 操作符
• Toka：同样的 Result<T, E> + ! 操作符

模式匹配：

• Rust：match 穷尽性检查
• Toka：同样的 match + 通配符 _

Traits：

• Rust：trait Foo { fn bar(&self); }
• Toka：pub trait Foo { fn bar(self); } + @ 语法

从 Go 迁移

错误处理：

• Go：到处都是 if err != nil
• Toka：Result/Option + ! 操作符——更简洁、更安全

并发模型：

• Go：Goroutines + 通道
• Toka：Tasks + MPSC 通道

接口：

• Go：隐式接口实现
• Toka：显式 trait 实现 + @ 语法

从 C 迁移

指针：

• C：不安全的原始指针 *
• Toka：PAL Checker 追踪的帽子 ^

内存管理：

• C：手动的 malloc/free
• Toka：自动的编译时内存管理

构建系统：

• C：Makefile / CMakeLists.txt
• Toka：package.tk（声明式）

从 Python 迁移

动态 vs 静态：

• Python：动态类型，运行时错误
• Toka：静态类型，编译时安全

性能：

• Python：解释执行，慢
• Toka：编译执行，原生速度（通过 LLVM）

快速语法参考

常见问题

通用问题

问：Toka 可以用于生产环境吗？

Toka 目前处于 beta 阶段（v0.9.8-03）。适用于个人项目、原型开发和实验。1.0 版本的发布计划将以生产稳定性为核心目标。

问：Toka 支持哪些平台？

支持 Linux、macOS 和 Windows。LLVM 后端提供交叉编译能力。

问：有包管理器吗？

Toka 通过 toka add 内置了包管理器。官方库注册中心在 pkg.tokalang.dev。

语言设计

问：Toka 与 Rust 有何不同？

Toka 通过 Hat Principle 实现内存安全，而不是 Borrow Checker。这意味着没有生命周期标注——只需简单的帽子（^）标记，使所有权在语法中可见。

问：Toka 有垃圾回收器吗？

没有。内存通过 PAL Checker 在编译时管理，没有运行时 GC 开销。

问：Toka 与 C 库兼容吗？

是的。Toka 有原生的 C 互操作能力，没有 FFI 开销。你可以直接调用 C 函数。

学习

问：我需要先学 C 或 Rust 才能学 Toka 吗？

完全不需要。Toka 的语法简洁，类似 Go。如果你会任何编程语言，一个周末就能学会 Toka。

问：哪里可以找到更多示例？

可以查看 Toka 仓库中的 examples/ 目录，以及社区库集合 tokalibs。

问：有社区或论坛吗？

欢迎加入 GitHub Discussions 上的 Toka 社区：github.com/tokalang/toka。

技术问题

问：Toka 有多快？

Toka 的编译速度约为每秒 80,000 行代码（Clang 后端），并通过 LLVM 20 生成优化的原生二进制文件。性能与等效的 C 代码相当。

问：Toka 的二进制文件有多大？

一个最小的 HTTP 服务器二进制文件约为 250 KB——无运行时、无虚拟机，只有原生代码。

问：Toka 支持多线程吗？

是的。Toka 为并发编程提供了 tasks、MPSC 通道、原子操作和互斥锁（mutex）。