Skryptowanie -- dokumentacja API

Kompletna dokumentacja obiektu api przekazywanego do funkcji setup każdego skryptu.

function setup(api)
    -- api.on, api.irc, api.log, etc.
end

Zdarzenia

api.on(event, handler, priority?)

Rejestruje handler zdarzenia. Zwraca identyfikator handlera do późniejszego usunięcia.

local id = api.on("irc.privmsg", function(event)
    -- handle message
end)

Parametry:

Handlery są uruchamiane w kolejności malejącego priorytetu. Zwróć true z handlera, aby wyciszyć zdarzenie (zapobiec uruchomieniu handlerów o niższym priorytecie i wbudowanej obsługi).

Stałe priorytetu:

api.on("irc.privmsg", function(event)
    -- this handler runs before normal-priority handlers
end, api.PRIORITY_HIGH)

api.once(event, handler, priority?)

Działa tak samo jak api.on(), ale handler uruchamia się tylko raz, a następnie usuwa się automatycznie.

api.off(id)

Usuń wcześniej zarejestrowany handler po jego identyfikatorze.

local id = api.on("irc.privmsg", handler)
api.off(id)  -- remove the handler

Zdarzenia IRC

Te zdarzenia są wyzwalane, gdy serwer IRC wysyła dane.

irc.privmsg

Wiadomość kanałowa lub prywatna.

api.on("irc.privmsg", function(event)
    -- event.connection_id  (string)
    -- event.nick           (string)
    -- event.ident          (string)
    -- event.hostname       (string)
    -- event.target         (string) channel or your nick
    -- event.channel        (string) same as target
    -- event.message        (string)
    -- event.is_channel     (string) "true" or "false"
end)

irc.action

Akcja CTCP ACTION (wiadomość /me). Te same pola co irc.privmsg.

irc.notice

irc.join

irc.part

Takie same pola jak irc.join plus message (powód wyjścia).

irc.quit

irc.kick

irc.nick

irc.topic

irc.mode

irc.invite

irc.ctcp_request / irc.ctcp_response

irc.wallops

irc.typing

Zmienił się status pisania jakiejś osoby (client tag +typing z IRCv3 w TAGMSG).

api.on("irc.typing", function(event)
    if event.state == "active" then
        api.ui.print(event.nick .. " is typing in " .. event.target)
    end
end)

To zdarzenie jest wyzwalane niezależnie od ustawienia typing.show -- ta flaga to jedynie preferencja wyświetlania, a skrypt reagujący na pisanie (automatyczna odpowiedź o nieobecności, logger) nie ma powodu przestać działać tylko dlatego, że element paska stanu jest ukryty. Zdarzenie nie jest wyzwalane dla Twojego własnego, odbitego echem statusu pisania ani dla odtwarzanych paczek historii.

Zwróć true, aby wyciszyć: tracker nie zostanie w ogóle zaktualizowany, więc zachowa się tak, jakby TAGMSG nigdy nie dotarł.

irc.ison

Odpowiedź serwera RPL_ISON (303) z listą odpytanych nicków, które są aktualnie online. Zwróć true, aby wyciszyć domyślną linię w buforze statusu.

Zdarzenia DCC

Te zdarzenia są wyzwalane dla aktywności DCC CHAT. Połączenia DCC to bezpośrednie połączenia TCP peer-to-peer, które omijają serwer IRC.

dcc.chat.request

Wyzwalane, gdy zdalny użytkownik wysyła żądanie DCC CHAT. Zwróć true, aby wyciszyć (automatycznie odrzucić).

api.on("dcc.chat.request", function(event)
    -- event.connection_id  (string) IRC connection the offer arrived on
    -- event.nick           (string) offering nick
    -- event.ip             (string) IP address to connect to
    -- event.port           (number) TCP port
    api.ui.print("DCC CHAT offer from " .. event.nick .. " (" .. event.ip .. ":" .. event.port .. ")")
end)

dcc.chat.connected

Wyzwalane, gdy połączenie TCP DCC CHAT jest w pełni nawiązane (w dowolnym kierunku).

api.on("dcc.chat.connected", function(event)
    -- event.connection_id  (string)
    -- event.nick           (string)
end)

dcc.chat.message

Wyzwalane, gdy wiadomość dociera przez nawiązane połączenie DCC CHAT. Zwróć true, aby wyciszyć wyświetlanie.

api.on("dcc.chat.message", function(event)
    -- event.connection_id  (string)
    -- event.nick           (string)
    -- event.text           (string) raw message text
end)

dcc.chat.closed

Wyzwalane, gdy połączenie DCC CHAT zostaje zamknięte (z dowolnej strony).

