--- LuaIRC is a low-level IRC library for Lua.
-- All functions raise Lua exceptions on error.
--
-- Use <code>new</code> to create a new IRC object.<br/>
-- Example:<br/><br/>
--<code>
--require "irc"<br/>
--local sleep = require "socket".sleep<br/>
--<br/>
--local s = irc.new{nick = "example"}<br/>
--<br/>
--s:hook("OnChat", function(user, channel, message)<br/>
--    print(("[%s] %s: %s"):format(channel, user.nick, message))<br/>
--end)<br/>
--<br/>
--s:connect("irc.example.net")<br/>
--s:join("#example")<br/>
--<br/>
--while true do<br/>
--    s:think()<br/>
--    sleep(0.5)<br/>
--end<br/>
--</code>

module "irc"

--- Create a new IRC object. Use <code>irc:connect</code> to connect to a server.
-- @param user Table with fields <code>nick</code>, <code>username</code> and <code>realname</code>.
-- The <code>nick</code> field is required.
--
-- @return Returns a new <code>irc</code> 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 <code>id</code>]
-- @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 <code>irc</code> to an IRC server.
-- @param host Host address.
-- @param port Server port. [default 6667]
function irc:connect(server, port)

-- @param table Table of connection details
-- @see Connection
function irc:connect(table)

--- Disconnect <code>irc</code> from the server.
-- @param message Quit message.
function irc:disconnect(message)

--- Handle incoming data for <code>irc</code>, 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 <code>userinfo</code>, <code>node</code>, <code>channels</code> and <code>account</code>.
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 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, ...)

--- Send a message to a channel or user.
-- @param target Nick or channel to send to.
-- @param message Message to send.
function irc:sendChat(target, message)

--- Send a notice to a channel or user.
-- @param target Nick or channel to send to.
-- @param message Notice to send.
function irc:sendNotice(target, message)

--- Join a channel.
-- @param channel Channel to join.
-- @param key Channel password. [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 <code>target, nick, add</code> and/or <code>rem</code>. <code>target</code> or <code>nick</code>
-- specifies the user or channel to add/remove modes. <code>add</code> is a list of modes to add to the user or channel.
-- <code>rem</code> is a list of modes to remove from the user or channel.
-- @usage Example which sets +m (moderated) for #channel: <br/>
-- <code>irc:setMode{target = "#channel", add = "m"}</code>
function irc:setMode(t)

--internal
function irc:invoke(name, ...)
function irc:handle(prefix, cmd, params)
function irc:shutdown()

--- Table with connection information.
-- <ul>
-- <li><code>host</code> - Server host name.</li>
-- <li><code>port</code> - Server port. [defaults to <code>6667</code>]</li>
-- <li><code>timeout</code> - Connect timeout. [defaults to <code>30</code>]</li>
-- <li><code>password</code> - Server password.</li>
-- <li><code>secure</code> - Boolean to enable TLS connection, pass a params table (described, [luasec]) to control</li>
-- </ul>
-- [luasec]: http://www.inf.puc-rio.br/~brunoos/luasec/reference.html
-- @name Connection
-- @class table

--- List of hooks you can use with irc:hook. The parameter list describes the parameters passed to the callback function.
-- <ul>
-- <li><code>OnRaw(line) - (any non false/nil return value assumes line handled and will not be further processed)</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>
-- <li><code>OnJoin(user, channel)</code>*</li>
-- <li><code>OnPart(user, channel)</code>*</li>
-- <li><code>OnQuit(user, message)</code></li>
-- <li><code>NickChange(user, newnick, channel)</code>*†</li>
-- <li><code>NameList(channel, names)</code></li>
-- <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>OnModeChange(user, target, modes)</code>*</li>
-- </ul>
-- * Event also invoked for yourself.
-- † Channel passed only when user tracking is enabled
-- @name Hooks
-- @class table

--- Table with information about a user.
-- <ul>
-- <li><code>nick</code> - User nickname. Always present.</li>
-- <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>
-- </ul>
-- Apart from <code>nick</code>, fields may be missing. To fill them in, enable user tracking and use irc:whois.
-- @name User
-- @class table