paotin/plugins/lib/storage.tin

#nop vim: set filetype=tt:;

/*
本文件属于 PaoTin++ 的一部分。
PaoTin++ © 2020~2026 的所有版权均由担子炮(dzp <danzipao@gmail.com>) 享有并保留一切法律权利
你可以在遵照 GPLv3 协议的基础之上使用、修改及重新分发本程序。
*/

///=== {
///// storage 模块实现了一个通用的本地存储引擎。
///// 可以用来存储和载入变量，这允许其它模块可以持久化自己的数据。
///// 变量会被存储在本地文件系统当中，称之为「存储文件」。
/////
///// 存储文件按规定会统一存放在 data 目录下，支持文件重定位。也就是说，
///// 对于存储文件 file1 来说，其可能的物理存放位置为：
/////   1. var/data/file1.tin （优先）
/////   2. data/file1.tin     （其次）
/////
///// storage 支持的存储有两大维度：
/////   - 存储形式
/////        - 文件式（Save/Load）: 按文件组织多个变量。
/////        - 键值式（Set/Get）: 把琐碎的数据集中存到同一个文件里，不必单独建文件。
/////   - 作用域
/////        - share: 跨角色共享。
/////        - user: 按角色 ID 隔离，存 data/<角色ID>/ 下。
/////
///// 两大维度正交，组合成四组 API：
/////   - 文件式 share: storage.Save     / storage.Load
/////   - 文件式 user : storage.SaveUser / storage.LoadUser
/////   - 键值式 share: storage.Set      / storage.Get
/////   - 键值式 user : storage.SetUser  / storage.GetUser
/////
///// 各模块可以自行决定变量的存放位置，通常来说，对于较大的变量，建议通过文件式 API，
///// 也就是 storage.Save/SaveUser 来创建自己模块专属的存储文件，并在需要时通过读取
///// API storage.Load/LoadUser 提取这些变量。每个存储文件可以存储一个或多个变量。
/////
///// 而那些较为琐碎的存储项，通常是一些较小的变量，storage 模块自行维护了一组全局收
///// 纳文件（data/storage.tin），各模块可通过键值式 API 来读写它们，更为方便。
/////
///// NOTE: 旧 API storage.SetGlobal/storage.GetGlobal 与 storage.Set/storage.Get 等
///// 价，目前已废弃，但暂时保留以兼容既有代码，请各模块作者尽快更换。
///// };

#var lib_storage[META] {
    {NAME}      {通用存储引擎}
    {DESC}      {可以存储和载入变量，这允许其它模块可以持久化自己的数据}
    {AUTHOR}    {担子炮}
};

VAR {存储路径}              storage-path            {data};
VAR {跨角色共享存储项}      storage-globals         {};
VAR {角色私有存储项}        storage-user-globals    {};

#func {lib_storage.Init} {
    #local _ {@mkdir{data}};

    #local files {};
    #line quiet #scan dir {var/data/} files;
    #if { &files[] > 0 } {
        #var storage-path {var/data};
    };

    storage.Load {storage} {storage-globals};

    #return {true};
};

#nop 内部函数，计算指定作用域的存储文件路径。user 作用域需要已登录的角色 ID。;
#func {storage.path} {
    #local scope    {%1};
    #local file     {%2};

    #replace file {.tin$} {};
    #cat file {.tin};

    #if { "$scope" != "{share|user}" } {
        errLog storage.path 参数错误，scope 只能为 share 或 user。;
        #return {};
    };

    #if { "$scope" == "share" } {
        #return {$storage-path/$file};
    };

    #if { "$user[id]" == "" } {
        errLog 尚未登录角色，无法操作 user 作用域的存储文件。;
        #return {};
    };

    #local _ {@mkdir{$storage-path/$user[id]}};
    #return {$storage-path/$user[id]/$file};
};

