Module irc

LuaIRC is a low-level IRC library for Lua. All functions raise Lua exceptions on error. Use new to create a new IRC object.
Example:

require "irc"
local sleep = require "socket".sleep

local s = irc.new{nick = "example"}

s:hook("OnChat", function(user, channel, message)
print(("[%s] %s: %s"):format(channel, user.nick, message))
end)

s:connect("irc.example.net")
s:join("#example")

while true do
s:think()
sleep(0.5)
end

Functions

irc:connect (host, port) Connect irc to an IRC server.
irc:disconnect (message) Disconnect irc from the server.
irc:hook (name, id, f) Hook a function to an event.
irc:join (channel, key) Join a channel.
irc:part (channel) Leave a channel.
irc:send (msg, ...) Send a raw line of IRC to the server.
irc:sendChat (target, message) Send a message to a channel or user.
irc:sendNotice (target, message) Send a notice to a channel or user.
irc:setMode (t) Add/remove modes for a channel or nick.
irc:think () Handle incoming data for irc, and invoke previously hooked callbacks based on new server input.
irc:topic (channel) Look up topic.
irc:trackUsers (b) Turn user information tracking on or off.
irc:unhook (name, id) Remove previous hooked callback.
irc:whois (nick) Look up user info.
new (user) Create a new IRC object.

Tables

Connection Table with connection information.
Hooks List of hooks you can use with irc:hook.
User Table with information about a user.


Functions

irc:connect (host, port)
Connect irc to an IRC server.

Parameters

  • host: Host address.
  • port: Server port. [default 6667]
irc:disconnect (message)
Disconnect irc from the server.

Parameters

  • message: Quit message.
irc:hook (name, id, f)
Hook a function to an event.

Parameters

  • name: Name of event.
  • id: Unique tag.
  • f: Callback function. [defaults to id]

See also:

irc:join (channel, key)
Join a channel.

Parameters

  • channel: Channel to join.
  • key: Channel password. [optional]
irc:part (channel)
Leave a channel.

Parameters

  • channel: Channel to leave.
irc:send (msg, ...)
Send a raw line of IRC to the server.

Parameters

  • msg: Line to be sent, excluding newline characters.
  • ...: Format parameters for msg, with string.format semantics. [optional]
irc:sendChat (target, message)
Send a message to a channel or user.

Parameters

  • target: Nick or channel to send to.
  • message: Message to send.
irc:sendNotice (target, message)
Send a notice to a channel or user.

Parameters

  • target: Nick or channel to send to.
  • message: Notice to send.
irc:setMode (t)
Add/remove modes for a channel or nick.

Parameters

  • t: Table with fields target, nick, add and/or rem. target or nick specifies the user or channel to add/remove modes. add is a list of modes to add to the user or channel. rem is a list of modes to remove from the user or channel.

Usage:

Example which sets +m (moderated) for #channel:
irc:setMode{target = "#channel", add = "m"}
irc:think ()
Handle incoming data for irc, and invoke previously hooked callbacks based on new server input. You should call this in some kind of main loop, or at least often enough to not time out.
irc:topic (channel)
Look up topic. Use this to invoke the hooks OnTopic and OnTopicInfo at any time.

Parameters

  • channel: Channel to query.
irc:trackUsers (b)
Turn user information tracking on or off. User tracking is enabled by default.

Parameters

  • b: Boolean whether or not to track user information.
irc:unhook (name, id)
Remove previous hooked callback.

Parameters

  • name: Name of event.
  • id: Unique tag.
irc:whois (nick)
Look up user info.

Parameters

  • nick: Nick of user to query.

Return value:

Table with fields userinfo, node, channels and account.
new (user)
Create a new IRC object. Use irc:connect to connect to a server.

Parameters

  • user: Table with fields nick, username and realname. The nick field is required.

Return value:

Returns a new irc object.

Tables

Connection
Table with connection information.
  • host - Server host name.
  • port - Server port. [defaults to 6667]
  • timeout - Connect timeout. [defaults to 30]
  • password - Server password.
  • secure - Boolean to enable TLS connection, pass a params table (described, [luasec]) to control
[luasec]: http://www.inf.puc-rio.br/~brunoos/luasec/reference.html
Hooks
List of hooks you can use with irc:hook. The parameter list describes the parameters passed to the callback function.
  • PreRegister(connection)Useful for CAP commands and SASL.
  • OnRaw(line) - (any non false/nil return value assumes line handled and will not be further processed)
  • OnSend(line)
  • OnDisconnect(message, errorOccurred)
  • OnChat(user, channel, message)
  • OnNotice(user, channel, message)
  • OnJoin(user, channel)*
  • OnPart(user, channel)*
  • OnQuit(user, message)
  • NickChange(user, newnick, channel)*†
  • NameList(channel, names)
  • OnTopic(channel, topic)
  • OnTopicInfo(channel, creator, timeCreated)
  • OnKick(channel, nick, kicker, reason)* (kicker is a user table)
  • OnUserMode(modes)
  • OnChannelMode(user, channel, modes)
  • OnModeChange(user, target, modes, ...)* ('...' contains mode options such as banmasks)
* Event also invoked for yourself. † Channel passed only when user tracking is enabled
User
Table with information about a user.
  • nick - User nickname. Always present.
  • username - User username.
  • host - User hostname.
  • realname - User real name.
  • access - User access, available in channel-oriented callbacks. A table containing the boolean fields 'op', 'halfop', and 'voice'.
Apart from nick, fields may be missing. To fill them in, enable user tracking and use irc:whois.

Valid XHTML 1.0!