Allow hooking to any IRC command

Generate a new nickname when it is in use or erroneous and check the...

README.markdown

@@ -14,9 +14,5 @@ Dependencies
 
 Documentation
 -------------
-Documentation can be automatically generated from the doc/irc.luadoc file, pre-generated documentation can be found in the gh-branch.
-
-You can also browse it [online](http://jakobovrum.github.com/LuaIRC/doc/modules/irc.html).
-
-Documentation is generated by [LuaDoc](http://luadoc.luaforge.net/)
+Documentation can be automatically generated by passing irc.luadoc (in doc/) to [LuaDoc](http://luadoc.luaforge.net/), or pre-generated documentation can be found in the 'gh-pages' branch, which can also be browsed [online](http://jakobovrum.github.com/LuaIRC/doc/modules/irc.html).
 

asyncoperations.lua

@@ -1,11 +1,18 @@
 local table = table
+local assert = assert
+local select = select
 
 module "irc"
 
 local meta = _META
 
-function meta:send(fmt, ...)
-	local bytes, err = self.socket:send(fmt:format(...) .. "\r\n")
+function meta:send(msg, ...)
+	if select("#", ...) > 0 then
+		msg = msg:format(...)
+	end
+	self:invoke("OnSend", msg)
+
+	local bytes, err = self.socket:send(msg .. "\r\n")
 
 	if not bytes and err ~= "timeout" and err ~= "wantwrite" then
 		self:invoke("OnDisconnect", err, true)

doc/irc.luadoc

@@ -71,9 +71,9 @@ function irc:whois(nick)
 function irc:topic(channel)
 
 --- Send a raw line of IRC to the server.
--- @param fmt Line to be sent, excluding newline characters.
--- @param ... Format parameters for <code>fmt</code>, with <code>string.format</code> semantics.
-function irc:send(fmt, ...)
+-- @param msg Line to be sent, excluding newline characters.
+-- @param ... Format parameters for <code>msg</code>, with <code>string.format</code> semantics. [optional]
+function irc:send(msg, ...)
 
 --- Send a message to a channel or user.
 -- @param target Nick or channel to send to.
@@ -125,7 +125,9 @@ function irc:shutdown()
 
 --- List of hooks you can use with irc:hook. The parameter list describes the parameters passed to the callback function.
 -- <ul>
+-- <li><code>PreRegister(connection)</code>Useful for CAP commands and SASL.</li>
 -- <li><code>OnRaw(line) - (any non false/nil return value assumes line handled and will not be further processed)</code></li>
+-- <li><code>OnSend(line)</code></li>
 -- <li><code>OnDisconnect(message, errorOccurred)</code></li>
 -- <li><code>OnChat(user, channel, message)</code></li>
 -- <li><code>OnNotice(user, channel, message)</code></li>
@@ -137,8 +139,10 @@ function irc:shutdown()
 -- <li><code>OnTopic(channel, topic)</code></li>
 -- <li><code>OnTopicInfo(channel, creator, timeCreated)</code></li>
 -- <li><code>OnKick(channel, nick, kicker, reason)</code>* (kicker is a <code>user</code> table)</li>
--- <li><code>OnUserModeIs(modes)</code></li>
--- <li><code>OnChannelModeIs(user, channel, modes)</code></li>
+-- <li><code>OnUserMode(modes)</code></li>
+-- <li><code>OnChannelMode(user, channel, modes)</code></li>
+-- <li><code>OnModeChange(user, target, modes, ...)</code>* ('...' contains mode options such as banmasks)</li>
+-- <li><code>DoX(user, ...)</code>'X' is any IRC command or numeric with the first letter capitalized (eg, DoPing and Do001)</li>
 -- </ul>
 -- * Event also invoked for yourself.
 -- <20> Channel passed only when user tracking is enabled
@@ -151,7 +155,7 @@ function irc:shutdown()
 -- <li><code>username</code> - User username.</li>
 -- <li><code>host</code> - User hostname.</li>
 -- <li><code>realname</code> - User real name.</li>
--- <li><code>access</code> - User access, available in channel-oriented callbacks. Can be '+', '@', and others, depending on the server.</li>
+-- <li><code>access</code> - User access, available in channel-oriented callbacks. A table containing the boolean fields 'op', 'halfop', and 'voice'.</li>
 -- </ul>
 -- Apart from <code>nick</code>, fields may be missing. To fill them in, enable user tracking and use irc:whois.
 -- @name User

handlers.lua

@@ -0,0 +1,171 @@
+local pairs = pairs
+local error = error
+local tonumber = tonumber
+local table = table
+
+module "irc"
+
+handlers = {}
+
+handlers["PING"] = function(o, user, query)
+	o:send("PONG :%s", query)
+end
+
+handlers["001"] = function(o, user, me)
+	o.authed = true
+	o.nick = me
+end
+
+handlers["PRIVMSG"] = function(o, user, channel, message)
+	o:invoke("OnChat", user, channel, message)
+end
+
+handlers["NOTICE"] = function(o, user, channel, message)
+	o:invoke("OnNotice", user, channel, message)
+end
+
+handlers["JOIN"] = function(o, user, channel)
+	if o.track_users then
+		if user.nick == o.nick then
+			o.channels[channel] = {users = {}}
+		else
+			o.channels[channel].users[user.nick] = user
+		end
+	end
+
+	o:invoke("OnJoin", user, channel)
+end
+
+handlers["PART"] = function(o, user, channel, reason)
+	if o.track_users then
+		if user.nick == o.nick then
+			o.channels[channel] = nil
+		else
+			o.channels[channel].users[user.nick] = nil
+		end
+	end
+	o:invoke("OnPart", user, channel, reason)
+end
+
+handlers["QUIT"] = function(o, user, msg)
+	if o.track_users then
+		for channel, v in pairs(o.channels) do
+			v.users[user.nick] = nil
+		end
+	end
+	o:invoke("OnQuit", user, msg)
+end
+
+handlers["NICK"] = function(o, user, newnick)
+	if o.track_users then
+		for channel, v in pairs(o.channels) do
+			local users = v.users
+			local oldinfo = users[user.nick]
+			if oldinfo then
+				users[newnick] = oldinfo
+				users[user.nick] = nil
+				o:invoke("NickChange", user, newnick, channel)
+			end
+		end
+	else
+		o:invoke("NickChange", user, newnick)
+	end
+	if user.nick == o.nick then
+		o.nick = newnick
+	end
+end
+
+local function needNewNick(o, user, target, badnick)
+	local newnick = o.nickGenerator(badnick)
+	o:send("NICK %s", newnick)
+end
+
+-- ERR_ERRONEUSNICKNAME (Misspelt but remains for historical reasons)
+handlers["432"] = needNewNick
+
+-- ERR_NICKNAMEINUSE
+handlers["433"] = needNewNick
+
+--NAMES list
+handlers["353"] = function(o, user, me, chanType, channel, names)
+	if o.track_users then
+		o.channels[channel] = o.channels[channel] or {users = {}, type = chanType}
+
+		local users = o.channels[channel].users
+		for nick in names:gmatch("(%S+)") do
+			local access, name = parseNick(nick)
+			users[name] = {access = access}
+		end
+	end
+end
+
+--end of NAMES
+handlers["366"] = function(o, user, me, channel, msg)
+	if o.track_users then
+		o:invoke("NameList", channel, msg)
+	end
+end
+
+--no topic
+handlers["331"] = function(o, user, me, channel)
+	o:invoke("OnTopic", channel, nil)
+end
+
+--new topic
+handlers["TOPIC"] = function(o, user, channel, topic)
+	o:invoke("OnTopic", channel, topic)
+end
+
+handlers["332"] = function(o, user, me, channel, topic)
+	o:invoke("OnTopic", channel, topic)
+end
+
+--topic creation info
+handlers["333"] = function(o, user, me, channel, nick, time)
+	o:invoke("OnTopicInfo", channel, nick, tonumber(time))
+end
+
+handlers["KICK"] = function(o, user, channel, kicked, reason)
+	o:invoke("OnKick", channel, kicked, user, reason)
+end
+
+--RPL_UMODEIS
+--To answer a query about a client's own mode, RPL_UMODEIS is sent back
+handlers["221"] = function(o, user, user, modes)
+	o:invoke("OnUserMode", modes)
+end
+
+--RPL_CHANNELMODEIS
+--The result from common irc servers differs from that defined by the rfc
+handlers["324"] = function(o, user, user, channel, modes)
+	o:invoke("OnChannelMode", channel, modes)
+end
+
+handlers["MODE"] = function(o, user, target, modes, ...)
+	if o.track_users and target ~= o.nick then
+		local add = true
+		local optList = {...}
+		for c in modes:gmatch(".") do
+			if     c == "+" then add = true
+			elseif c == "-" then add = false
+			elseif c == "o" then
+				local user = table.remove(optList, 1)
+				o.channels[target].users[user].access.op = add
+			elseif c == "h" then
+				local user = table.remove(optList, 1)
+				o.channels[target].users[user].access.halfop = add
+			elseif c == "v" then
+				local user = table.remove(optList, 1)
+				o.channels[target].users[user].access.voice = add
+			end
+		end
+	end
+	o:invoke("OnModeChange", user, target, modes, ...)
+end
+
+handlers["ERROR"] = function(o, user, message)
+	o:invoke("OnDisconnect", message, true)
+	o:shutdown()
+	error(message, 3)
+end
+

init.lua

@@ -19,25 +19,28 @@ _META = meta
 
 require "irc.util"
 require "irc.asyncoperations"
+require "irc.handlers"
 
 local meta_preconnect = {}
 function meta_preconnect.__index(o, k)
 	local v = rawget(meta_preconnect, k)
 
 	if not v and meta[k] then
-		error("field '"..k.."' is not accessible before connecting", 2)
+		error(("field '%s' is not accessible before connecting"):format(k), 2)
 	end
 	return v
 end
 
-function new(user)
+function new(data)
 	local o = {
-		nick = assert(user.nick, "Field 'nick' is required");
-		username = user.username or "lua";
-		realname = user.realname or "Lua owns";
+		nick = assert(data.nick, "Field 'nick' is required");
+		username = data.username or "lua";
+		realname = data.realname or "Lua owns";
+		nickGenerator = data.nickGenerator or defaultNickGenerator;
 		hooks = {};
 		track_users = true;
 	}
+	assert(checkNick(o.nick), "Erroneous nickname passed to irc.new")
 	return setmetatable(o, meta_preconnect)
 end
 
@@ -116,12 +119,17 @@ function meta_preconnect:connect(_host, _port)
 	self.socket = s
 	setmetatable(self, meta)
 
+	self:send("CAP REQ multi-prefix")
+
+	self:invoke("PreRegister", self)
+	self:send("CAP END")
+
 	if password then
 		self:send("PASS %s", password)
 	end
 
-	self:send("USER %s 0 * :%s", self.username, self.realname)
 	self:send("NICK %s", self.nick)
+	self:send("USER %s 0 * :%s", self.username, self.realname)
 
 	self.channels = {}
 
@@ -149,21 +157,19 @@ end
 local function getline(self, errlevel)
 	local line, err = self.socket:receive("*l")
 
-	if line then
-		return line
-	end
-
-	if err ~= "timeout" and err ~= "wantread" then
+	if not line and err ~= "timeout" and err ~= "wantread" then
 		self:invoke("OnDisconnect", err, true)
-		self:close()
+		self:shutdown()
 		error(err, errlevel)
 	end
+
+	return line
 end
 
 function meta:think()
 	while true do
 		local line = getline(self, 3)
-		if line then
+		if line and #line > 0 then
 			if not self:invoke("OnRaw", line) then
 				self:handle(parse(line))
 			end
@@ -173,142 +179,15 @@ function meta:think()
 	end
 end
 
-local handlers = {}
-
-handlers["PING"] = function(o, prefix, query)
-	o:send("PONG :%s", query)
-end
-
-handlers["001"] = function(o)
-	o.authed = true
-end
-
-handlers["PRIVMSG"] = function(o, prefix, channel, message)
-	o:invoke("OnChat", parsePrefix(prefix), channel, message)
-end
-
-handlers["NOTICE"] = function(o, prefix, channel, message)
-	o:invoke("OnNotice", parsePrefix(prefix), channel, message)
-end
-
-handlers["JOIN"] = function(o, prefix, channel)
-	local user = parsePrefix(prefix)
-	if o.track_users then
-		if user.nick == o.nick then
-			o.channels[channel] = {users = {}}
-		else
-			o.channels[channel].users[user.nick] = user
-		end
-	end
-
-	o:invoke("OnJoin", user, channel)
-end
-
-handlers["PART"] = function(o, prefix, channel, reason)
-	local user = parsePrefix(prefix)
-	if o.track_users then
-		if user.nick == o.nick then
-			o.channels[channel] = nil
-		else
-			o.channels[channel].users[user.nick] = nil
-		end
-	end
-	o:invoke("OnPart", user, channel, reason)
-end
-
-handlers["QUIT"] = function(o, prefix, msg)
-	local user = parsePrefix(prefix)
-	if o.track_users then
-		for channel, v in pairs(o.channels) do
-			v.users[user.nick] = nil
-		end
-	end
-	o:invoke("OnQuit", user, msg)
-end
-
-handlers["NICK"] = function(o, prefix, newnick)
-	local user = parsePrefix(prefix)
-	if o.track_users then
-		for channel, v in pairs(o.channels) do
-			local users = v.users
-			local oldinfo = users[user.nick]
-			if oldinfo then
-				users[newnick] = oldinfo
-				users[user.nick] = nil
-				o:invoke("NickChange", user, newnick, channel)
-			end
-		end
-	else
-		o:invoke("NickChange", user, newnick)
-	end
-end
-
---NAMES list
-handlers["353"] = function(o, prefix, me, chanType, channel, names)
-	if o.track_users then
-		o.channels[channel] = o.channels[channel] or {users = {}, type = chanType}
-
-		local users = o.channels[channel].users
-		for nick in names:gmatch("(%S+)") do
-			local access, name = parseNick(nick)
-			users[name] = {type = access}
-		end
-	end
-end
-
---end of NAMES
-handlers["366"] = function(o, prefix, me, channel, msg)
-	if o.track_users then
-		o:invoke("NameList", channel, msg)
-	end
-end
-
---no topic
-handlers["331"] = function(o, prefix, me, channel)
-	o:invoke("OnTopic", channel, nil)
-end
-
---new topic
-handlers["TOPIC"] = function(o, prefix, channel, topic)
-	o:invoke("OnTopic", channel, topic)
-end
-
-handlers["332"] = function(o, prefix, me, channel, topic)
-	o:invoke("OnTopic", channel, topic)
-end
-
---topic creation info
-handlers["333"] = function(o, prefix, me, channel, nick, time)
-	o:invoke("OnTopicInfo", channel, nick, tonumber(time))
-end
-
-handlers["KICK"] = function(o, prefix, channel, kicked, reason)
-	o:invoke("OnKick", channel, kicked, parsePrefix(prefix), reason)
-end
-
---RPL_UMODEIS
---To answer a query about a client's own mode, RPL_UMODEIS is sent back
-handlers["221"] = function(o, prefix, modes)
-	o:invoke("OnUserModeIs", modes)
-end
-
---RPL_CHANNELMODEIS
---The result from common irc servers differs from that defined by the rfc
-handlers["324"] = function(o, prefix, user, channel, modes)
-	o:invoke("OnChannelModeIs", user, channel, modes)
-end
-
-handlers["ERROR"] = function(o, prefix, message)
-	o:invoke("OnDisconnect", message, true)
-	o:shutdown()
-	error(message, 3)
-end
+local handlers = handlers
 
 function meta:handle(prefix, cmd, params)
+	local user = parsePrefix(prefix)
 	local handler = handlers[cmd]
 	if handler then
-		return handler(self, prefix, unpack(params))
+		handler(self, user, unpack(params))
 	end
+	self:invoke("Do"..capitalize(cmd), user, unpack(params))
 end
 
 local whoisHandlers = {

set.lua

@@ -0,0 +1,56 @@
+local select = require "socket".select
+
+local setmetatable = setmetatable
+local insert = table.insert
+local remove = table.remove
+local ipairs = ipairs
+local error = error
+
+module "irc.set"
+
+local set = {}
+set.__index = set
+
+function new(t)
+	t.connections = {}
+	t.sockets = {}
+	return setmetatable(t, set)
+end
+
+function set:add(connection)
+	local socket = connection.socket
+	insert(self.sockets, socket)
+	
+	self.connections[socket] = connection
+	insert(self.connections, connection)
+end
+
+function set:remove(connection)
+	local socket = connection.socket
+	self.connections[socket] = nil
+	for k, s in ipairs(self.sockets) do
+		if socket == s then
+			remove(self.sockets, k)
+			remove(self.connections, k)
+			break
+		end
+	end
+end
+
+function set:select()
+	local read, write, err = select(self.sockets, nil, self.timeout)
+	
+	if read then
+		for k, socket in ipairs(read) do
+			read[k] = self.connections[socket]
+		end
+	end
+	
+	return read, err
+end
+
+-- Select - but if it times out, it returns all connections.
+function set:poll()
+	local read, err = self:select()
+	return err == "timeout" and self.connections or read
+end

util.lua

@@ -1,9 +1,12 @@
 local setmetatable = setmetatable
+local sub = string.sub
+local byte = string.byte
 local char = string.char
 local table = table
 local assert = assert
 local tostring = tostring
 local type = type
+local random = math.random
 
 module "irc"
 
@@ -48,17 +51,30 @@ function parse(line)
 end
 
 function parseNick(nick)
-	return nick:match("^([%+@]?)(.+)$")
+	local access, name = nick:match("^([%+@]*)(.+)$")
+	return parseAccess(access or ""), name
 end
 
 function parsePrefix(prefix)
 	local user = {}
 	if prefix then
-		user.access, user.nick, user.username, user.host = prefix:match("^([%+@]?)(.+)!(.+)@(.+)$")
+		user.access, user.nick, user.username, user.host = prefix:match("^([%+@]*)(.+)!(.+)@(.+)$")
 	end
+	user.access = parseAccess(user.access or "")
 	return user
 end
 
+function parseAccess(accessString)
+	local access = {op = false, halfop = false, voice = false}
+	for c in accessString:gmatch(".") do
+		if     c == "@" then access.op = true
+		elseif c == "%" then access.halfop = true
+		elseif c == "+" then access.voice = true
+		end
+	end
+	return access
+end
+
 --mIRC markup scheme (de-facto standard)
 color = {
 	black = 1,
@@ -94,3 +110,33 @@ local underlineByte = char(31)
 function underline(text)
 	return underlineByte..text..underlineByte
 end
+
+function checkNick(nick)
+	return nick:find("^[a-zA-Z_%-%[|%]%^{|}`][a-zA-Z0-9_%-%[|%]%^{|}`]*$") ~= nil
+end
+
+function defaultNickGenerator(nick)
+	-- LuaBot -> LuaCot -> LuaCou -> ...
+	-- We change a random charachter rather than appending to the
+	-- nickname as otherwise the new nick could exceed the ircd's
+	-- maximum nickname length.
+	local randindex = random(1, #nick)
+	local randchar = sub(nick, randindex, randindex)
+	local b = byte(randchar)
+	b = b + 1
+	if b < 65 or b > 125 then
+		b = 65
+	end
+	-- Get the halves before and after the changed character
+	local first = sub(nick, 1, randindex - 1)
+	local last = sub(nick, randindex + 1, #nick)
+	nick = first..char(b)..last  -- Insert the new charachter
+	return nick
+end
+
+function capitalize(text)
+  -- Converts first character to upercase and the rest to lowercase.
+  -- "PING" -> "Ping" | "hello" -> "Hello" | "123" -> "123"
+  return text:sub(1, 1):upper()..text:sub(2):lower()
+end
+