{"id":16866356,"url":"https://github.com/jprjr/lua-irc-parser","last_synced_at":"2025-03-18T17:43:18.456Z","repository":{"id":70966733,"uuid":"464321341","full_name":"jprjr/lua-irc-parser","owner":"jprjr","description":"An IRC parser for Lua in LPEG, with a Pure-Lua fallback","archived":false,"fork":false,"pushed_at":"2022-02-28T20:35:39.000Z","size":27,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-24T21:13:46.092Z","etag":null,"topics":["irc","irc-protocol","lua","luajit"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jprjr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-28T03:09:52.000Z","updated_at":"2022-02-28T03:57:32.000Z","dependencies_parsed_at":"2023-04-13T01:48:01.972Z","dependency_job_id":null,"html_url":"https://github.com/jprjr/lua-irc-parser","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jprjr%2Flua-irc-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jprjr%2Flua-irc-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jprjr%2Flua-irc-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jprjr%2Flua-irc-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jprjr","download_url":"https://codeload.github.com/jprjr/lua-irc-parser/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244272541,"owners_count":20426754,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["irc","irc-protocol","lua","luajit"],"created_at":"2024-10-13T14:50:19.481Z","updated_at":"2025-03-18T17:43:18.429Z","avatar_url":"https://github.com/jprjr.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# lua-irc-parser\n\n[![codecov](https://codecov.io/gh/jprjr/lua-irc-parser/branch/main/graph/badge.svg?token=9wV63fuaVu)](https://codecov.io/gh/jprjr/lua-irc-parser)\n\nAn IRC parser in LPEG, with a pure-Lua fallback. Supports IRCv3 message tags.\n\n## Synopsis\n\n```lua\nlocal parser = require('irc-parser').new()\nlocal line = '@message-id=12345;some-content=hello\\\\sthere;empty-str=;empty :nick!user@example.com PRIVMSG #a-room ::-) Hi there!'\nlocal parsed, pos = parser(line)\n\n--[[\n  parsed is a table:\n  {\n    tags = {\n      empty = false,\n      [\"empty-str\"] = false,\n      [\"message-id\"] = \"12345\",\n      [\"some-content\"] = \"hello there\"\n    },\n    source = {\n      host = \"example.com\",\n      nick = \"nick\",\n      user = \"user\"\n    },\n    command = \"PRIVMSG\",\n    params = { \"#a-room\", \":-) Hi there!\" },\n  }\n\n  pos is the length of the string + 1, so in this case 115\n]]\n```\n\n## Installation\n\n### luarocks\n\nAvailable on [luarocks](https://luarocks.org/modules/jprjr/irc-parser):\n\n```bash\nluarocks install irc-parser\n```\n\n### OPM\n\nAvailable on [OPM](https://opm.openresty.org/package/jprjr/irc-parser/)\n\n```bash\nopm install jprjr/irc-parser\n```\n\n## Usage\n\nBy default, you can `require('irc-parser')`, and it will automatically\nchoose an appropriate backend.\n\nIt will first try to load the LPEG-based backend, and fall back\nto the pure-Lua backend if LPEG is not available.\n\nYou can force a specific backend by requiring it: `require('irc-parser.fallback')`\nfor the Lua fallback, and `require('irc-parser.lpeg')` for the LPEG version.\n\n### Instantiating\n\nYou can then instantiate a parser with `.new([mode],[opts])` (or just call the returned\nmodule directly like `parser = require('irc-parser')([mode],[opts])`.\n\nThe `mode` argument is optional. If not specified, the parser will be in\n`LOOSE` mode.\n\nThere's three different modes available:\n\n* `LOOSE` - aims to be broadly-compatible.\n* `STRICT` - follows the IRC RFCs as closely as possible.\n* `TWITCH` - essentially `STRICT` with a few modifications for Twitch's IRC interface.\n\nThe default `LOOSE` mode should work on most IRC servers, including Twitch. In\nmy testing, it's also the fastest (since it performs less validations than\nany other mode).\n\nYou can specify which mode you'd like in a few ways:\n\n```lua\n\n-- these are all equivalent:\n-- use a string name\nlocal strict_parser = require('irc-parser')('strict')\nlocal strict_parser = require('irc-parser')('STRICT')\n\n-- use an enum\nlocal mod = require('irc-parser')\nlocal strict_parser = mod.new(mod.STRICT)\n```\n\nThe `opts` argument is a table of options to fine-tune handling of empty and\nmissing tag values. By default, empty and missing tags are converted to\nthe boolean `false`.\n\nIf you'd prefer a different value for either empty or missing tags (example,\nsay you want empty tags to remain empty strings), you can:\n\n```lua\nlocal parser = require('irc-parser')('loose', {\n  empty_tag_replacement = '',\n})\n```\n\nAnd now empty tags will be returned as empty strings, missing tags\nwill remain as `false`.\n\nYou can also specify that you'd like empty and missing strings to be\nremoved entirely:\n\n```lua\nlocal parser = require('irc-parser')('loose', {\n  remove_empty_tags = true,\n  remove_missing_tags = true,\n})\n```\n\n### Parsing\n\nThe parser exposes a single method, `parser:parse(str, [pos])`. The parser itself\ncan also be called as a function, `parser(str, [pos])`.\n\nIt accepts a string argument, the string argument can be terminated with\na newline character, or a carriage return and newline, or nothing. It also\naccepts an optional position argument, this should be a number indicating\nwhere to start parsing.\n\nIf successful, it will return a parsed table, and the position for the\nnext parse (essentially the length of the line + 1). This position\nargument is so you can have a string with multiple lines.\n\nIf not successful, it returns `nil`.\n\nHere's an example of looping through a block of data using the\nposition argument and return value.\n\nThe returned table will have the following keys:\n\n* `tags` - a table of tag values, or `nil` if no tags were attached to the message.\n* `source` - a table representing the message source with the keys `host`, `nick`,\nand/or `user`. `source` will be `nil` if there was no source on the message.\n* `command` - an IRC command (ie, `PRIVMSG`, `001`, etc).\n* `params` - an array-like table of parameters, or `nil` if there were no parameters.\n\n```\nlocal parser = require('irc-parser').new()\n-- we'll say that \"raw.txt\" is a raw IRC log file with multiple lines\nlocal rawfile = io.open('raw.txt','rb')\nlocal rawdata = rawfile:read('*a')\nrawfile:close()\n\nlocal parsed\nlocal pos = 1\n\nwhile pos \u003c #rawdata do\n  parsed, pos = parser:parse(rawdata,pos)\n  if not parsed then\n    break\n  end\n  -- do something with parsed\n  print(parsed.command)\nend\n```\n\n\n## LICENSE\n\nMIT (see file `LICENSE`).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjprjr%2Flua-irc-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjprjr%2Flua-irc-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjprjr%2Flua-irc-parser/lists"}