|-- Environments
    |-- Frame 类：实现词法作用域的环境框架
    |-- SchemeError 异常类：处理 Scheme 程序错误
|-- Procedures/  
    |-- Procedure 基类
        |-- BuiltinProcedure：Python实现的Scheme内建过程
        |-- LambdaProcedure：Lambda表达式生成的过程（静态作用域）
        |-- MuProcedure：Mu表达式生成的过程（动态作用域）

class Frame:  # 构成作用域链的核心数据结构
    def __init__(self, parent):
        self.bindings = {}   # 存储符号-值的映射关系
        self.parent = parent # 指向父级环境帧的指针

def define(self, symbol, value):
    # 特殊处理字符串值引用其他符号的情况
    if isinstance(value, str) and value in self.bindings:
        value = self.bindings[value]  # 实现符号别名机制
    self.bindings[symbol] = value     # 执行实际绑定

def lookup(self, symbol):    # 实现作用域链逐级查找
    if 当前帧存在符号: return binding → 直接返回
    elif parent存在:         → 递归查找父级环境
    else: raise SchemeError → 抛出未定义符号异常

def make_child_frame(self, formals, vals):
    1. 检查形参(formals)和实参(vals)数量是否一致
    2. 创建以当前帧为parent的新子帧
    3. 逐个绑定量形参（通过链表遍历实现）

# 创建全局帧
global_frame = Frame(parent=None)
global_frame.define('PI', 3.14159)

# 创建lambda过程
lambda_proc = LambdaProcedure(
    formals=Pair('x', nil),
    body=Pair('(* x x)', nil),
    env=global_frame)

# 创建子帧调用过程
child_frame = global_frame.make_child_frame(
    formals=Pair('x', nil),
    vals=Pair(5, nil))
result = lambda_proc.body.eval(child_frame)  # 返回25

|-- Eval/Apply 核心模块
    ├── scheme_eval: 表达式求值器
    ├── scheme_apply: 过程执行器
    ├── eval_all: 表达式序列求值
    └── 辅助组件
        ├── Unevaluated 包装类
        └── complete_apply: 完整求值包装器

def scheme_eval(expr, env, _=None): 
    if 表达式为符号 → 环境查找(env.lookup)
    elif 自求值类型 → 直接返回值(数字/字符串等)
    else:
        if 非法列表 → 抛出异常
        分解为: first(操作符), rest(操作数列表)
      
        if 是特殊形式(if/define等): 
            → 调用对应的特殊处理函数
        else:
            递归求值操作符 → 获得过程对象
            递归求值所有操作数 → 获得参数列表
            → 调用 scheme_apply 执行过程

def scheme_apply(procedure, args, env):
    验证过程类型后:
    ├── BuiltinProcedure: 解包参数并调用Python实现
        ├── args转换为Python列表
        └── 按需附加环境参数
    ├── LambdaProcedure: 
        ├── 创建以定义环境为父级的新帧
        └── 在新环境中执行过程体
    └── MuProcedure: 
        ├── 以当前环境为父级创建新帧
        └── 执行动态作用域求值

def eval_all(expressions, env):
    执行步骤:
    1. 将表达式链表转换为求值后链表 (map递归求值)
    2. 遍历到最后一个元素返回其值
    3. 空表达式返回None

    典型应用场景:
    - 代码块执行 (如lambda体/beging块)
    - 文件加载时的多表达式求值

class Unevaluated:  # 保存未求值表达式和对应环境
    def __init__(self, expr, env): ...

def complete_apply:  # 确保最终结果被完全求值
    在 scheme_apply 后执行二次求值验证
    应用场景: 处理 quasiquote 等需要延迟求值的特性

# 测试表达式: (+ (* 3 2) 5)
1. scheme_eval解析为 Pair('+', Pair(Pair('*', ...), ...))
2. 递归求值 "+" 符号 → 获取内置加法过程
3. 递归处理操作数列表:
   - 求值 (* 3 2) → 6
   - 求值 5 → 5
