From 5ac786e883ab761121f5fb20279345fb17a1e687 Mon Sep 17 00:00:00 2001 From: Jakob Ovrum Date: Tue, 15 Jun 2010 16:48:19 +0900 Subject: [PATCH] Updated documentation --- doc/irc.luadoc | 145 +++++++++++++++++++++++++-------------- doc/modules/irc.html | 160 +++++++++++++++++++++++++++++-------------- 2 files changed, 200 insertions(+), 105 deletions(-) diff --git a/doc/irc.luadoc b/doc/irc.luadoc index 97abe09..2680634 100644 --- a/doc/irc.luadoc +++ b/doc/irc.luadoc @@ -24,67 +24,108 @@ module "irc" ---- Create a new IRC object. --- The user parameter can contain fields nick, username and realname. +--- 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. --- Returns a new irc object. +-- +-- @return Returns a new irc object. function new(user) ---- Hooks function f to event name, with the unique tag id. --- If parameter f is absent, id is assumed to be both the callback function and unique tag. +--- 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) ---- Removes previous hooked callback with the tag id from event name. +--- 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 server Server address. +-- @param port Server port. [default 6667] +-- @param timeout Connection timeout value in seconds. [default 30] +function irc:connect(server, port, timeout) + +--- 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) + +--- Send a raw line of IRC to the server. +-- @param fmt Line to be sent, excluding newline characters. +-- @param ... Format parameters for fmt, with string.format 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 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, ...) - ---- Connects irc to server:port, with the connection timeout value timeout. -function irc:connect(server, port, timeout) - ---- Disconnects irc from the server, with the quit message message. -function irc:disconnect(message) - ---internal +function irc:handle(prefix, cmd, params) function irc:shutdown() ---- Handles incoming data for irc, and invokes previously hooked callbacks based on the new server input. --- You should call this in some kind of main loop, or at least often enough not to time out. -function irc:think() +--- List of hooks you can use with irc:hook. The parameter list describes the parameters passed to the callback function. +-- +-- * Event also invoked for yourself. +-- @name Hooks +-- @class table ---internal -function irc:handle(prefix, cmd, params) - ---- Sends a WHOIS lookup request for nick. --- Returns a table with the fields userinfo, node, channels and account. -function irc:whois(nick) - ---- Sends a raw line of IRC to the server. --- fmt is the line to be sent, without the newline characters. --- fmt can be a format string taking the parameters ..., with string.format semantics. -function irc:send(fmt, ...) - ---- Sends the message msg to target. --- target should be either a channel or nick. -function irc:sendChat(target, msg) - ---- Sends the notice msg to target. --- target should be either a channel or nick. -function irc:sendNotice(target, msg) - ---- Joins channel, optionally with the channel password key. -function irc:join(channel, key) - ---- Leaves channel. -function irc:part(channel) - ---- Specifies whether to cache user information or not with the boolean b. -function irc:trackUsers(b) - ---- Adds and/or removes modes for a channel or nick. --- Either t.target or t.nick specifies the channel or nick to add/remove modes. --- t.add is a list of modes to add to the target. --- t.rem is a list of modes to remove from the target. --- Example which sets +m (moderated) for #channel: irc:setMode{target = "#channel", add = "m"} -function irc:setMode(t) +--- Table with information about a user. +-- +-- Apart from nick, fields may be missing. To fill them in, enable user tracking and use irc:whois. +-- @name User +-- @class table diff --git a/doc/modules/irc.html b/doc/modules/irc.html index 3a12f4f..90a8104 100644 --- a/doc/modules/irc.html +++ b/doc/modules/irc.html @@ -64,67 +64,67 @@ irc:connect (server, port, timeout) - Connects irc to server:port, with the connection timeout value timeout. + Connect irc to an IRC server. irc:disconnect (message) - Disconnects irc from the server, with the quit message message. + Disconnect irc from the server. irc:hook (name, id, f) - Hooks function f to event name, with the unique tag id. + Hook a function to an event. irc:join (channel, key) - Joins channel, optionally with the channel password key. + Join a channel. irc:part (channel) - Leaves channel. + Leave a channel. irc:send (fmt, ...) - Sends a raw line of IRC to the server. + Send a raw line of IRC to the server. - irc:sendChat (target, msg) - Sends the message msg to target. + irc:sendChat (target, message) + Send a message to a channel or user. - irc:sendNotice (target, msg) - Sends the notice msg to target. + irc:sendNotice (target, message) + Send a notice to a channel or user. irc:setMode (t) - Adds and/or removes modes for a channel or nick. + Add/remove modes for a channel or nick. irc:think () - Handles incoming data for irc, and invokes previously hooked callbacks based on the new server input. + Handle incoming data for irc, and invoke previously hooked callbacks based on new server input. irc:trackUsers (b) - Specifies whether to cache user information or not with the boolean b. + Turn user information tracking on or off. irc:unhook (name, id) - Removes previous hooked callback with the tag id from event name. + Remove previous hooked callback. irc:whois (nick) - Sends a WHOIS lookup request for nick. + Look up user info. @@ -137,6 +137,21 @@ +

Tables

+ + + + + + + + + + + + +
HooksList of hooks you can use with irc:hook.
UserTable with information about a user.
+
@@ -151,22 +166,22 @@
irc:connect (server, port, timeout)
-Connects irc to server:port, with the connection timeout value timeout. +Connect irc to an IRC server.

Parameters

