paotin/plugins/lib/storage.tin

#nop vim: set filetype=tt:;

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

///=== {
///// storage 模块实现了一个通用的本地存储引擎。
///// 可以用来存储和载入变量，这允许其它模块可以持久化自己的数据。
///// 变量会被存储在本地文件系统当中，称之为「存储文件」。
/////
///// 存储文件按规定会统一存放在 data 目录下，支持文件重定位。也就是说，
///// 对于存储文件 file1 来说，其可能的物理存放位置为：
/////   1. var/data/file1.tin （优先）
/////   2. data/file1.tin     （其次）
/////
///// 各模块可以通过 API storage.Save 按需创建自己的存储文件，在其中存储一个或多个
///// 变量，并在需要时通过 API storage.Load 提取这些变量。
/////
///// 另外，storage 模块自行维护了一个全局存储文件。在简单使用场景下，其它模块
///// 可以通过 API storage.SetGlobal 和 storage.GetGlobal 来读写这个全局存储文件。
///// 这对读写少量的数据显得更加方便。
///// };

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

VAR {存储路径} storage-path {data};

#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};

    dbgLog storage 全局存储项已加载。;

    #return {true};
};

///=== {
// ## storage.Save <文件名> <变量名1> [...]
//    将由变量名列表所指定的变量及其值存储到指定的存储文件中。
// };
#alias {storage.Save} {
    #local file {%1};
    #local vars {%2};

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

    #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 {$storage-path/${file}.tin};

    #class comm-store-tmp kill;
};

///=== {
// ## storage.Load <文件名> <变量名1> [...]
//    从指定的存储文件中加载变量。
//    存储文件中实际存储的变量可能更多一些，但本函数可以只加载其中一部分变量。
// };
#alias {storage.Load} {
    #local file {%1};
    #local vars {%2};

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

    #line quiet #class comm-store-tmp {assign} {load-file data/${file}.tin};
    #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.SetGlobal <KEY> [<值>]
//    将值关联到 KEY 上，并存储到全局存储文件中。
//    参见 storage.GetGlobal
// };
#alias {storage.SetGlobal} {
    #local key      {%1};
    #local value    {%2};

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

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

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

///=== {
// #@ storage.GetGlobal <KEY>
//    从全局存储文件中根据 KEY 提取值。
//    参见 storage.SetGlobal
// };
#func {storage.GetGlobal} {
    #local key  {%1};

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

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