$ opm get jprjr/irc-parser

lua-irc-parser

[!codecov](https://codecov.io/gh/jprjr/lua-irc-parser)

一个基于 LPEG 的 IRC 解析器，带有纯 Lua 备用方案。支持 IRCv3 消息标签。

概要

    local parser = require('irc-parser').new()
    local line = '@message-id=12345;some-content=hello\\sthere;empty-str=;empty :nick!user@example.com PRIVMSG #a-room ::-) Hi there!'
    local parsed, pos = parser(line)
    
    --[[
      parsed is a table:
      {
        tags = {
          empty = false,
          ["empty-str"] = false,
          ["message-id"] = "12345",
          ["some-content"] = "hello there"
        },
        source = {
          host = "example.com",
          nick = "nick",
          user = "user"
        },
        command = "PRIVMSG",
        params = { "#a-room", ":-) Hi there!" },
      }
    
      pos is the length of the string + 1, so in this case 115
    ]]

安装

luarocks

可在 luarocks 上获取

    luarocks install irc-parser

OPM

可在 OPM 上获取

    opm install jprjr/irc-parser

使用方法

默认情况下，您可以 require('irc-parser')，它会自动选择合适的后端。

它将首先尝试加载基于 LPEG 的后端，如果 LPEG 不可使用，则回退到纯 Lua 后端。

您可以通过要求它强制使用特定的后端：require('irc-parser.fallback') 用于 Lua 备用方案，require('irc-parser.lpeg') 用于 LPEG 版本。

实例化

然后，您可以使用 .new([mode],[opts]) 实例化一个解析器（或者直接调用返回的模块，例如 parser = require('irc-parser')([mode],[opts])）。

mode 参数是可选的。如果未指定，解析器将处于 LOOSE 模式。

有三种不同的模式可用

• LOOSE - 旨在广泛兼容。

• STRICT - 尽可能遵循 IRC RFC。

• TWITCH - 本质上是 STRICT，对 Twitch 的 IRC 接口进行了一些修改。

默认的 LOOSE 模式应该适用于大多数 IRC 服务器，包括 Twitch。在我的测试中，它也是最快的（因为它执行的验证比任何其他模式都少）。

您可以通过几种方式指定所需的模式

    -- these are all equivalent:
    -- use a string name
    local strict_parser = require('irc-parser')('strict')
    local strict_parser = require('irc-parser')('STRICT')
    
    -- use an enum
    local mod = require('irc-parser')
    local strict_parser = mod.new(mod.STRICT)

opts 参数是一个选项表，用于微调空标签和缺失标签的处理方式。默认情况下，空标签和缺失标签将转换为布尔值 false。

如果您希望对空标签或缺失标签使用不同的值（例如，假设您希望空标签保留为空字符串），您可以

    local parser = require('irc-parser')('loose', {
      empty_tag_replacement = '',
    })

现在，空标签将被返回为空字符串，缺失标签将保留为 false。

您也可以指定希望完全删除空字符串和缺失字符串

    local parser = require('irc-parser')('loose', {
      remove_empty_tags = true,
      remove_missing_tags = true,
    })

解析

解析器公开了一个方法 parser:parse(str, [pos])。解析器本身也可以作为函数调用，parser(str, [pos])。

它接受一个字符串参数，字符串参数可以以换行符或回车符和换行符结尾，也可以不结尾。它还接受一个可选的 position 参数，它应该是一个表示从哪里开始解析的数字。

如果成功，它将返回一个解析后的表，以及下一个解析的位置（本质上是行长度 + 1）。这个 position 参数是为了让你能够处理包含多行的字符串。

如果失败，它将返回 nil。

以下是如何使用 position 参数和返回值循环遍历一组数据的示例。

返回的表将具有以下键

• tags - 标签值的表，如果消息没有附加标签，则为 nil。

• source - 表示消息源的表，包含键 host、nick 和/或 user。如果消息没有源，则 source 为 nil。

• command - IRC 命令（例如，PRIVMSG、001 等）。

• params - 参数的类似数组的表，如果没有参数，则为 nil。

    local parser = require('irc-parser').new()
    -- we'll say that "raw.txt" is a raw IRC log file with multiple lines
    local rawfile = io.open('raw.txt','rb')
    local rawdata = rawfile:read('*a')
    rawfile:close()
    
    local parsed
    local pos = 1
    
    while pos < #rawdata do
      parsed, pos = parser:parse(rawdata,pos)
      if not parsed then
        break
      end
      -- do something with parsed
      print(parsed.command)
    end

许可证

MIT（请参阅文件 LICENSE）。