NAC_Blockchain/charter-std-zh/docs/中文关键字设计.md

# Charter中文关键字设计文档

## 📖 概述

本文档详细说明了Charter语言中文关键字的设计原则、实现方式和使用规范。

## 🎯 设计原则

### 1. 自然性
- 使用符合中文表达习惯的词汇
- 避免生硬的直译
- 考虑中文语境下的自然表达

### 2. 简洁性
- 优先使用2-3个汉字的词汇
- 避免过长的关键字
- 保持代码的可读性

### 3. 一致性
- 同类关键字使用相似的命名模式
- 保持与英文关键字的语义对应
- 统一的命名风格

### 4. 无歧义性
- 避免多义词
- 确保关键字含义明确
- 与常用词汇区分

## 📚 关键字列表

### 基础关键字

| 中文 | 英文 | 说明 | 使用场景 |
|------|------|------|----------|
| 资产 | asset | 资产类型 | 定义资产合约 |
| 合约 | contract | 智能合约 | 定义合约 |
| 函数 | fn | 函数定义 | 定义函数 |
| 让 | let | 变量声明 | 声明变量 |
| 可变 | mut | 可变变量 | 声明可变变量 |
| 常量 | const | 常量声明 | 声明常量 |

### 控制流关键字

| 中文 | 英文 | 说明 | 使用场景 |
|------|------|------|----------|
| 如果 | if | 条件判断 | 条件分支 |
| 否则 | else | 否则分支 | 条件分支 |
| 对于 | for | 循环 | for循环 |
| 在 | in | 在...中 | for循环中 |
| 循环 | while | while循环 | while循环 |
| 返回 | return | 返回值 | 函数返回 |

### 事件和模块关键字

| 中文 | 英文 | 说明 | 使用场景 |
|------|------|------|----------|
| 触发 | emit | 触发事件 | 触发事件 |
| 模块 | module | 模块声明 | 声明模块 |
| 使用 | import | 导入模块 | 导入模块 |
| 要求 | require | 断言条件 | 条件检查 |

### 可见性关键字

| 中文 | 英文 | 说明 | 使用场景 |
|------|------|------|----------|
| 公开 | public | 公开可见性 | 公开函数/变量 |
| 私有 | private | 私有可见性 | 私有函数/变量 |
| 内部 | internal | 内部可见性 | 内部函数/变量 |

### 布尔值

| 中文 | 英文 | 说明 | 使用场景 |
|------|------|------|----------|
| 真 | true | 布尔真值 | 布尔表达式 |
| 假 | false | 布尔假值 | 布尔表达式 |

## 🔧 实现方式

### 词法分析器实现

在Charter编译器的词法分析器中，使用Logos库实现中文关键字识别：

```rust
#[derive(Logos, Debug, Clone, PartialEq)]
pub enum Token {
    #[token("asset")]
    #[token("资产")]
    Asset,
    
    #[token("contract")]
    #[token("合约")]
    Contract,
    
    // ... 其他关键字
}
```

### 中文标识符支持

支持中文字符作为标识符：

```rust
#[regex(r"[a-zA-Z_\u4e00-\u9fa5][a-zA-Z0-9_\u4e00-\u9fa5]*", |lex| lex.slice().to_string())]
Identifier(String),
```

Unicode范围 `\u4e00-\u9fa5` 覆盖了常用汉字。

## 📝 使用示例

### 示例1: 纯中文合约

```charter
合约 我的代币 {
    私有 名称: 字符串;
    私有 符号: 字符串;
    私有 总量: u256;
    
    构造函数(名称: 字符串, 符号: 字符串, 总量: u256) {
        让 可变 自己 = 自己;
        自己.名称 = 名称;
        自己.符号 = 符号;
        自己.总量 = 总量;
    }
    
    公开 函数 获取名称() -> 字符串 {
        返回 自己.名称;
    }
    
    公开 函数 转账(接收者: 地址, 数量: u256) {
        要求(数量 > 0, "数量必须大于0");
        // 转账逻辑
    }
}
```

### 示例2: 中英文混合

```charter
使用 charter-std-zh/acc/acc20;

合约 MyToken {
    私有 代币: ACC20基础;
    
    构造函数() {
        代币 = ACC20基础::新建("我的代币", "MYT", 18, 1000000);
    }
    
    函数 transfer(to: 地址, amount: u256) {
        如果 amount > 0 {
            代币.转移(to, amount);
        } 否则 {
            要求(假, "数量必须大于0");
        }
    }
}
```

### 示例3: 控制流

```charter
函数 计算总和(数组: [u256]) -> u256 {
    让 可变 总和 = 0;
    
    对于 数字 在 数组 {
        总和 = 总和 + 数字;
    }
    
    返回 总和;
}

函数 查找最大值(数组: [u256]) -> u256 {
    让 可变 最大 = 0;
    让 可变 索引 = 0;
    
    循环 索引 < 数组.长度() {
        如果 数组[索引] > 最大 {
            最大 = 数组[索引];
        }
        索引 = 索引 + 1;
    }
    
    返回 最大;
}
```

## 🎨 命名规范

### 变量命名
- 使用有意义的中文名称
- 避免单字变量名（除了循环变量）
- 使用驼峰命名或下划线分隔

```charter
// 推荐
让 用户余额 = 1000;
让 最大供应量 = 1000000;

// 不推荐
让 a = 1000;
让 x = 1000000;
```

### 函数命名
- 使用动词开头
- 清晰表达函数功能
- 保持简洁

```charter
// 推荐
函数 获取余额() -> u256
函数 转移代币(接收者: 地址, 数量: u256)
函数 检查权限(用户: 地址) -> 布尔

// 不推荐
函数 余额() -> u256
函数 转移() 
函数 检查()
```

### 合约命名
- 使用名词
- 清晰表达合约用途
- 可以使用中英文混合

```charter
// 推荐
合约 用户管理
合约 代币合约
合约 NFT市场

// 不推荐
合约 管理
合约 合约
合约 市场
```

## ⚠️ 注意事项

### 1. 编码问题
- 确保源文件使用UTF-8编码
- 避免使用BOM
- 注意不同操作系统的换行符

### 2. 兼容性
- 中文关键字与英文关键字完全等价
- 可以在同一文件中混用
- 编译器会统一处理

### 3. 性能
- 中文关键字不影响编译性能
- 生成的字节码完全相同
- 运行时性能无差异

### 4. 工具支持
- IDE需要支持UTF-8
- 语法高亮需要配置
- 代码补全需要更新词库

## 🔮 未来计划

### 短期计划
- [ ] 添加更多中文关键字
- [ ] 完善中文错误消息
- [ ] 提供中文API文档

### 长期计划
- [ ] 支持繁体中文
- [ ] 支持其他语言（日语、韩语等）
- [ ] 多语言IDE插件

## 📚 参考资料

- [Charter语言规范](https://docs.newassetchain.io/charter)
- [Logos词法分析器](https://github.com/maciejhirsz/logos)
- [Unicode汉字范围](https://www.unicode.org/charts/PDF/U4E00.pdf)

## 🤝 贡献

欢迎提出改进建议！如果您有更好的中文关键字翻译方案，请提交Issue或Pull Request。

---

**版本**: 1.0.0  
**最后更新**: 2026-02-18  
**作者**: NAC开发团队