api.on("dcc.chat.closed", function(event)
    -- event.connection_id  (string)
    -- event.nick           (string)
    -- event.reason         (string) e.g. "remote closed", "timeout", "error"
end)

Zdarzenia cyklu życia

connected

disconnected

command_input

Wyzwalane przed wykonaniem polecenia. Zwróć true, aby wyciszyć.

Polecenia

api.command(name, def)

Rejestruje niestandardowe polecenie slash.

api.command("greet", {
    handler = function(args, connection_id)
        local target = args[1] or "world"
        api.irc.say(target, "Hello, " .. target .. "!")
    end,
    description = "Send a greeting",
    usage = "/greet <nick>",
})

Metody IRC

Wszystkie metody IRC przyjmują opcjonalny connection_id jako ostatni parametr. Jeśli zostanie pominięty, używane jest połączenie aktywnego bufora.

api.irc.say(target, message, connection_id?)

Wyślij PRIVMSG na kanał lub do użytkownika.

api.irc.action(target, message, connection_id?)

Wyślij akcję CTCP ACTION (/me).

api.irc.notice(target, message, connection_id?)

Wyślij NOTICE.

api.irc.join(channel, key?, connection_id?)

Dołącz do kanału, opcjonalnie z kluczem.

api.irc.part(channel, message?, connection_id?)

Opuść kanał z opcjonalnym komunikatem.

api.irc.raw(line, connection_id?)

Wyślij surową linię protokołu IRC.

api.irc.nick(new_nick, connection_id?)

Zmień swój nick.

api.irc.whois(nick, connection_id?)

Wyślij zapytanie WHOIS.

api.irc.mode(target, mode_string, connection_id?)

Ustaw tryb kanału lub użytkownika.

api.irc.kick(channel, nick, reason?, connection_id?)

Kicknij użytkownika z kanału.

api.irc.ctcp(target, type, message?, connection_id?)

Wyślij zapytanie CTCP.

Metody interfejsu

api.ui.print(text)

Wyświetl lokalną wiadomość zdarzenia w aktywnym buforze.

api.ui.print_to(buffer_id, text)

Wyświetl lokalną wiadomość zdarzenia w konkretnym buforze.

api.ui.switch_buffer(buffer_id)

Przejdź do bufora. Gdy akcja przełączenia zostanie zakolejkowana, api.store.active_buffer() odzwierciedla nowy identyfikator bufora natychmiast w ramach tego samego wywołania zwrotnego.

api.ui.execute(command_line)

Wykonaj polecenie klienta (np. api.ui.execute("/set theme default")).

Dostęp do stanu

api.store.active_buffer()

Zwraca identyfikator aktywnego bufora lub nil.

api.store.our_nick(connection_id?)

Zwraca bieżący nick lub nil, jeśli nie jesteś połączony. Jeśli connection_id nie jest podany, używa połączenia aktywnego bufora.

api.store.connections()

Zwraca tablicę wszystkich połączeń. Każdy wpis zawiera: id, label, nick, connected, user_modes.

api.store.connection(connection_id)

Zwraca informacje o konkretnym połączeniu lub nil.

api.store.buffers()

Zwraca tablicę wszystkich buforów. Każdy wpis zawiera: id, connection_id, name, buffer_type, topic, unread_count.

api.store.buffer(buffer_id)

Zwraca informacje o konkretnym buforze lub nil.

api.store.nicks(buffer_id)

Zwraca tablicę nicków w buforze. Każdy wpis zawiera: nick, prefix, modes, away.

Konfiguracja

api.config.get(key, default?)

Pobierz wartość konfiguracji specyficzną dla skryptu lub default (bądź nil), gdy nie jest ustawiona.

api.config.set(key, value)

Ustaw wartość konfiguracji specyficzną dla skryptu w czasie wykonywania i utrwal ją w config.toml w sekcji [scripts.values.<nazwa_skryptu>], dzięki czemu przetrwa przeładowanie skryptu oraz restart klienta.

api.config.app_get(key_path)

Odczytaj wartość konfiguracji aplikacji za pomocą ścieżki rozdzielonej kropkami. Zwraca wartość jako string lub nil.

local theme = api.config.app_get("general.theme")
local nick_width = api.config.app_get("display.nick_width")

Timery

api.timer(ms, handler)

Uruchom powtarzający się timer. Zwraca identyfikator timera.

api.timeout(ms, handler)

Uruchom jednorazowy timeout. Zwraca identyfikator timera.

api.cancel_timer(id)

Anuluj timer.

Logowanie

api.log(message)

Zaloguj wiadomość debugowania. Wyświetla dane wyjściowe tylko gdy scripts.debug = true w konfiguracji.