paotin/plugins/lib/event.tin

#nop vim: set filetype=tt:;

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

///=== {
///// event 模块实现了一个事件驱动编程框架，
///// 提供基本的事件驱动编程 API，允许用户定义、发射、订阅事件。
///// };

#var lib_event[META] {
    {NAME}      {事件驱动编程框架}
    {DESC}      {提供基本的事件驱动编程 API，允许用户定义、发射、订阅事件}
    {AUTHOR}    {担子炮}
    {NOTE}      {本文件属于 PaoTin++ 的一部分}
};

#func {lib_event.Init} {
    #class data/lib/event open;
    #var gEventHandlers {};
    #var gValidEvent    {};
    #class data/lib/event close;

    #return true;
};

#func {__xtt_event_name_is_valid__} {
    #local name {%1};
    #if { "$name" == "{[_a-zA-Z]([./_a-zA-Z0-9-]*[a-zA-Z0-9])?}" } {
        #return {true};
    };

    #return {false};
};

///=== {
// ## event.Define <名称> <类型> <模块> <说明>
//    定义事件。事件在使用前必须先定义。事件经过定义后，可以用 event.List 查看。
//    参数列表：
//        - 名称：标识事件的唯一名称，只能以拉丁字母或下划线开头，后面跟若干个
//                字母、数字、下划线（_）、斜线（/）、小数点(.) 组成。其中三个
//                标点符号不能出现在末尾，只能出现在中间。
//        - 类型：枚举值，{有参} 或者 {无参} 二选一。
//                如果事件被定义为有参，则允许发射事件时携带参数，事件驱动会将
//                参数传递给事件处理句柄。
//        - 模块：标识事件所属模块，一般来说事件发射方为事件所属模块。
//                这里要用标准的 PaoTin++ 模块描述符。
//        - 说明：事件的简短说明。会出现在类似于 event.List 的用户交互界面。
// };
#alias {event.Define} {
    #local name     {%1};
    #local type     {%2};
    #local module   {%3};
    #local desc     {%4};

    #if { "@__xtt_event_name_is_valid__{{$name}}" != "true" } {
        xtt.Usage event.Define 事件名称不是合法的标识符名称;
        #return;
    };

    #if { "$type" == "" } {
        #local type {无参};
    };

    #if { "$type" != "{有参|无参}" } {
        xtt.Usage event.Define 事件类型参数值不正确;
        #return;
    };

    #var {gValidEvent[$name]} {
        {type}{$type}
        {module}{$module}
        {desc}{$desc}
    };
};

///=== {
// ## event.List
//    列出所有已定义的事件，以及目前已注册在这些事件上面的钩子。
// };
#alias {event.List} {
    #local event {};

    #if { &gValidEvent[] <= 0 } {
        infoLog 尚未定义任何事件。;
        #return;
    };

    #echo {%h} { 已经定义的事件列表 };

    #echo {%-20s %-5s %-30s %s} {事件/已注册的钩子} {类型} {模块} {说明/代码};
    #echo {%-20s %-5s %-30s %s} {@str.Repeat{20;-}} {----} {@str.Repeat{30;-}} {------------};

    #foreach {*gValidEvent[]} {event} {
        #local type {有参};
        #if { "$gValidEvent[$event][type]" == "{无参|}" } {
            #local type {无参};
        };

        #echo {%-20s %-5s %-30s %s}{$event} {$type}
            {@genModuleLink{$gValidEvent[$event][module];MOD}}
            {$gValidEvent[$event][desc]};
        #local hook {};
        #local count {0};
        #foreach {*gEventHandlers[$event][]} {hook} {
            #local len {1};
            #format len {%L} {$hook};
            #math len {16 - $len};
            #math count {$count + 1};
            #local lead {├};
            #if { $count == &gEventHandlers[$event][] } {
                #local lead {╰};
            };
            #echo { $lead@str.Repeat{$len;─} %s        %-30s %s}{$hook}
                {@genModuleLink{$gEventHandlers[$event][$hook][module];MOD}}
                {$gEventHandlers[$event][$hook][code]};
        };
    };

    #echo {%h};
};