4. 调用 scheme_apply(加法过程, [6,5], 当前环境)
5. 返回 11

| 错误类型                | 触发条件                   | 典型错误信息                     |
|------------------------|--------------------------|-------------------------------|
| SchemeError            | 未定义符号访问            | unknown identifier: {symbol} |
| 参数数量不匹配          | make_child_frame 时检查  | Incorrect number of arguments|
| 无效过程调用            | validate_procedure 验证  | ... is not callable           |
| 类型错误                | 操作符应用时              | operand 0 ...                 |

|-- Special Forms 处理中心
    ├── 变量定义：do_define_form
    ├── 引用机制：do_quote_form
    ├── 代码块：do_begin_form
    ├── 过程构建：do_lambda_form
    ├── 条件控制：do_if_form
    ├── 逻辑运算：do_and_form/do_or_form
    ├── 分支选择：do_cond_form
    ├── 局部作用域：do_let_form
    ├── 准引用：do_quasiquote_form
    └── 动态作用域：do_mu_form

def do_define_form(expressions, env):
    """双模式定义处理器：
    - 值绑定: (define x (+ 1 2))
    - 过程定义: (define (f x) (+ x 1)) """
  
    验证流程：
    validate_form(expressions, 2) → 确保至少两个参数
  
    分发逻辑：
    (参数结构判断):
    └── symbol类型 → 变量绑定 (env.define)
    └── Pair类型 → 生成Lambda过程并绑定

def do_lambda_form(expressions, env):
    """构造闭包的关键处理器"""
    实现步骤：
    1. validate_form检查长度≥2 → (形参 过程体...) 
    2. validate_formals验证形参合法性 → 排除重复/非符号参数
    3. 返回LambdaProcedure对象 → 捕获当前环境

def do_if_form(expressions, env):
    """三元条件处理器："""
    处理逻辑：
    if条件为ture → 执行then分支
    elif存在else → 执行else分支
    else → 返回None (Scheme的undefined)

# 示例：do_and_form逻辑流程
表达式序列 → 逐个求值 → 遇到False → 提前终止返回

def do_let_form(expressions, env): 
    """通过环境帧层级实现局部变量"""
    关键步骤：
    1. make_let_frame创建子环境 → env.make_child_frame
    2. 在新环境中执行表达式序列 → eval_all
  
    绑定列表处理：
    names收集符号 → vals求值结果列表 → 逆向压栈匹配

def do_quasiquote_form(expressions, env):
    """递归展开的模板语法处理器"""
    核心逻辑：
    - 维护展开层级计数器 → level参数
    - 深层遍历表达式树 → map递归处理
    - unquote触发动态求值 → scheme_eval

def do_mu_form(expressions, env):
    """生成动态作用域过程的关键函数"""
    与Lambda区别：
    - 不捕获当前环境 → 执行时再绑定
    返回值：
    MuProcedure对象 → 保存参数列表和过程体

# lambda表达式处理流程
表达式：(lambda (x y) (+ x y))
处理步骤：
1. 解析形参列表 (x y)
2. 生成LambdaProcedure对象
3. 当被调用时创建新帧 → 参数绑定 → 执行过程体

# cond条件分支示例
表达式：(cond ((> x 0) 1) (else -1))
求值步骤：
1. 遍历各分支 → 测试第一个表达式
2. 找到为真的分支 → 执行后续表达式
3. 返回最后表达式结果

| 错误类型                | 触发方法               | 典型场景                  |
|------------------------|-----------------------|--------------------------|
| SchemeError('non-symbol') | do_define_form检测    | 定义非法符号              |
| 参数数量异常            | validate_form控制      | (if) → 缺少分支           |
| duplicate formal        | validate_formals       | (lambda (x x) ...)       |
| unbalance unquote       | quasiquote_item检测    | 嵌套层级错误               |

