paotin/plugins/lib/option.tin

#nop vim: set filetype=tt:;

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

#var lib_option[META] {
    {NAME}      {全局选项管理}
    {DESC}      {为全局选项提供了一个储存位置，并提供一些实用的 API。}
    {AUTHOR}    {担子炮}
};

VAR {全局选项字典}  gOptions    {};

load-lib storage;

event.Define {option/changed} {无参} {$MODULE} {选项已更新。本事件只会唤醒和选项名称相对应的钩子};

#func {lib_option.Init} {
    #var gOptions {@storage.GetGlobal{global-options}};
    #return {true};
};

///=== {
///// 全局选项管理。
/////
///// 全局选项本质上就是一些变量，这个模块主要是为了提供一些公共 API，和一个统
///// 一的管理方式，能够把散落在各处的选项集中管理。
/////
// ## option.Define <名称> <数据类型> <中文含义> [<默认值>]
//    定义一个全局选项。选项被定义之后有一些公共 API 可供使用。
//    选项必须经过定义之后才能使用。选项的名称按照大骆驼风格命名。
//    目前仅支持 Bool 型选项。
// };
#alias {option.Define} {
    #local option   {%1};
    #local type     {%2};
    #local meaning  {%3};
    #local default  {%4};

    #if { "$option" == "" || "$type" == "" || "$meaning" == "" } {
        xtt.Usage option.Define;
        #return;
    };

    #if { "$gOptions[$option]" != "" } {
        #if {  "$gOptions[$option][name]" != "$option"
            || "$gOptions[$option][type]" != "$type"
            || "$gOptions[$option][meaning]" != "$meaning"
        } {
            errLog 选项「$option」已存在，请检查代码。;
        };
        #return;
    };

    #if { ! @option.isValidValue{$type;{$default}} } {
        #return;
    };

    #var gOptions[$option] {
        {name}      {$option}
        {type}      {$type}
        {meaning}   {$meaning}
        {value}     {$default}
    };

    storage.SetGlobal {global-options} {$gOptions};
};

///=== {
// ## option.List
//    列出所有的选项。
// };
#alias {option.List} {
    #echo {};
    #echo {   <128>%-25s%-10s  %-30s %+22s} {选项名称} {选项类型} {选项含义} {选项当前值};
    #draw Yellow scroll line 1 1 1 100;

    #local option {};
    #foreach {*gOptions[]} {option} {
        #local value {$gOptions[$option][value]};

        #if { "$gOptions[$option][type]" == "Time" } {
            #if { $value > 0 } {
                #format value {%t} {{%Y-%m-%d %H:%M:%S}{$value}};
            };
        };

        #echo {   %-25s %-10s %-30s %+22s}
            {$gOptions[$option][name]}
            {$gOptions[$option][type]}
            {$gOptions[$option][meaning]}
            {{$value}};
    };

    #echo {};
};

///=== {
// #@ option.Get <选项名称>
//    获取选项的当前值。
// };
#func {option.Get} {
    #local {option} {%1};

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

    #if { "$gOptions[$option]" == "" } {
        errLog 不存在选项「$option」，请先定义后再使用。;
        #return {};
    };

    #return {$gOptions[$option][value]};
};

///=== {
// #@ option.Set <选项名称> <选项新值>
//    设置选项的当前值，返回之前的旧值。
// };
#func {option.Set} {
    #local {option} {%1};
    #local {value}  {%2};

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

    #local old {$gOptions[$option]};
    #if { "$old" == "" } {
        errLog 不存在选项「$option」，请先定义后再使用。;
        #return {};
    };

    #if { ! @option.isValidValue{$gOptions[$option][type];{$value}} } {
        #return {};
    };

    #if { "$old[value]" !== "$value" } {
        #var {gOptions[$option][value]} {$value};
        storage.SetGlobal {global-options} {$gOptions};
        event.Emit {option/changed} {opt/$option/%*};
    };

    #return {$old[value]};
};

///=== {
// ## option.Set <选项名称> <选项值>
//    设置选项的当前值。
// };
#alias {option.Set} {
    #local {option} {%1};
    #local {value}  {%2};

    #local _ {@option.Set{$option;{$value}}};
};

///=== {
// ## option.Push <选项名称> <选项值>
//    设置选项的当前值，并将旧值压入栈中。配合 option.Pop 可以实现选项值的回退。
// };
#alias {option.Push} {
    #local {option} {%1};
    #local {value}  {%2};

    #if { "$option" == "" } {
        xtt.Usage option.Push;
        #return {};
    };

    #local old {$gOptions[$option]};
    #if { "$old" == "" } {
        errLog 不存在选项「$option」，请先定义后再使用。;
        #return;
    };

    #if { ! @option.isValidValue{$gOptions[$option][type];{$value}} } {
        #return;
    };

    #var {gOptions[$option][value]} {$value};
    #list gOptions[$option][stack] add {$old[value]};
    storage.SetGlobal {global-options} {$gOptions};
    event.Emit {option/changed} {opt/$option/%*};
};

