YKit Language Support
VS Code 扩展，为 YKit 脚本语言（.yk）提供语法高亮、代码片段与悬停文档。
功能特性
- 语法高亮：关键字、字符串（含
$"..." 插值）、数字、注释、运算符、内建函数、方法调用、task 名标识。
- 代码片段：
task / if / loop / retry / let / letref（新表达式形式 let a = ref b;）/ callref（调用点传引用）/ 复合赋值 / 文件 I/O / 数组 / 字典 / noexcept 等常用模板。
- 悬停文档：将鼠标悬停在内建函数、方法、关键字上，查看用法、签名与示例。
YKit 语言概览
YKit 是一个面向自动化流水线的轻量级解释型脚本语言。语法贴近 C/JS，运行时极小。
关键字与控制流
- 声明：
let（含 let alias = ref original; 引用别名）、task（形参一律按值绑定，是否引用由调用点用 ref 决定）
- 控制流：
if / elif / else、while、loop(N [, i])、retry(N [, i]) { ... success; / fail; }、break、continue、success / fail（仅 retry body 内）、return
- 模块：
include "path";（运行到该语句时按当前 basedir 解析并执行另一份 .yk）
- 字面量：整数（
true/false 即 1/0；支持下划线分组 1_000_000、十六进制 0xDEAD_BEEF、二进制 0b1111_0000）、"plain string"、r"raw string"（不解释转义，适合路径与正则）、$"interpolated {var}"、数组 [a, b]、字典 { "k": v }
ref 语义（已更新）
ref 现在只有两种用法，全部以表达式前缀的形式存在：
调用点传引用（最常用）：
task set_to_8848(a, b, c) { a = 8848; }
let k = 123;
set_to_8848(ref k, k, k); // 仅第 1 个实参用 ref，task 内 `a = 8848` 会写回 k
print(k); // 8848
被调用方对形参一视同仁，形参声明里不写 ref——是否按引用完全由调用点决定。
引用别名（表达式形式）：
let alias = ref original; // alias 与 original 共享存储
alias += 1; // 等价于 original += 1
旧版 let ref a = b; 与 task f(ref x) 形参语法已不再支持；请改用上述新写法。
表达式与运算符
- 复合赋值：
+=、-=、*=、/=、%=
- 比较：
==、!=、<、<=、>、>=
- 逻辑：
&&、||、!
- 索引：
a[i]（数组下标 / map key）
文件操作 —— 立即执行
所有文件操作（copy / cut / delete / create / mkdir / write / append / read / exists / listdir）调用即落盘，每一步成功/失败立即可见，符合流水线脚本的执行直觉：
- 没有事务、没有回滚、没有
commit/flush；
- 路径最后一段支持
* 与 ? 通配（如 copy("src/*.dat", "build/")）；
- 失败时携带
path:line: error: ... 退出；可选 on_ok / on_fail 回显字符串。
错误处理
assert(cond, message) —— 断言失败立即退出；error(message) —— 立即报错退出（一参，与文档保持一致）；noexcept(expr) —— 在表达式范围内捕获 runtime 失败，失败返回 0，否则返回表达式值。
内建函数（节选）
- 文件/路径：
copy / cut / delete / create / mkdir / write / append / read / exists / listdir / isfile / isdir / join / basename / dirname / extname / setbasedir / getbasedir
- 字符串/类型：
format / toint / tostr / isnum / isstr / ismap / isarray / isref
- 系统：
system / system_capture / getenv / setenv / input / wait(ms) / exit / now / random_int / uuid / argc / argv
- 数学：
abs / min / max / clamp / gcd / pow / sqrt_int
- OS / 进程探测：
os_name / os_arch / path_sep / line_sep / cwd / chdir / pid / hostname / username
- 日志：
print / log_info / log_warn / log_error
方法调用
- 数组：
push / pop / len / empty / slice / find / remove / sort / reverse / join
- 字符串：
split / trim / replace / contains / starts_with / ends_with
- Map：
keys / values / contains
1.4.0 更新
- 新增 OS / 进程探测内建（9 项），让跨平台脚本无需再调
system_capture("uname") 之类：
os_name() → "windows" / "linux" / "macos" / "freebsd" / "unknown"os_arch() → "x86_64" / "x86" / "arm64" / "arm" / "unknown"path_sep() / line_sep() —— 跨平台路径与行尾符常量cwd() / chdir(dir) —— 进程级当前工作目录（注意区分 getbasedir()：后者是 yk 文件 builtin 解析相对路径的逻辑基准）pid() —— 当前进程 PIDhostname() —— 机器名username() —— 当前用户名
- 同步
tmLanguage builtins 列表、snippets（新增 os_name / os_arch / path_sep / line_sep / cwd / chdir / pid / hostname / username）、hover 文档。
1.3.0 更新
- 整数升级到 64 位：
int_t = long long。now() 不再于 2038 年溢出；arr.len()/arr.find()/slice() 等不再受 2^31 限制；toint() 现支持完整 64bit 范围。
- 数字字面量增强：
- 下划线分组：
100_000_000、0xDEAD_BEEF、0b1111_0000（仅作分隔，不允许首尾或连续下划线）
- 十六进制：
0xFF、0XFF
- 二进制：
0b1010、0B1010
- 原样字符串
r"..."：内部不解释任何转义，适合 Windows 路径 r"C:\Users\Tom\file.txt" 与正则 r"\d+\.\d+"。限制：不能含 " 字符（要含时改用普通字符串）。
- 新增数学内建：
abs / min / max / clamp / gcd / pow / sqrt_int，全部为整数版本，零 <cmath> 依赖以保持轻量化。
min(...) / max(...) 接受变长参数（≥ 1 个）pow(base, exp) exp 必须 ≥ 0，O(log exp) 二分快速幂；溢出按 64bit 自然回卷sqrt_int(x) 牛顿迭代实现，向下取整
- 同步更新
tmLanguage（数字字面量分类、r-string scope）、snippets（新增 rstr/abs/min/max/clamp/gcd/pow/sqrt_int）、hover 文档。
1.2.2 更新
- 项目改名：
YYToolkit → YKit，源码扩展名 .yykt → .yk，语言 id yytoolkit → ykit，TextMate scope source.yytoolkit → source.ykit。
- 同步更新 hover、snippet、tmLanguage 中的 scope 命名与示例文件名。
- 新增
isref(variable)：判断变量自身是否为 ref 绑定（如以 ref x 形式传入的形参）；附带 snippet 与 hover。
- 插值字符串
$"..." 升级：{...} 内允许任意表达式（语义同 format(fmt, ...) 的语法糖）。
1.2.1 更新
ref 语义同步：当前语言只支持 ref 作为表达式前缀——
- 调用点：
f(ref x)（被调用方形参一律按值声明，由调用点决定是否传引用）
- 引用别名（表达式形式）：
let a = ref b;
- 已废弃语法：
let ref a = b;、task f(ref x)（task 形参不再接受 ref 修饰）
- 同步更新
task / let / ref hover 文档与 README 示例。
- snippets：删除
taskref（已不支持）；letref 改为新表达式形式 let a = ref b;；新增 callref 模板。
1.2.0 更新
- 将文件操作描述统一为"立即执行"（删除原"录制 + 退出时统一提交"的事务模型相关表述）。
- 修复
error() snippet：实际签名为 error("message")，单参必填。
- 修复
noexcept snippet：是表达式形式 noexcept(expr)，不是块。
- 修复
wait snippet 的描述与参数名：单位是毫秒。
- 修复
format snippet 中多余的右花括号。
- 新增
ismap / isarray / isfile / isdir 的 snippet 与 hover。
- 完善
retry / include / ref / $"..." 插值字符串等关键特性的 hover 描述。
- README 重写：补全语言概览与内建函数清单。
关于 YKit
YKit 是一个轻量级的解释型脚本语言，专为自动化流水线设计。详见项目主页。
许可
MIT License
| |