|-- 核心子系统
    ├── REPL 循环引擎: read_eval_print_loop
    ├── 环境初始化: create_global_frame
    ├── 内置过程注入: add_builtins
    └── 命令行接口: run主函数

|-- 扩展支持
    ├── Turtle图形模块配置
    └── 文件加载机制

def read_eval_print_loop(...):
    """Scheme 的交互式解释循环"""
    关键流程：
    while True:
        1. 获取输入源 → src = next_line()
        2. 逐行解析 → scheme_read
        3. 表达式求值 → scheme_eval
        4. 结果输出 → repl_str 转换打印
      
    异常处理机制：
    | 异常类型                  | 处理方式                     |
    |--------------------------|-----------------------------|
    | SchemeError/SyntaxError   | 打印友好错误信息            |
    | KeyboardInterrupt         | 中断当前输入循环            |
    | EOFError                  | 安全退出解释器              |
    | 递归深度异常              | 特殊提示栈溢信息            |

def create_global_frame():
    """构建初始化环境框架"""
    定义核心构建元素：
    - 'eval': 元求值过程 (BuiltinProcedure 包装)
    - 'apply': 完整应用过程
    - 'undefined' 占位符
    - 导入 BUILTINS 内置函数库

    关键方法：
    add_builtins: 批量注册 Python 实现为 Scheme 内置过程

@main
def run(*argv):
    支持参数：
    --pillow-turtle   启用高性能绘图模式
    --turtle-save-path 设定图像保存路径
    -load             以交互模式加载文件
    file              直接执行 Scheme 文件

    运行模式切换：根据参数选择 buffer_input 或 buffer_lines

# 示例：define内置实现
add_builtins(env, [
    ('define', do_define_form, 'define', False),
    ...
])

异常分级处理策略：
- 原生Python错误转换 → 封装为SchemeError
- 递归错误特殊处理 → 识别解释器栈溢出
- 开发/生产模式切换 → report_errors参数控制堆栈打印

通过注入全局变量配置:
builtins.TK_TURTLE = False  # 使用Pillow替代Tkinter
TURTLE_SAVE_PATH = path     # 设定绘图输出路径

def scheme_load(filename, ...): 
    实现机制：
    1. 打开文件创建新输入源
    2. 修改输入处理器为文件读取模式
    3. 触发REPL循环但不输出结果

# 命令行启动示例：scheme --load init.scm
流程分解：
1. 解析参数识别--load标志
2. 创建初始全局环境
3. 将init.scm加入load_files列表
4. REPL启动时自动执行文件内容
5. 进入交互式循环

环境访问快捷方式：
>>> env = create_global_frame()
>>> env.lookup('eval')  # 查看元求值过程实现
<BuiltinProcedure apply>




# Scheme解释器项目总结

## 整体架构概览
```python
|-- 数据流动全景图
    用户输入 → REPL循环 → 语法分析 → 求值引擎 → 环境操作 → 输出结果
           ↑          ↓               ↑          ↓
       异常处理 ← 特殊形式调度 ← 内置过程调用 ← 绑定管理

# 典型求值流程示例
scheme_eval → 判断特殊形式 → 调用do_xxx_form → 修改环境或控制流
                   ↓
               普通过程 → scheme_apply → 执行过程体

# 新增特殊形式的扩展方式
1. 实现do_xxx_form处理函数
2. 注册到SPECIAL_FORMS字典
3. 自动集成到求值流程中

- JIT编译优化: 将Scheme代码转为字节码
- 持久化环境: 支持环境序列化/反序列化
- 并行计算: 实现fork-join模型

1. 包管理器: 实现模块依赖解析
2. 标准库扩建: 网络/文件IO支持
3. 调试工具链: Stack trace可视化

通过本项目的实现：
✓ 深入理解eval/apply核心循环
✓ 掌握环境模型的实现精髓
✓ 实践编程语言设计的关键问题
✓ 培养大型系统抽象设计能力
✓ 建立Lisp系语言核心认知范式