///=== {
// ## option.Pop <选项名称> <选项值>
//    从选项的历史值中按照后进先出的原则弹出一个值，使之成为当前值。配合 option.Push 可以实现选项值的回退。
// };
#alias {option.Pop} {
    #local {option} {%1};

    #if { "$option" == "" } {
        xtt.Usage option.Pop;
        #return {};
    };

    #local old {$gOptions[$option]};
    #if { "$old" == "" } {
        errLog 不存在选项「$option」，请先定义后再使用。;
        #return;
    };

    #if { &gOptions[$option][stack][] == 0 } {
        #return;
    };

    #var {gOptions[$option][value]} {$old[stack][-1]};
    #list gOptions[$option][stack] delete -1;
    storage.SetGlobal {global-options} {$gOptions};
    event.Emit {option/changed} {opt/$option/%*};
};

///=== {
// #@ option.IsEnable <选项名称>
//    检查选项是否已被开启。
// };
#func {option.IsEnable} {
    #local option {%1};

    #if { "$option" == "" } {
        xtt.Usage option.IsEnable;
        #return {};
    };

    #if { "$gOptions[$option]" == "" } {
        errLog 不存在选项「$option」，请先定义后再使用。;
        #return {};
    };

    #if { "$gOptions[$option][type]" != "Bool" } {
        errLog 只有 Bool 型变量才支持这个 API。;
        #return {};
    };

    #local value {@option.Get{$option}};
    #return @isTrue{$value};
};

///=== {
// #@ option.IsDisable <选项名称>
//    检查选项是否已被禁用。
// };
#func {option.IsDisable} {
    #local option {%1};

    #if { "$option" == "" } {
        xtt.Usage option.IsDisable;
        #return {};
    };

    #if { "$gOptions[$option]" == "" } {
        errLog 不存在选项「$option」，请先定义后再使用。;
        #return {};
    };

    #if { "$gOptions[$option][type]" != "Bool" } {
        errLog 只有 Bool 型变量才支持这个 API。;
        #return {};
    };

    #local value {@option.Get{$option}};
    #return @isFalse{$value};
};

///=== {
// #@ option.Toggle <选项名称>
//    翻转选项的当前值。如果是启用则改为禁用；如果是禁用则改为启用。
//    本函数将返回之前的值。
// };
#func {option.Toggle} {
    #local {option} {%1};

    #if { "$option" == "" } {
        xtt.Usage option.Toggle;
        #return {};
    };

    #if { "$gOptions[$option]" == "" } {
        errLog 不存在选项「$option」，请先定义后再使用。;
        #return {};
    };

    #if { "$gOptions[$option][type]" != "Bool" } {
        errLog 只有 Bool 型变量才支持这个 API。;
        #return {};
    };

    #local value {@option.Get{$option}};
    #if { "$value" == "true" } {
        option.Disable $option;
        infoLog <169>选项「<139>$gOptions[$option][meaning]($option)<169>」 <119>已禁用。<299>;
    };
    #elseif { "$value" == "false" } {
        option.Enable $option;
        infoLog <169>选项「<139>$gOptions[$option][meaning]($option)<169>」 <129>已启用。<299>;
    };

    #return {$value};
};

///=== {
// ## option.Toggle <选项名称>
//    翻转选项的当前值。如果是启用则改为禁用；如果是禁用则改为启用。
// };
#alias {option.Toggle} {
    #local {option} {%1};

    #local _ {@option.Toggle{$option}};
};

///=== {
// ## option.Enable <选项名称>
//    启用该选项。
// };
#alias {option.Enable} {
    #local {option} {%1};

    option.Set $option {true};
};

///=== {
// ## option.Disable <选项名称>
//    禁用该选项。
// };
#alias {option.Disable} {
    #local {option} {%1};

    option.Set $option {false};
};

#func {@option.isValidValue} {
    #local type     {%2};
    #local value    {%3};

    #local types {Bool|String|Slist|Number|Time};
    #if { "$type" != "{$types}" } {
        errLog 不能识别的选项类型: 「$type」，目前仅支持选项类型：{$types};
        #return;
    };

    #if { "$type" == "Bool" && "$value" != "{true|false}" } {
        errLog Bool 型的选项值只能是 true 或者 false。;
        #return 0;
    };
    #else {
        #return 1;
    };
};