--- 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
--
module "irc"
--- Create a new IRC object. Use irc:connect to connect to a server.
-- @param user Table with fields nick, username and realname.
-- The nick field is required.
--
-- @return Returns a new irc object.
function new(user)
--- Hook a function to an event.
-- @param name Name of event.
-- @param id Unique tag.
-- @param f Callback function. [defaults to id]
-- @see Hooks
function irc:hook(name, id, f)
--- Remove previous hooked callback.
-- @param name Name of event.
-- @param id Unique tag.
function irc:unhook(name, id)
--- Connect irc to an IRC server.
-- @param host Host address.
-- @param port Server port. [default 6667]
function irc:connect(host, port)
-- @param table Table of connection details
-- @see Connection
function irc:connect(table)
--- Disconnect irc from the server.
-- @param message Quit message.
function irc:disconnect(message)
--- 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.
function irc:think()
--- Look up user info.
-- @param nick Nick of user to query.
-- @return Table with fields userinfo, node, channels and account.
function irc:whois(nick)
--- Look up topic.
-- Use this to invoke the hooks OnTopic and OnTopicInfo at any time.
-- @param channel Channel to query.
function irc:topic(channel)
--- Send a IRC message to the server.
-- @param msg Message or raw line to send, excluding newline characters.
-- @param ... Format parameters for msg, with string.format semantics. [optional]
function irc:send(msg, ...)
--- Send a message to a channel or user.
-- @param target Nick or channel to send to.
-- @param message Message text.
function irc:sendChat(target, message)
--- Send a notice to a channel or user.
-- @param target Nick or channel to send to.
-- @param message Notice text.
function irc:sendNotice(target, message)
--- Join a channel.
-- @param channel Channel to join.
-- @param key Channel key. [optional]
function irc:join(channel, key)
--- Leave a channel.
-- @param channel Channel to leave.
function irc:part(channel)
--- Turn user information tracking on or off. User tracking is enabled by default.
-- @param b Boolean whether or not to track user information.
function irc:trackUsers(b)
--- Add/remove modes for a channel or nick.
-- @param 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"}
function irc:setMode(t)
--internal
function irc:invoke(name, ...)
function irc:handle(msg)
function irc:shutdown()
--- 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
-- @name Connection
-- @class table
--- Class representing an IRC message. Objects of this class may contain the following fields:
--
-- tags - A table of IRCv3 tags.prefix - Prefix of the message.user - A User object describing the sender of the message.command - The IRC command.args - A list of the command arguments.
-- Fields may be missing. The only guarantee is that args is a table.
-- Messages have the following methods:
--
-- @name Message
-- @class table
--- 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)DoX(msg)'X' is any IRC command or numeric with the first letter capitalized (eg, DoPing and Do001)
-- * Event also invoked for yourself.
-- † Channel passed only when user tracking is enabled
-- @name Hooks
-- @class table
--- Table with information about a user.
--
-- server - Server name.nick - User nickname.username - User username.host - User hostname.realname - User real name.access - User access, available in channel-oriented callbacks. A table containing boolean fields for each access mode that the server supports. Eg: 'o', and 'v'.
-- Fields may be missing. To fill them in, enable user tracking and use irc:whois.
-- @name User
-- @class table