-- erkSearch - IRC network finder for HexChat (Lua) -- ------------------------------------------------ -- Searches the erkstats public API for IRC networks and lets you connect. No API -- key needed - the API is public. HexChat scripts have no GUI, so this is -- command-based: results print to the current window, numbered, and you join by -- number. -- -- Install: put this file in HexChat's addons folder (Window > ... or -- ~/.config/hexchat/addons/), or run: /lua load /path/to/erksearch.lua -- Needs: curl on your PATH (standard on modern Windows/macOS/Linux). -- -- Commands: -- /erksearch [sort=..] [lang=..] [show=N] search by keyword: names, descriptions, -- tags and languages, best match first -- /erksearch tag= [terms] [..] networks with that tag -- /erksearch [sort=..] [lang=..] [show=N] (no terms) browse the top networks -- /erkinfo full details for result n -- /erkconnect connect to result n -- /erk show help -- -- sort = best (default for a search) | users (default for browsing) | 30d | channels -- | servers | name | newest | oldest -- e.g. /erksearch linux /erksearch tag=gaming /erksearch sort=newest lang=german show=25 local VERSION = "1.2" hexchat.register("erkSearch", VERSION, "Find IRC networks via the erkstats public API") local API = "https://erkstats.info/api/v1/public" local TAG = "\002erkSearch\002 " local last = {} -- last result list (array of network tables) local is_windows = package.config:sub(1, 1) == "\\" -- friendly sort name -> { api_sort, dir } local SORTS = { best = { "relevance", "desc" }, users = { "users", "desc" }, ["30d"] = { "users_30d", "desc" }, avg = { "users_30d", "desc" }, channels = { "channels", "desc" }, servers = { "servers", "desc" }, name = { "name", "asc" }, newest = { "founded", "desc" }, oldest = { "founded", "asc" }, age = { "founded", "asc" }, } -- ---- helpers ----------------------------------------------------------------- local function say(msg) hexchat.print(TAG .. msg) end local function comma(n) if not n then return "?" end local s = tostring(n) local out = s:reverse():gsub("(%d%d%d)", "%1,"):reverse() return (out:gsub("^,", "")) end local function trunc(s, n) s = s or "" if #s <= n then return s end return s:sub(1, n - 1) .. "\226\128\166" -- ellipsis end local function urlencode(s) return (tostring(s):gsub("[^%w%._~%-]", function(c) return string.format("%%%02X", string.byte(c)) end)) end -- shell-quote a URL so & etc. are not interpreted by the shell local function shq(s) if is_windows then return '"' .. s .. '"' -- cmd treats & as literal inside quotes end return "'" .. s:gsub("'", "'\\''") .. "'" end local function http_get(url) local cmd = "curl -sS --max-time 15 -A " .. shq("erksearch-hexchat/" .. VERSION) .. " " .. shq(url) local f = io.popen(cmd, "r") if not f then return nil, "could not run curl (is it installed?)" end local body = f:read("*a") f:close() if not body or body == "" then return nil, "no response (network error or curl missing)" end return body end -- ---- a tiny JSON decoder (decode only) --------------------------------------- local function utf8char(cp) local fl = math.floor if cp < 0x80 then return string.char(cp) end if cp < 0x800 then return string.char(0xC0 + fl(cp / 0x40), 0x80 + cp % 0x40) end return string.char(0xE0 + fl(cp / 0x1000), 0x80 + fl(cp / 0x40) % 0x40, 0x80 + cp % 0x40) end local function json_decode(s) local i, n = 1, #s local value local function ws() local a, b = s:find("^[ \t\r\n]+", i); if a then i = b + 1 end end local function ch() return s:sub(i, i) end local ESC = { n = "\n", t = "\t", r = "\r", b = "\b", f = "\f", ['"'] = '"', ["\\"] = "\\", ["/"] = "/" } local function pstr() i = i + 1 local t = {} while i <= n do local c = s:sub(i, i) if c == '"' then i = i + 1; return table.concat(t) end if c == "\\" then local e = s:sub(i + 1, i + 1) if e == "u" then t[#t + 1] = utf8char(tonumber(s:sub(i + 2, i + 5), 16) or 63); i = i + 6 else t[#t + 1] = ESC[e] or e; i = i + 2 end else t[#t + 1] = c; i = i + 1 end end error("unterminated string") end local function pnum() local a, b = s:find("^%-?%d+%.?%d*[eE]?[%+%-]?%d*", i) local v = tonumber(s:sub(a, b)); i = b + 1; return v end local function parr() i = i + 1; local t = {}; ws() if ch() == "]" then i = i + 1; return t end while true do t[#t + 1] = value(); ws() local c = ch() if c == "," then i = i + 1; ws() elseif c == "]" then i = i + 1; return t else error("expected , or ]") end end end local function pobj() i = i + 1; local t = {}; ws() if ch() == "}" then i = i + 1; return t end while true do ws() if ch() ~= '"' then error("expected key") end local k = pstr(); ws() if ch() ~= ":" then error("expected :") end i = i + 1; ws() t[k] = value(); ws() local c = ch() if c == "," then i = i + 1 elseif c == "}" then i = i + 1; return t else error("expected , or }") end end end value = function() ws() local c = ch() if c == '"' then return pstr() end if c == "{" then return pobj() end if c == "[" then return parr() end if c == "t" then i = i + 4; return true end if c == "f" then i = i + 5; return false end if c == "n" then i = i + 4; return nil end -- null return pnum() end local ok, res = pcall(value) if not ok then return nil, res end return res end -- ---- request + parse --------------------------------------------------------- local function fetch(url) local body, err = http_get(url) if not body then return nil, err end local data = json_decode(body) if type(data) ~= "table" then return nil, "unexpected response from server" end if data.error then return nil, data.error end return data end -- parse "sort=.. lang=.. show=.." flags out of the args; the rest is the query local function parse_args(argline) local opts = { sort = nil, dir = "desc", lang = nil, tag = nil, show = 10 } local terms = {} for tok in tostring(argline or ""):gmatch("%S+") do local k, v = tok:match("^(%a+)=(.+)$") if k == "sort" then local s = SORTS[v:lower()] if not s then return nil, 'Unknown sort "' .. v .. '". Use best, users, 30d, channels, servers, name, newest or oldest.' end opts.sort, opts.dir = s[1], s[2] elseif k == "lang" then opts.lang = v elseif k == "tag" then opts.tag = v:gsub("^#", "") elseif k == "show" then opts.show = math.max(1, math.min(100, tonumber(v) or 10)) else terms[#terms + 1] = tok end end return table.concat(terms, " "), opts end local function build_url(query, opts) local searching = query ~= "" or opts.tag -- a search ranks best match first unless a sort is asked for; browsing has no -- "best", so it lists the biggest first local sort = opts.sort or (searching and "relevance" or "users") if sort == "relevance" and not searching then sort = "users" end local params = { "sort=" .. sort, "dir=" .. opts.dir, "limit=" .. opts.show } local path = "/networks" if searching then path = "/search/network" if query ~= "" then table.insert(params, 1, "q=" .. urlencode(query)) end if opts.tag then params[#params + 1] = "tag=" .. urlencode(opts.tag) end end if opts.lang and opts.lang ~= "" then params[#params + 1] = "lang=" .. urlencode(opts.lang) end return API .. path .. "?" .. table.concat(params, "&") end -- ---- output ------------------------------------------------------------------ local function print_results(data, query, opts) last = data.results or {} local what = query ~= "" and ('"' .. query .. '"') or "" if opts.tag then what = (what ~= "" and (what .. " ") or "") .. "tag " .. opts.tag end if #last == 0 then say("No networks found" .. (what ~= "" and (" for " .. what) or "") .. ".") return end if what == "" then what = "top networks" end say(("%d match(es) for %s - showing %d. /erkconnect N to join, /erkinfo N for details.") :format(data.count or #last, what, #last)) -- the words the search widened to (word forms, related words) if type(data.also_matching) == "table" and #data.also_matching > 0 then say("Also matching: " .. table.concat(data.also_matching, ", ")) end for i, nw in ipairs(last) do local tls = nw.tls and " (TLS)" or "" local ver = nw.verified and " [verified]" or "" hexchat.print(("%2d. \002%-20s\002 %9s users %-10s %-5s %s:%s%s%s"):format( i, trunc(nw.name, 20), comma(nw.users), nw.language or "-", nw.founded or "-", nw.server, tostring(nw.port), tls, ver)) end end -- ---- commands ---------------------------------------------------------------- local function cmd_search(word, word_eol) local query, opts = parse_args(word_eol[2]) if not query then say(opts) return hexchat.EAT_ALL end if query ~= "" and #query < 2 and not opts.tag then say("Enter at least 2 characters to search, or nothing to browse the top networks.") return hexchat.EAT_ALL end if query ~= "" then say('Searching for "' .. query .. '" ...') elseif opts.tag then say("Searching for tag " .. opts.tag .. " ...") else say("Loading top networks ...") end local data, err = fetch(build_url(query, opts)) if not data then say("Error: " .. tostring(err)) else print_results(data, query, opts) end return hexchat.EAT_ALL end local function cmd_info(word) local n = tonumber(word[2]) local nw = n and last[n] if not nw then say("No result #" .. tostring(word[2]) .. ". Run a search first.") return hexchat.EAT_ALL end say("\002" .. nw.name .. "\002" .. (nw.verified and " [verified]" or "")) hexchat.print(" Server: " .. nw.server .. ":" .. tostring(nw.port) .. (nw.tls and " (TLS)" or " (plain)")) hexchat.print(" Users: " .. comma(nw.users) .. " online, " .. comma(nw.users_30d_avg) .. " avg (30d)") if nw.language then hexchat.print(" Language: " .. nw.language) end if nw.founded then hexchat.print(" Founded: " .. tostring(nw.founded)) end if nw.website then hexchat.print(" Website: " .. nw.website) end hexchat.print(" Connect: " .. (nw.connect_uri or "")) if nw.blurb then hexchat.print(" " .. nw.blurb) end return hexchat.EAT_ALL end local function cmd_connect(word) local n = tonumber(word[2]) local nw = n and last[n] if not nw then say("No result #" .. tostring(word[2]) .. ". Run a search first.") return hexchat.EAT_ALL end say("Connecting to " .. nw.name .. " (" .. nw.server .. ":" .. tostring(nw.port) .. ") ...") hexchat.command("newserver " .. (nw.tls and "-ssl " or "") .. nw.server .. " " .. tostring(nw.port)) return hexchat.EAT_ALL end local function cmd_help() say("commands:") hexchat.print(" /erksearch [sort=..] [lang=..] [show=N] - search networks") hexchat.print(" /erksearch tag= [terms] - networks with a tag") hexchat.print(" /erksearch [sort=..] [lang=..] [show=N] - browse the top networks") hexchat.print(" /erkinfo - full details for result n") hexchat.print(" /erkconnect - connect to result n") hexchat.print(" sort = best | users | 30d | channels | servers | name | newest | oldest") return hexchat.EAT_ALL end hexchat.hook_command("ERKSEARCH", cmd_search, "Usage: /erksearch [sort=..] [lang=..] [show=N] (no terms = browse top)") hexchat.hook_command("ERKINFO", cmd_info, "Usage: /erkinfo - details for search result n") hexchat.hook_command("ERKCONNECT", cmd_connect, "Usage: /erkconnect - connect to search result n") hexchat.hook_command("ERK", cmd_help, "Show erkSearch help") hexchat.print(TAG .. "loaded. Type /erk for help, /erksearch to search.")