///=== {
// ## event.Emit <事件名称> [<回调钩子通配符>] [<事件参数>]
//    发射事件。这将导致与回调钩子通配符相匹配的回调钩子被立即执行。
//    默认会触发所有注册在本事件下的事件回调钩子。
//    你可以参考 event.Handle 理解什么是事件回调钩子。
// };
#alias {event.Emit} {
    #local name  {%1};
    #local pHook {%2};
    #local args  {%3};

    #if { "@__xtt_event_name_is_valid__{{$name}}" != "true" } {
        xtt.Usage event.Emit 事件名称不是合法的标识符名称;
        #return;
    };

    #if { "$gValidEvent[$name]" == "" } {
        xtt.Usage event.Emit {未定义的事件名称: $name};
        #return;
    };

    #if { &gEventHandlers[$name][] <= 0 } {
        dbgLog event => 事件「$name」已产生，但因为没有注册接受者所以无法投递。;
        #return;
    };

    #local delivered {false};
    #local hook {};
    #foreach {*gEventHandlers[$name][]} {hook} {
        #local options  {$gEventHandlers[$name][$hook][options]};
        #local code     {$gEventHandlers[$name][$hook][code]};
        #nop 如果发射事件时指定了 pHook，则只唤醒指定的 hook，注意这里的 pHook 支持通配符;
        #if { "$pHook" != "" && "$hook" != "$pHook" } {
            #continue;
        };

        #local delivered {true};
        dbgLog event => 事件「$name」即将投递给「$gEventHandlers[$name][$hook][module]」模块的「$hook」。;

        #if { "$options[justOnce]" == "true" } {
            #unvar {gEventHandlers[$name][$hook]};
        };
        #if { "$args" == "" || "$gValidEvent[$name][type]" == "无参" } {
            $code;
        };
        #else {
            $code {$args};
        };
    };

    #if { @isFalse{$delivered} } {
        dbgLog event => 事件「$name」已产生，但因为没有匹配的接受者所以无法投递。;
    };
};

///=== {
// ## event.DelayEmit <事件名称> [<回调钩子通配符>] [<事件参数>]
//    延迟发射事件。类似于 event.Emit，但是会在当前触发执行完毕之后再发射事件。
// };
#alias {event.DelayEmit} {
    #if { "@__xtt_event_name_is_valid__{%1}" != "true" } {
        xtt.Usage event.DelayEmit;
        #return;
    };

    #delay 0 {event.Emit %0};
};

///=== {
// ## event.Handle <事件名称> <回调钩子> <所属模块> <回调代码>
//    注册事件回调钩子。参数说明如下：
//        - 事件名称: 本钩子要关联的事件的名称，需要事先用 event.Define 声明。
//        - 回调钩子: 本次注册的钩子，可以在随后用来取消本钩子，或者当事件发射时，
//                    发射方可以用正则表达式指定要触发哪些钩子。
//        - 所属模块: 注册钩子所在的代码模块。必须是一个严格的 PaoTin++ 模块描述符。
//        - 回调代码: 用来指明钩子被回调时要执行的代码。
// };
#alias {event.Handle} {
    #local name     {%1};
    #local hook     {%2};
    #local module   {%3};
    #local code     {%4};

    #if { "$name" == "" || "$hook" == "" || "$module" == "" || {$code} == {} } {
        xtt.Usage event.Handle;
        #return;
    };

    #if { "@__xtt_event_name_is_valid__{{$name}}" != "true" } {
        xtt.Usage event.Handle 事件名称不是合法的标识符名称;
        #return;
    };

    #var {gEventHandlers[$name][$hook]} {
        {module}{$module}
        {code}{$code}
    };
};

///=== {
// ## event.HandleOnce <事件名称> <回调钩子> <所属模块> <回调代码>
//    注册事件回调钩子，但是本钩子只会被执行一次，然后会自动注销。
//    参数说明如下：
//        - 事件名称: 本钩子要关联的事件的名称，需要事先用 event.Define 声明。
//        - 回调钩子: 本次注册的钩子，可以在随后用来取消本钩子，或者当事件发射时，
//                    发射方可以用正则表达式指定要触发哪些钩子。
//        - 所属模块: 注册钩子所在的代码模块。必须是一个严格的 PaoTin++ 模块描述符。
//        - 回调代码: 用来指明钩子被回调时要执行的代码。
// };
#alias {event.HandleOnce} {
    #local name     {%1};
    #local hook     {%2};
    #local module   {%3};
    #local code     {%4};

    #if { "$name" == "" || "$hook" == "" || "$module" == "" || {$code} == {} } {
        xtt.Usage event.HandleOnce;
        #return;
    };

    #if { "@__xtt_event_name_is_valid__{{$name}}" != "true" } {
        xtt.Usage event.HandleOnce 事件名称不是合法的标识符名称;
        #return;
    };

    #var {gEventHandlers[$name][$hook]} {
        {options}{{justOnce}{true}}
        {module}{$module}
        {code}{$code}
    };
};

///=== {
// ## event.UnHandle <事件名称> <事件回调钩子名称>
//    注销已注册的事件回调钩子。
// };
#alias {event.UnHandle} {
    #local name {%1};
    #local hook {%2};

    #if { "$name" == "" || "$hook" == "" } {
        xtt.Usage event.UnHandle;
        #return;
    };

    #if { "@__xtt_event_name_is_valid__{{$name}}" != "true" } {
        xtt.Usage event.UnHandle 事件名称不是合法的标识符名称;
        #return;
    };

    #unvar {gEventHandlers[$name][$hook]};
};