6.2 KiB

Raw Blame History

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库实现中文关键字识别：

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

中文标识符支持

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

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

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

📝 使用示例

示例1: 纯中文合约

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

示例2: 中英文混合

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

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

示例3: 控制流

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

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

🎨 命名规范

变量命名

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

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

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

函数命名

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

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

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

合约命名

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

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

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

⚠️ 注意事项

1. 编码问题

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

2. 兼容性

中文关键字与英文关键字完全等价
可以在同一文件中混用
编译器会统一处理

3. 性能

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

4. 工具支持

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

🔮 未来计划

短期计划

添加更多中文关键字
完善中文错误消息
提供中文API文档

长期计划

支持繁体中文
支持其他语言（日语、韩语等）
多语言IDE插件

📚 参考资料

🤝 贡献

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

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

6.2 KiB Raw Blame History Unescape Escape