Mercurial > irccd

comparison man/irccd-api.3 @ 932:0e11221c9bcc

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
man: split irccd-api into individual ones
author David Demelier <markand@malikania.fr>
date Tue, 05 Jan 2021 22:25:47 +0100
parents man/irccd-api.7@5e25439fe98d
children ec5461750efd
comparison
equal deleted inserted replaced
931:c78ad0799e68 932:0e11221c9bcc
1 .\"
2 .\" Copyright (c) 2013-2020 David Demelier <markand@malikania.fr>
3 .\"
4 .\" Permission to use, copy, modify, and/or distribute this software for any
5 .\" purpose with or without fee is hereby granted, provided that the above
6 .\" copyright notice and this permission notice appear in all copies.
7 .\"
8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15 .\"
16 .Dd @IRCCD_MAN_DATE@
17 .Dt IRCCD-API 7
18 .Os
19 .\" NAME
20 .Sh NAME
21 .Nm irccd-api
22 .Nd irccd Javascript API
23 .\" SYNOPSIS
24 .Sh SYNOPSIS
25 .Ss Modules
26 .Vt Irccd
27 .Vt Irccd.Chrono
28 .Vt Irccd.Directory
29 .Vt Irccd.File
30 .Vt Irccd.Logger
31 .Vt Irccd.Plugin
32 .Vt Irccd.Server
33 .Vt Irccd.System
34 .Vt Irccd.Timer
35 .Vt Irccd.Unicode
36 .Vt Irccd.Util
37 .Ss Events
38 .Fn onCommand "server, origin, channel, message"
39 .Fn onConnect "server"
40 .Fn onDisonnect "server"
41 .Fn onInvite "server, origin, channel"
42 .Fn onJoin "server, origin, channel"
43 .Fn onKick "server, origin, channel, target, reason"
44 .Fn onLoad "
45 .Fn onMe "server, origin, channel, message"
46 .Fn onMessage "server, origin, channel, message"
47 .Fn onMode "server, origin, channel, mode, limit, user, mask"
48 .Fn onNames "server, channel, list"
49 .Fn onNick "server, origin, nickname"
50 .Fn onNotice "server, origin, notice"
51 .Fn onPart "server, origin, channel, reason"
52 .Fn onReload "
53 .Fn onTopic "server, origin, channel, topic"
54 .Fn onUnload "
55 .Fn onWhois "server, info"
56 .El
57 .\" DESCRIPTION
58 .Sh DESCRIPTION
59 This documentation shows the API reference for the official irccd Javascript
60 API.
61 .Pp
62 Any function that is indicated as
63 .Em optional
64 in square brackets means it may not exist on your platform. A quick check in
65 Javascript will let you test its presence.
66 .\" EVENTS
67 .Sh EVENTS
68 The following is a list of events that Javascript plugins support. All functions
69 are completely optional and may be omitted. If you want to support a function
70 just implement it as global Javascript function.
71 .\" onCommand
72 .Ss onCommand
73 Special commands are not real IRC events. They are called from channel messages
74 with a specific syntax using a delimiter and the plugin name.
75 .Pp
76 For instance, with default irccd parameters, saying on a channel
77 .Ar "!ask foo"
78 will call the special command of the plugin named
79 .Nm ask .
80 .Pp
81 Arguments
82 .Bl -tag -width 20n -compact -offset Ds
83 .It Fa server No (Server)
84 The current server.
85 .It Fa origin No (string)
86 Who invoked the command.
87 .It Fa channel No (string)
88 The channel where the message comes from.
89 .It Fa message No (string)
90 The real message, without the ! part.
91 .El
92 .\" onConnect
93 .Ss onConnect
94 This callback is called when the irccd instance successfully connect to a
95 server.
96 .Pp
97 Arguments
98 .Bl -tag -width 20n -compact -offset Ds
99 .It Fa server No (Server)
100 The current server.
101 .El
102 .\" onDisconnect
103 .Ss onDisconnect
104 This callback is called when a server has been disconnected by any way.
105 .Pp
106 Arguments
107 .Bl -tag -width 20n -compact -offset Ds
108 .It Fa server No (Server)
109 The current server.
110 .El
111 .\" onInvite
112 .Ss onInvite
113 This event is called when someone is inviting you to a channel.
114 .Pp
115 Arguments
116 .Bl -tag -width 20n -compact -offset Ds
117 .It Fa server No (Server)
118 The current server.
119 .It Fa origin No (string)
120 Who invited you.
121 .It Fa channel No (string)
122 On which channel you are invited to.
123 .El
124 .\" onJoin
125 .Ss onJoin
126 User join events, this function is called when someone joins a channel.
127 .Pp
128 Arguments
129 .Bl -tag -width 20n -compact -offset Ds
130 .It Fa server No (Server)
131 The current server.
132 .It Fa origin No (string)
133 The person who joined the channel.
134 .It Fa channel No (string)
135 The channel the user has joined.
136 .El
137 .\" onKick
138 .Ss onKick
139 This event is triggered when someone has been kicked from a channel.
140 .Pp
141 Arguments
142 .Bl -tag -width 20n -compact -offset Ds
143 .It Fa server No (Server)
144 The current server.
145 .It Fa origin No (string)
146 Who kicked the person.
147 .It Fa channel No (string)
148 The channel.
149 .It Fa target No (string)
150 The kicked person.
151 .It Fa reason No (string)
152 An optional reason.
153 .El
154 .\" onLoad
155 .Ss onLoad
156 This function is called when irccd instance load a plugin. If this function
157 throws an error, the script is not loaded.
158 .\" onMe
159 .Ss onMe
160 Action emote.
161 .Pp
162 Arguments
163 .Bl -tag -width 20n -compact -offset Ds
164 .It Fa server No (Server)
165 The current server.
166 .It Fa origin No (string)
167 The person who said something.
168 .It Fa channel No (string)
169 The channel.
170 .It Fa message No (string)
171 The message sent.
172 .El
173 .\" onMessage
174 .Ss onMessage
175 This event is triggered when someone said something on a specific channel.
176 .Pp
177 Arguments
178 .Bl -tag -width 20n -compact -offset Ds
179 .It Fa server No (Server)
180 The current server.
181 .It Fa origin No (string)
182 The person who said something.
183 .It Fa channel No (string)
184 The channel.
185 .It Fa message No (string)
186 The message sent.
187 .El
188 .\" onMode
189 .Ss onMode
190 This event is triggered when the server changed a channel mode or your mode.
191 .Pp
192 Arguments
193 .Bl -tag -width 20n -compact -offset Ds
194 .It Fa server No (Server)
195 The current server.
196 .It Fa origin No (string)
197 The person who changed the mode.
198 .It Fa mode No (string)
199 The new mode.
200 .El
201 .\" onNames
202 .Ss onNames
203 This event is triggered when a list of names has come.
204 .Pp
205 Arguments
206 .Bl -tag -width 20n -compact -offset Ds
207 .It Fa server No (Server)
208 The current server.
209 .It Fa channel No (string)
210 Which channel.
211 .It Fa list No (string)
212 A sequence with all users.
213 .El
214 .\" onNick
215 .Ss onNick
216 This event is triggered when someone changed its nickname.
217 .Pp
218 Arguments
219 .Bl -tag -width 20n -compact -offset Ds
220 .It Fa server No (Server)
221 The current server.
222 .It Fa origin No (string)
223 The old nickname.
224 .It Fa nickname No (string)
225 The new nickname.
226 .El
227 .\" onNotice
228 .Ss onNotice
229 This event is triggered when someone sent a notice to you.
230 .Pp
231 Arguments
232 .Bl -tag -width 20n -compact -offset Ds
233 .It Fa server No (Server)
234 The current server.
235 .It Fa origin No (string)
236 The one who sent the notice.
237 .It Fa message No (string)
238 The notice message.
239 .El
240 .\" onPart
241 .Ss onPart
242 This event is triggered when someone has left a specific channel.
243 .Pp
244 Arguments
245 .Bl -tag -width 20n -compact -offset Ds
246 .It Fa server No (Server)
247 The current server.
248 .It Fa origin No (string)
249 The person who left the channel.
250 .It Fa channel No (string)
251 The channel.
252 .It Fa reason No (string)
253 An optional reason.
254 .El
255 .\" onReload
256 .Ss onReload
257 Request to reload the plugin.
258 .Pp
259 This function does nothing in the irccd internals, it just calls a function that
260 you can use to reload some data.
261 .\" onTopic
262 .Ss onTopic
263 This event is triggered when someone changed the channel's topic.
264 .Pp
265 Arguments
266 .Bl -tag -width 20n -compact -offset Ds
267 .It Fa server No (Server)
268 The current server.
269 .It Fa origin No (string)
270 The person who changed the topic.
271 .It Fa channel No (string)
272 The channel.
273 .It Fa topic No (string)
274 The new topic (may be empty).
275 .El
276 .\" onUnload
277 .Ss onUnload
278 This event is triggered when the plugin is about to be unloaded.
279 .\" onWhois
280 .Ss onWhois
281 This event is triggered when irccd gets information about a user.
282 .Pp
283 Arguments
284 .Bl -tag -width 20n -compact -offset Ds
285 .It Fa server No (Server)
286 The current server.
287 .It Fa info No (Object)
288 The whois information.
289 .El
290 .Pp
291 The
292 .Fa info
293 is an object with the following properties:
294 .Bl -tag -width 20n -compact -offset Ds
295 .It Fa nickname No (string)
296 The user nickname.
297 .It Fa user No (string)
298 The user name.
299 .It Fa host No (string)
300 The hostname.
301 .It Fa realname No (string)
302 The real name used.
303 .It Fa channels No (array)
304 An optional list of channels joined.
305 .El
306 .\" MODULES
307 .Sh MODULES
308 The following modules are part of the official Javascript API. They are all
309 accessible as global function, variables and objects.
310 .Pp
311 All modules are categorized into pseudo namespaces that are placed into the
312 global
313 .Va Irccd
314 object. (e.g.
315 .Va Irccd.Directory , Irccd.File ) .
316 See dedicated manual pages for information of all submodules.
317 .\" CONSTANTS
318 .Sh CONSTANTS
319 .\" Constants
320 The following constants properties are defined:
321 .Pp
322 .Bl -tag
323 .It Va Irccd.version No (object)
324 See below.
325 .It Va Irccd.version.major No (int)
326 The major irccd version.
327 .It Va Irccd.version.minor No (int)
328 The minor irccd version.
329 .It Va Irccd.version.patch No (int)
330 The patch irccd version.
331 .El
332 .Pp
333 .\" EXCEPTIONS
334 .Sh EXCEPTIONS
335 The following exceptions are defined:
336 .Bl -tag
337 .It Va Irccd.SystemError
338 An exception inheriting Error thrown by some filesystem functions.
339 .It Va Irccd.ServerError
340 Thrown from Irccd.Server module.
341 .It Va Irccd.PluginError
342 Throw from Irccd.Plugin module.
343 .El
344 .\" SEE ALSO
345 .Sh SEE ALSO
346 .Xr irccd 1
347 .Xr irccd-api-chrono 3 ,
348 .Xr irccd-api-directory 3 ,
349 .Xr irccd-api-file 3 ,
350 .Xr irccd-api-logger 3 ,
351 .Xr irccd-api-plugin 3 ,
352 .Xr irccd-api-server 3 ,
353 .Xr irccd-api-system 3 ,
354 .Xr irccd-api-timer 3 ,
355 .Xr irccd-api-unicode 3 ,
356 .Xr irccd-api-util 3