PageRenderTime 136ms CodeModel.GetById 24ms app.highlight 2ms RepoModel.GetById 107ms app.codeStats 0ms

/doc/irc.luadoc

http://github.com/JakobOvrum/LuaIRC
Unknown | 161 lines | 140 code | 21 blank | 0 comment | 0 complexity | c24e041e22e362b6f209e48b15f0c60d MD5 | raw file
  1--- LuaIRC is a low-level IRC library for Lua.
  2-- All functions raise Lua exceptions on error.
  3--
  4-- Use <code>new</code> to create a new IRC object.<br/>
  5-- Example:<br/><br/>
  6--<code>
  7--require "irc"<br/>
  8--local sleep = require "socket".sleep<br/>
  9--<br/>
 10--local s = irc.new{nick = "example"}<br/>
 11--<br/>
 12--s:hook("OnChat", function(user, channel, message)<br/>
 13--    print(("[%s] %s: %s"):format(channel, user.nick, message))<br/>
 14--end)<br/>
 15--<br/>
 16--s:connect("irc.example.net")<br/>
 17--s:join("#example")<br/>
 18--<br/>
 19--while true do<br/>
 20--    s:think()<br/>
 21--    sleep(0.5)<br/>
 22--end<br/>
 23--</code>
 24
 25module "irc"
 26
 27--- Create a new IRC object. Use <code>irc:connect</code> to connect to a server.
 28-- @param user Table with fields <code>nick</code>, <code>username</code> and <code>realname</code>.
 29-- The <code>nick</code> field is required.
 30--
 31-- @return Returns a new <code>irc</code> object.
 32function new(user)
 33
 34--- Hook a function to an event.
 35-- @param name Name of event.
 36-- @param id Unique tag.
 37-- @param f Callback function. [defaults to <code>id</code>]
 38-- @see Hooks
 39function irc:hook(name, id, f)
 40
 41--- Remove previous hooked callback.
 42-- @param name Name of event.
 43-- @param id Unique tag.
 44function irc:unhook(name, id)
 45
 46--- Connect <code>irc</code> to an IRC server.
 47-- @param host Host address.
 48-- @param port Server port. [default 6667]
 49function irc:connect(host, port)
 50
 51-- @param table Table of connection details
 52-- @see Connection
 53function irc:connect(table)
 54
 55--- Disconnect <code>irc</code> from the server.
 56-- @param message Quit message.
 57function irc:disconnect(message)
 58
 59--- Handle incoming data for <code>irc</code>, and invoke previously hooked callbacks based on new server input.
 60-- You should call this in some kind of main loop, or at least often enough to not time out.
 61function irc:think()
 62
 63--- Look up user info.
 64-- @param nick Nick of user to query.
 65-- @return Table with fields <code>userinfo</code>, <code>node</code>, <code>channels</code> and <code>account</code>.
 66function irc:whois(nick)
 67
 68--- Look up topic.
 69-- Use this to invoke the hooks OnTopic and OnTopicInfo at any time.
 70-- @param channel Channel to query.
 71function irc:topic(channel)
 72
 73--- Send a raw line of IRC to the server.
 74-- @param msg Line to be sent, excluding newline characters.
 75-- @param ... Format parameters for <code>msg</code>, with <code>string.format</code> semantics. [optional]
 76function irc:send(msg, ...)
 77
 78--- Send a message to a channel or user.
 79-- @param target Nick or channel to send to.
 80-- @param message Message to send.
 81function irc:sendChat(target, message)
 82
 83--- Send a notice to a channel or user.
 84-- @param target Nick or channel to send to.
 85-- @param message Notice to send.
 86function irc:sendNotice(target, message)
 87
 88--- Join a channel.
 89-- @param channel Channel to join.
 90-- @param key Channel password. [optional]
 91function irc:join(channel, key)
 92
 93--- Leave a channel.
 94-- @param channel Channel to leave.
 95function irc:part(channel)
 96
 97--- Turn user information tracking on or off. User tracking is enabled by default.
 98-- @param b Boolean whether or not to track user information.
 99function irc:trackUsers(b)
100
101--- Add/remove modes for a channel or nick.
102-- @param t Table with fields <code>target, nick, add</code> and/or <code>rem</code>. <code>target</code> or <code>nick</code>
103-- specifies the user or channel to add/remove modes. <code>add</code> is a list of modes to add to the user or channel.
104-- <code>rem</code> is a list of modes to remove from the user or channel.
105-- @usage Example which sets +m (moderated) for #channel: <br/>
106-- <code>irc:setMode{target = "#channel", add = "m"}</code>
107function irc:setMode(t)
108
109--internal
110function irc:invoke(name, ...)
111function irc:handle(prefix, cmd, params)
112function irc:shutdown()
113
114--- Table with connection information.
115-- <ul>
116-- <li><code>host</code> - Server host name.</li>
117-- <li><code>port</code> - Server port. [defaults to <code>6667</code>]</li>
118-- <li><code>timeout</code> - Connect timeout. [defaults to <code>30</code>]</li>
119-- <li><code>password</code> - Server password.</li>
120-- <li><code>secure</code> - Boolean to enable TLS connection, pass a params table (described, [luasec]) to control</li>
121-- </ul>
122-- [luasec]: http://www.inf.puc-rio.br/~brunoos/luasec/reference.html
123-- @name Connection
124-- @class table
125
126--- List of hooks you can use with irc:hook. The parameter list describes the parameters passed to the callback function.
127-- <ul>
128-- <li><code>PreRegister(connection)</code>Useful for CAP commands and SASL.</li>
129-- <li><code>OnRaw(line) - (any non false/nil return value assumes line handled and will not be further processed)</code></li>
130-- <li><code>OnSend(line)</code></li>
131-- <li><code>OnDisconnect(message, errorOccurred)</code></li>
132-- <li><code>OnChat(user, channel, message)</code></li>
133-- <li><code>OnNotice(user, channel, message)</code></li>
134-- <li><code>OnJoin(user, channel)</code>*</li>
135-- <li><code>OnPart(user, channel)</code>*</li>
136-- <li><code>OnQuit(user, message)</code></li>
137-- <li><code>NickChange(user, newnick, channel)</code>*†</li>
138-- <li><code>NameList(channel, names)</code></li>
139-- <li><code>OnTopic(channel, topic)</code></li>
140-- <li><code>OnTopicInfo(channel, creator, timeCreated)</code></li>
141-- <li><code>OnKick(channel, nick, kicker, reason)</code>* (kicker is a <code>user</code> table)</li>
142-- <li><code>OnUserMode(modes)</code></li>
143-- <li><code>OnChannelMode(user, channel, modes)</code></li>
144-- <li><code>OnModeChange(user, target, modes, ...)</code>* ('...' contains mode options such as banmasks)</li>
145-- </ul>
146-- * Event also invoked for yourself.
147-- † Channel passed only when user tracking is enabled
148-- @name Hooks
149-- @class table
150
151--- Table with information about a user.
152-- <ul>
153-- <li><code>nick</code> - User nickname. Always present.</li>
154-- <li><code>username</code> - User username.</li>
155-- <li><code>host</code> - User hostname.</li>
156-- <li><code>realname</code> - User real name.</li>
157-- <li><code>access</code> - User access, available in channel-oriented callbacks. A table containing the boolean fields 'op', 'halfop', and 'voice'.</li>
158-- </ul>
159-- Apart from <code>nick</code>, fields may be missing. To fill them in, enable user tracking and use irc:whois.
160-- @name User
161-- @class table