#nop 内部命令，将指定变量列表存储到给定的存储文件中。;
#alias {storage.dump} {
    #local vars {%1};
    #local path {%2};

    #class comm-store-tmp open;
    #local var {};
    #foreach {$vars} {var} {
        #local count {&{${var}[]}};
        #if { $count < 100 } {
            #var {dump-$var} {${$var}};
            dbgLog storage 变量 $var 已写入磁盘。共有 @math.Max{$count;1} 个数据项。;
            #continue;
        };

        #local idx {0};
        #loop 1 {$count} {idx} {
            #local key   {*{${var}[+$idx]}};
            #local value {${${var}[+$idx]}};
            #var {dump-${var}[$key]} {$value};
        };

        dbgLog storage 变量 $var 已写入磁盘。共有 $count 个数据项。;
    };
    #class comm-store-tmp close;

    #class comm-store-tmp write {$path};

    #class comm-store-tmp kill;
};

#nop 内部命令，从给定的存储文件中加载变量到指定变量列表中。
#nop 存储文件不存在时静默跳过，不会报错。;
#alias {storage.load} {
    #local path {%1};
    #local vars {%2};

    #if { !@existsFile{$path} } {
        #return;
    };

    #line quiet #class comm-store-tmp {assign} {load-file $path};
    #local var {};
    #foreach {$vars} {var} {
        #local count {&{dump-${var}[]}};
        #if { $count < 100 } {
            #var {$var} {${dump-$var}};
            dbgLog storage 已从磁盘中加载变量 $var，共有 @math.Max{$count;1} 个数据项。;
            #continue;
        };

        #local idx {0};
        #loop 1 {$count} {idx} {
            #local key   {*{dump-${var}[+$idx]}};
            #local value {${dump-${var}[+$idx]}};
            #var {${var}[$key]} {$value};
        };

        dbgLog storage 已从磁盘中加载变量 $var，共有 $count 个数据项。;
    };
    #class comm-store-tmp kill;
};

///=== {
// ## storage.Save <文件名> <变量名1> [...]
//    将由变量名列表所指定的变量及其值存储到指定的存储文件中。
//    存储文件的路径为 share 作用域，所有角色共享同一份数据。
//    例子: storage.Save {foo} {my-var1;my-var2};
//    注意文件名可以省略且建议省略 .tin 后缀。
// };
#alias {storage.Save} {
    #local file {%1};
    #local vars {%2};

    #if { "$file" == "" || "$vars" == "" } {
        xtt.Usage storage.Save;
        #return;
    };

    storage.dump {$vars} {@storage.path{share;$file}};
};

///=== {
// ## storage.Load <文件名> <变量名1> [...]
//    从指定的存储文件中加载变量。
//    存储文件的路径为 share 作用域，所有角色共享同一份数据。
//    存储文件中实际存储的变量可能更多一些，但本函数可以只加载其中一部分变量。
//    例子: storage.Load {foo} {my-var1;my-var2};
//    注意文件名可以省略且建议省略 .tin 后缀。
// };
#alias {storage.Load} {
    #local file {%1};
    #local vars {%2};

    #if { "$file" == "" || "$vars" == "" } {
        xtt.Usage storage.Load;
        #return;
    };

    storage.load {@storage.path{share;$file}} {$vars};
};

///=== {
// ## storage.SaveUser <文件名> <变量名1> [...]
//    将由变量名列表所指定的变量及其值存储到当前角色的私有存储文件中。
//    存储文件的路径为 user 作用域，位于 data/<角色ID>/ 目录下，各角色相互隔离。
//    本命令需要登录完成、获得角色 ID 之后才能使用，否则报错拒绝。
//    例子: storage.SaveUser {foo} {my-var1;my-var2};
//    注意文件名可以省略且建议省略 .tin 后缀。
// };
#alias {storage.SaveUser} {
    #local file {%1};
    #local vars {%2};

    #if { "$file" == "" || "$vars" == "" } {
        xtt.Usage storage.SaveUser;
        #return;
    };

    #if { "$user[id]" == "" } {
        errLog storage 尚未登录角色，无法使用 storage.SaveUser。;
        #return;
    };

    storage.dump {$vars} {@storage.path{user;$file}};
};

