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 现在只有两种用法，全部以表达式前缀的形式存在：

1. 调用点传引用（最常用）：

   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——是否按引用完全由调用点决定。

2. 引用别名（表达式形式）：

   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() —— 当前进程 PID
  • hostname() —— 机器名
  • 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