fsys.res：资源枚举、加载与保存

import fsys.res;

主要用于枚举、加载和保存 aardio EXE 中的内嵌文件及库资源：enum/loadRes/saveRes。默认类型为字符串 "RES"，枚举内嵌库可指定 "LIB"。

也支持其它 EXE/DLL 的 PE 资源；names/types/languages/list 提供普通数组查询。

使用 fsys.res.menu 探查菜单资源

快速上手

import fsys.res;

// 枚举当前 EXE 的内嵌文件；回调不需要返回值。
var ok,err,code = fsys.res.enum(function(module,resType,resName){
    var data = fsys.res.loadRes(resName,resType,module);
    print(resName,#data);
});
if(!ok) return null,err,code;

// 枚举当前 EXE 的内嵌库。
fsys.res.enum(function(module,resType,resName){
    print(resType,resName);
},"LIB");

通常读取工程内嵌文件可直接使用 string.load("/res/file.txt")，它能同时处理开发期硬盘文件和发布后的内嵌资源。enum 用于需要列出或批量处理资源的情况；默认模块在开发期是 aardio EXE，发布后是自己的 EXE。

函数	返回值
`enum(proc, resType="RES", module)`	对每个名称调用 `proc(module,resType,resName)`；成功返回 `true`
`types(module)`	全部类型的纯数组：数字 ID 或文本类型名
`names(resType="RES", module)`	指定类型下的资源名称纯数组：数字 ID 或文本名称
`languages(resName, resType="RES", module)`	真实存在的 LANGID 数值纯数组，可能包含 `0`
`list(resType, module)`	`{type;name;lang;size}` 项目的纯数组，每个语言版本一项
`loadRes(resName, resType="RES", module, lang)`	二进制字符串，保留所有字节，包括 NUL
`loadMenu(resName, module, lang)`	`{version;helpId;items}` 菜单数据表
`decodeMenu(data)`	不访问文件，直接解码 MENU/MENUEX 字节串

module 可以是路径或 load 返回的有效指针；省略时使用当前 EXE 的 _HINSTANCE。
传路径时自动以 LOAD_LIBRARY_AS_DATAFILE 加载并释放，不执行文件代码；借用的句柄不释放。
查询结果按数值在前、文本在后，各自升序排列；list 再按语言升序排列，适合比较和序列化。
查询不存在的类型、名称或语言集合返回 []。加载失败、参数错误等仍返回 null, err, code，不要用 : [] 隐藏错误。
loadRes 的空资源返回 ""，缺失资源返回 null, err, code。空字符串在 aardio 中为真值。
查询函数返回数组，直接放在 for ... in 中时应加括号；更推荐先接收返回值并检查错误，再遍历。

名称与类型：数字不等于文本

Windows 的数值资源 ID 是 16 位无符号整数，可取 0..65535。数值 7 与文本 "7" 保持区分。原生 API 的 "#7" 数值名称约定仍按 Windows 语义处理。

"MENU"、"ICON" 等字符串不是数字类型的隐式别名，可能是真实的自定义类型名。Windows API 常量不作运行时声明，代码使用 4/*_RT_MENU*/、3/*_RT_ICON*/ 或直接写数值。库中的常量条目仅供编辑器自动完成，将名称替换成数值，不依赖运行时变量。

import fsys.res;
var file = "C:\Windows\System32\notepad.exe";
var ids,err,code = fsys.res.names(4/*_RT_MENU*/,file);
if(!ids) return null,err,code;
for i,id in ids {
    print(id); // number 或 string，没有原生资源指针
}

常用类型值：菜单 4、对话框 5、字符串表 6、快捷键表 9、原始数据 10、图标组 14、版本 16、HTML 23、清单 24。类型库直接使用字符串 "TYPELIB"。

调用原生 API 时，makeIntResource(value) 负责转成原生参数；getName(value) 反向转换。普通查询无需使用它们。getName 将空原生指针解释为资源 ID 0，将低位指针（包含 65535）转成整数，将有效的 UTF-16 名称指针转成 UTF-8。不要给 getName 传任意内存地址。

精确语言选择

import fsys.res;
var file = "C:\path\resources.dll";
var langs,err,code = fsys.res.languages(100,10/*_RT_RCDATA*/,file);
if(!langs) return null,err,code;
for i,lang in langs {
    var bytes,err,code = fsys.res.loadRes(100,10/*_RT_RCDATA*/,file,lang);
    if(bytes===null) return null,err,code;
    print(lang,#bytes);
}

不传 lang：保留 Windows 默认资源语言选择/回退行为。
显式传 lang，包括 0：必须存在这个 LANGID，绝不回退到其它语言。
即使直接调用 FindResourceExW 也可能发生语言回退；库会先核对实际语言列表，避免“请求日语却读到了中性/英语资源”。
不存在的显式语言返回错误码 1815；资源类型或名称本身不存在时保留相应错误码。

LANGID 是整数，不是 "zh-CN" 等字符串。常见值为 0（中性）、1033（英语/美国）、2052（中文/中国）。

enum 回调

调用方式为 enum(proc,resType="RES",module)，回调参数顺序为 module,resType,resName。

import fsys.res;

fsys.res.enum(function(module,resType,resName){
    var data = fsys.res.loadRes(resName,resType,module);
    print(resName,#data);
    // 不返回值即可继续；如果只要第一个资源，明确 return false。
},"RES","C:\path\app.exe");

"RES"、"LIB" 等自定义资源类型和名称为 UTF-8 string；数字资源类型/名称直接为 number。不用转换指针。
回调不需要返回值；只有返回值全等于 false 才停止后续回调，null、0、true 都继续。
与 names 共用一次名称收集和排序，再逐项调用普通 aardio 回调；停止不影响已经完成的名称收集。
正常完成、提前停止或没有匹配资源均返回 true；加载/参数/系统错误返回 null,err,code。
回调期间模块有效，可直接传给 loadRes，不要在回调中释放它。传路径的模块在 enum 返回或回调抛错后释放，不能保存该句柄留作以后使用；传入已有模块时仍由调用者负责释放。

手工加载模块

load(path, flags) 默认标志 2，只映射数据、不执行代码。若显式指定其它标志，则按 LoadLibraryExW 语义执行，特别是 0 可执行 DLL 入口。

只对自己从 load 获得的模块调用 free。free(null) 安全忽略，但它不能识别已释放的非空句柄，不要重复释放或释放 _HINSTANCE。

更新资源

import fsys.res;
var updater,err,code = fsys.res.open("C:\path\copy.dll");
if(!updater) return null,err,code;

var ok,err,code = updater.update(10/*_RT_RCDATA*/,100,'abc\0def',2052);
if(!ok){
    updater.close(true); // 丢弃暂存修改
    return null,err,code;
}
return updater.close(); // 提交

open(path, true) 会在提交时移除全部旧资源，属于显式的破坏性操作；通常省略第二参数。
update(type, name, data, lang=0) 暂存修改；data 可以是字符串或 buffer，数据会按确切字节长度写入。
删除资源必须明确传 null：updater.update(10/*_RT_RCDATA*/,100,null,2052)。
Win32 更新 API 不支持写入零长度数据。空字符串返回错误，不会隐式删除；读取已有的空资源仍受支持。
close(false)（默认）提交；close(true) 丢弃；重复关闭安全忽略，关闭后不能再更新。
原生更新成功返回 true，失败返回 null, err, code。
库不会代替调用者创建备份或实现文件事务。更新前应确保目标是允许修改的副本；不要修改签名系统文件或正在使用的程序，修改资源会使数字签名失效。

当前 EXE 的 aardio 内嵌文件

aardio 内嵌目录使用文本类型 "RES" 和大写虚拟路径名称，因此 names/loadRes 的默认类型为 "RES"。

saveRes(srcDir="/", target="/") 和 saveAppData(resDir="/", target) 用于导出当前程序内嵌资源目录，发布期实现直接使用 names/loadRes。一般读取工程文件无需使用本库，直接 string.load("/res/file.txt") 就能兼容开发期硬盘文件与发布后的 EXE 内嵌资源。

常见错误码

code	含义
2 / 3	文件或路径不存在
6	更新器已关闭/无效句柄
13	损坏或不支持的菜单模板
87	参数类型、范围或 NUL 错误
1812	PE 没有资源数据
1813	资源类型不存在
1814	资源名称不存在
1815	指定语言资源不存在

没有资源的 PE 可能完全没有资源目录，也可能保留空目录；Windows 会相应返回 1812 或 1813，库保留实际错误码。

检查第一个返回值或 ===null 即可，通常不需要 try/catch；不要在释放模块后才取 lasterr()，函数已经返回操作时的错误文本和错误码。

Markdown 格式