+---
+-- Implementation of the main LuaIRC module
+
-- initialization {{{
local base = _G
local constants = require 'irc.constants'
local table = require 'table'
-- }}}
+---
+-- LuaIRC - IRC framework written in Lua
+-- @release 0.02
module 'irc'
-- constants {{{
-- public functions {{{
-- server commands {{{
--- connect() - start a connection to the irc server {{{
--- args: network - address of the irc network to connect to
--- port - port to connect to
--- pass - irc server password (if required)
--- nick - nickname to connect as
--- username - username to connect with
--- realname - realname to connect with
--- timeout - amount of time in seconds to wait before dropping an idle
--- connection
--- notes: this function uses a table and named arguments. defaults are specified
--- by the capitalized versions of the arguments at the top of this file.
--- all args are optional.
+-- connect {{{
+---
+-- Start a connection to the irc server.
+-- @param args Table of named arguments containing connection parameters.
+-- Defaults are the all-caps versions of these parameters given
+-- at the top of the file, and are overridable by setting them
+-- as well, i.e. <pre>irc.NETWORK = irc.freenode.net</pre>
+-- Possible options are:
+-- <ul>
+-- <li><i>network:</i> address of the irc network to connect to
+-- (default: 'localhost')</li>
+-- <li><i>port:</i> port to connect to
+-- (default: '6667')</li>
+-- <li><i>pass:</i> irc server password
+-- (default: don't send)</li>
+-- <li><i>nick:</i> nickname to connect as
+-- (default: 'luabot')</li>
+-- <li><i>username:</i> username to connect with
+-- (default: 'LuaIRC')</li>
+-- <li><i>realname:</i> realname to connect with
+-- (default: 'LuaIRC')</li>
+-- <li><i>timeout:</i> amount of time in seconds to wait before
+-- dropping an idle connection
+-- (default: '60')</li>
+-- </ul>
function connect(args)
local network = args.network or NETWORK
local port = args.port or PORT
end
-- }}}
--- quit() - close the connection to the irc server {{{
--- args: message - quit message (optional)
+-- quit {{{
+---
+-- Close the connection to the irc server.
+-- @param message Quit message (optional, defaults to 'Leaving')
function quit(message)
message = message or "Leaving"
send("QUIT", message)
end
-- }}}
--- join() - join a channel {{{
--- args: channel - channel to join (required)
+-- join {{{
+---
+-- Join a channel.
+-- @param channel Channel to join
function join(channel)
if not channel then return end
serverinfo.channels[channel] = Channel.new(channel)
end
-- }}}
--- part() - leave a channel {{{
--- args: channel - channel to leave (required)
+-- part {{{
+---
+-- Leave a channel.
+-- @param channel Channel to leave
function part(channel)
if not channel then return end
serverinfo.channels[channel] = nil
end
-- }}}
--- say() - send a message to a user or channel {{{
--- args: name - user or channel to send the message to
--- message - message to send
+-- say {{{
+---
+-- Send a message to a user or channel.
+-- @param name User or channel to send the message to
+-- @param message Message to send
function say(name, message)
if not name then return end
message = message or ""
end
-- }}}
--- notice() - send a notice to a user or channel {{{
--- args: name - user or channel to send the notice to
--- message - message to send
+-- notice {{{
+---
+-- Send a notice to a user or channel.
+-- @param name User or channel to send the notice to
+-- @param message Message to send
function notice(name, message)
if not name then return end
message = message or ""
end
-- }}}
--- act() - perform a /me action {{{
--- args: name - user or channel to send the action to
--- action - action to send
+-- act {{{
+---
+-- Perform a /me action.
+-- @param name User or channel to send the action to
+-- @param action Action to send
function act(name, action)
if not name then return end
action = action or ""
-- information requests {{{
-- server_version {{{
-function server_version(cb, server)
- -- apparently the optional server parameter isn't supported?
- --server = server or serverinfo.host
- server = serverinfo.host
+---
+-- Request the version of the IRC server you are currently connected to.
+-- @param cb Callback to call when the information is available. The single
+-- table parameter to this callback will contain the fields:
+-- <ul>
+-- <li><i>server:</i> the server which responded to the request</li>
+-- <li><i>version:</i> the server version</li>
+-- <li><i>comments:</i> other data provided by the server</li>
+-- </ul>
+function server_version(cb)
+ -- apparently the optional server parameter isn't supported for servers
+ -- which you are not directly connected to (freenode specific?)
+ local server = serverinfo.host
if not icallbacks.serverversion[server] then
icallbacks.serverversion[server] = {cb}
send("VERSION", server)
-- whois {{{
-- TODO: allow server parameter (to get user idle time)
+---
+-- Request WHOIS information about a given user.
+-- @param cb Callback to call when the information is available. The single
+-- table parameter to this callback may contain any or all of the
+-- fields:
+-- <ul>
+-- <li><i>nick:</i> the nick that was passed to this function
+-- (this field will always be here)</li>
+-- <li><i>user:</i> the IRC username of the user</li>
+-- <li><i>host:</i> the user's hostname</li>
+-- <li><i>realname:</i> the IRC realname of the user</li>
+-- <li><i>server:</i> the IRC server the user is connected to</li>
+-- <li><i>serverinfo:</i> arbitrary information about the above
+-- server</li>
+-- <li><i>awaymsg:</i> set to the user's away message if they are
+-- away</li>
+-- <li><i>is_oper:</i> true if the user is an IRCop</li>
+-- <li><i>idle_time:</i> amount of time the user has been idle</li>
+-- <li><i>channels:</i> array containing the channels the user has
+-- joined</li>
+-- </ul>
+-- @param nick User to request WHOIS information about
function whois(cb, nick)
nick = nick:lower()
requestinfo.whois[nick] = {nick = nick}
-- }}}
-- server_time {{{
-function server_time(cb, server)
- -- apparently the optional server parameter isn't supported?
- --server = server or serverinfo.host
- server = serverinfo.host
+---
+-- Request the current time of the server you are connected to.
+-- @param cb Callback to call when the information is available. The single
+-- table parameter to this callback will contain the fields:
+-- <ul>
+-- <li><i>server:</i> the server which responded to the request</li>
+-- <li><i>time:</i> the time reported by the server</li>
+-- </ul>
+function server_time(cb)
+ -- apparently the optional server parameter isn't supported for servers
+ -- which you are not directly connected to (freenode specific?)
+ local server = serverinfo.host
if not icallbacks.servertime[server] then
icallbacks.servertime[server] = {cb}
send("TIME", server)
end
end
-- }}}
-
--- trace {{{
---function trace(cb, server)
--- send("WHOWAS", "ekiM")
---end
--- }}}
-- }}}
-- ctcp commands {{{
projects / luairc.git / blobdiff