///=== {
// ## storage.LoadUser <文件名> <变量名1> [...]
//    从当前角色的私有存储文件中加载变量。
//    存储文件的路径为 user 作用域，位于 data/<角色ID>/ 目录下，各角色相互隔离。
//    本命令需要登录完成、获得角色 ID 之后才能使用，否则报错拒绝。
//    存储文件中实际存储的变量可能更多一些，但本函数可以只加载其中一部分变量。
//    例子: storage.LoadUser {foo} {my-var1;my-var2};
//    注意文件名可以省略且建议省略 .tin 后缀。
// };
#alias {storage.LoadUser} {
    #local file {%1};
    #local vars {%2};

    #if { "$file" == "" || "$vars" == "" } {
        xtt.Usage storage.LoadUser;
        #return;
    };

    #if { "$user[id]" == "" } {
        errLog storage 尚未登录角色，无法使用 storage.LoadUser。;
        #return;
    };

    storage.load {@storage.path{user;$file}} {$vars};
};

///=== {
// ## storage.Set <KEY> [<值>]
//    将值关联到 KEY 上，并存储到全局存储文件中。
//    本命令与 storage.SetUser 相对，读写的是 share 作用域的键值存储。
//    参见 storage.Get
// };
#alias {storage.Set} {
    #local key      {%1};
    #local value    {%2};

    #if { "$key" == "" } {
        xtt.Usage storage.Set;
        #return;
    };

    #var storage-globals[$key] {$value};
    storage.Save {storage} {storage-globals};

    dbgLog storage 全局存储项已写入磁盘。;
};

///=== {
// #@ storage.Get <KEY>
//    从全局存储文件中根据 KEY 提取值。
//    本函数与 storage.GetUser 相对，读写的是 share 作用域的键值存储。
//    参见 storage.Set
// };
#func {storage.Get} {
    #local key  {%1};

    #if { "$key" == "" } {
        xtt.Usage storage.Get;
        #return {};
    };

    #return {$storage-globals[$key]};
};

///=== {
// ## storage.SetGlobal <KEY> [<值>]
//    旧名称，已废弃，等同于 storage.Set，保留以兼容既有代码，请尽快迁移。
// };
#alias {storage.SetGlobal} {
    warnLog 本接口已废弃，请尽快改用 storage.Set;
    storage.Set %0;
};

///=== {
// #@ storage.GetGlobal <KEY>
//    旧名称，已废弃，等同于 storage.Get，保留以兼容既有代码，请尽快迁移。
// };
#func {storage.GetGlobal} {
    #local key {%1};
    warnLog 本接口已废弃，请尽快改用 storage.Get;
    #return @storage.Get{$key};
};

///=== {
// ## storage.SetUser <KEY> [<值>]
//    将值关联到 KEY 上，并存储到当前角色的私有存储文件中。
//    需要登录完成、获得角色 ID 之后才能使用，否则报错拒绝。
//    参见 storage.GetUser
// };
#alias {storage.SetUser} {
    #local key      {%1};
    #local value    {%2};

    #if { "$key" == "" } {
        xtt.Usage storage.SetUser;
        #return;
    };

    #if { "$user[id]" == "" } {
        errLog storage 尚未登录角色，无法使用 storage.SetUser。;
        #return;
    };

    storage.ensure-user;
    #var storage-user-globals[$key] {$value};
    storage.SaveUser {storage-user} {storage-user-globals};
};

///=== {
// #@ storage.GetUser <KEY>
//    从当前角色的私有存储文件中根据 KEY 提取值。
//    需要登录完成、获得角色 ID 之后才能使用，否则报错拒绝。
//    参见 storage.SetUser
// };
#func {storage.GetUser} {
    #local key  {%1};

    #if { "$key" == "" } {
        xtt.Usage storage.SetUser;
        #return {};
    };

    #if { "$user[id]" == "" } {
        errLog storage 尚未登录角色，无法使用 storage.GetUser。;
        #return {};
    };

    storage.ensure-user;
    #return {$storage-user-globals[$key]};
};

VAR {角色私有存储已加载}    storage-user-loaded     {false};

#nop 内部命令，确保角色私有存储项已从磁盘加载。;
#alias {storage.ensure-user} {
    #if { @isTrue{$storage-user-loaded} } {
        #return;
    };

    storage.LoadUser {storage-user} {storage-user-globals};
    #var storage-user-loaded {true};
};