@@ -185,14 +200,14 @@ Connects irc to server:port, with the connection timeo
irc:disconnect (message)
-Disconnects irc from the server, with the quit message message. +Disconnect irc from the server.

Parameters

@@ -211,22 +226,22 @@ Disconnects irc from the server, with the quit message messag
irc:hook (name, id, f)
-Hooks function f to event name, with the unique tag id. If parameter f is absent, id is assumed to be both the callback function and unique tag. +Hook a function to an event.

Parameters

  • - name: + name: Name of event.
  • - id: + id: Unique tag.
  • - f: + f: Callback function. [defaults to id]
@@ -238,6 +253,15 @@ Hooks function f to event name, with the unique tag See also: + +
@@ -245,18 +269,18 @@ Hooks function f to event name, with the unique tag irc:join (channel, key)
-Joins channel, optionally with the channel password key. +Join a channel.

Parameters

  • - channel: + channel: Channel to join.
  • - key: + key: Channel password. [optional]
@@ -275,14 +299,14 @@ Joins channel, optionally with the channel password keyirc:part (channel)
-Leaves channel. +Leave a channel.

Parameters

  • - channel: + channel: Channel to leave.
@@ -301,18 +325,18 @@ Leaves channel.
irc:send (fmt, ...)
-Sends a raw line of IRC to the server. fmt is the line to be sent, without the newline characters. fmt can be a format string taking the parameters ..., with string.format semantics. +Send a raw line of IRC to the server.

Parameters

  • - fmt: + fmt: Line to be sent, excluding newline characters.
  • - ...: + ...: Format parameters for fmt, with string.format semantics.
@@ -329,20 +353,20 @@ Sends a raw line of IRC to the server. fmt is the line to be sent, -
irc:sendChat (target, msg)
+
irc:sendChat (target, message)
-Sends the message msg to target. target should be either a channel or nick. +Send a message to a channel or user.

Parameters

  • - target: + target: Nick or channel to send to.
  • - msg: + message: Message to send.
@@ -359,20 +383,20 @@ Sends the message msg to target. target s -
irc:sendNotice (target, msg)
+
irc:sendNotice (target, message)
-Sends the notice msg to target. target should be either a channel or nick. +Send a notice to a channel or user.

Parameters

  • - target: + target: Nick or channel to send to.
  • - msg: + message: Notice to send.
@@ -391,14 +415,14 @@ Sends the notice msg to target. target sh
irc:setMode (t)
-Adds and/or removes modes for a channel or nick. Either t.target or t.nick specifies the channel or nick to add/remove modes. t.add is a list of modes to add to the target. t.rem is a list of modes to remove from the target. Example which sets +m (moderated) for #channel: irc:setMode{target = "#channel", add = "m"} +Add/remove modes for a channel or nick.

Parameters

  • - t: + 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.
@@ -406,6 +430,9 @@ Adds and/or removes modes for a channel or nick. Either t.target or +

Usage:

+Example which sets +m (moderated) for #channel:
irc:setMode{target = "#channel", add = "m"} + @@ -417,7 +444,7 @@ Adds and/or removes modes for a channel or nick. Either t.target or
irc:think ()
-Handles incoming data for irc, and invokes previously hooked callbacks based on the new server input. You should call this in some kind of main loop, or at least often enough not to time out. +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. @@ -434,14 +461,14 @@ Handles incoming data for irc, and invokes previously hooked callba
irc:trackUsers (b)
-Specifies whether to cache user information or not with the boolean b. +Turn user information tracking on or off. User tracking is enabled by default.

Parameters

  • - b: + b: Boolean whether or not to track user information.
@@ -460,18 +487,18 @@ Specifies whether to cache user information or not with the boolean birc:unhook (name, id)
-Removes previous hooked callback with the tag id from event name. +Remove previous hooked callback.

Parameters

  • - name: + name: Name of event.
  • - id: + id: Unique tag.
@@ -490,14 +517,14 @@ Removes previous hooked callback with the tag id from event n
irc:whois (nick)
-Sends a WHOIS lookup request for nick. Returns a table with the fields userinfo, node, channels and account. +Look up user info.

Parameters

  • - nick: + nick: Nick of user to query.
@@ -507,6 +534,9 @@ Sends a WHOIS lookup request for nick. Returns a table with the fie +

Return value:

+Table with fields userinfo, node, channels and account. +
@@ -516,14 +546,14 @@ Sends a WHOIS lookup request for nick. Returns a table with the fie
new (user)
-Create a new IRC object. The user parameter can contain fields nick, username and realname. The nick field is required. Returns a new irc object. +Create a new IRC object. Use irc:connect to connect to a server.

Parameters

  • - user: + user: Table with fields nick, username and realname. The nick field is required.
@@ -533,6 +563,9 @@ Create a new IRC object. The user parameter can contain fields Return value: +Returns a new irc object. +
@@ -543,6 +576,27 @@ Create a new IRC object. The user parameter can contain fields Tables +
+ +
Hooks
+
List of hooks you can use with irc:hook. The parameter list describes the parameters passed to the callback function.
  • OnDisconnect(message, errorOccurred)
  • OnChat(user, channel, message)
  • OnNotice(user, channel, message)
  • OnJoin(user, channel)*
  • OnPart(user, channel)*
  • OnQuit(user, message)
  • NickChange(user, newnick)*
  • NameList(channel, names)
* Event also invoked for yourself. + + + +
+ + +
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. Can be '+', '@', and others, depending on the server.
Apart from nick, fields may be missing. To fill them in, enable user tracking and use irc:whois. + + + +
+ + +
+