Mercurial > irccd

comparison man/irccd-api.7 @ 845:00a4720c4874

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: rewrite documentation in manual pages, closes #1674 Get rid of markdown documentation and the custom generator tools, instead use raw manual pages.
author David Demelier <markand@malikania.fr>
date Mon, 08 Jul 2019 16:15:57 +0200
parents
children a23b7b574ed2
comparison
equal deleted inserted replaced
844:dc6b42d7b97a 845:00a4720c4874
1 .\"
2 .\" Copyright (c) 2013-2019 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 .\" DESCRIPTION
24 .Sh DESCRIPTION
25 This documentation shows the API reference for the official irccd Javascript
26 API.
27 .Pp
28 Any function that is indicated as
29 .Em optional
30 in square brackets means it may not exist on your platform. A quick check in
31 Javascript will let you test its presence.
32 .\" EVENTS
33 .Sh EVENTS
34 The following is a list of events that Javascript plugins support. All functions
35 are completely optional and may be omitted. If you want to support a function
36 just implement it as global Javascript function.
37 .\" onCommand
38 .Ss onCommand
39 Special commands are not real IRC events. They are called from channel messages
40 with a specific syntax using a delimiter and the plugin name.
41 .Pp
42 For instance, with default irccd parameters, saying on a channel
43 .Ar "!ask foo"
44 will call the special command of the plugin named
45 .Nm ask .
46 .Pp
47 Synopsis
48 .Bd -literal -offset Ds
49 function onCommand(server, origin, channel, message)
50 .Ed
51 .Pp
52 Arguments
53 .Bl -tag -width 20n -compact -offset Ds
54 .It Fa server No (Server)
55 The current server.
56 .It Fa origin No (string)
57 Who invoked the command.
58 .It Fa channel No (string)
59 The channel where the message comes from.
60 .It Fa message No (string)
61 The real message, without the ! part.
62 .El
63 .\" onConnect
64 .Ss onConnect
65 This callback is called when the irccd instance successfully connect to a
66 server.
67 .Pp
68 Synopsis
69 .Bd -literal -offset Ds
70 function onConnect(server)
71 .Ed
72 .Pp
73 Arguments
74 .Bl -tag -width 20n -compact -offset Ds
75 .It Fa server No (Server)
76 The current server.
77 .El
78 .\" onDisconnect
79 .Ss onDisconnect
80 This callback is called when a server has been disconnected by any way.
81 .Pp
82 Synopsis
83 .Bd -literal -offset Ds
84 function onDisonnect(server)
85 .Ed
86 .Pp
87 Arguments
88 .Bl -tag -width 20n -compact -offset Ds
89 .It Fa server No (Server)
90 The current server.
91 .El
92 .\" onInvite
93 .Ss onInvite
94 This event is called when someone is inviting you to a channel.
95 .Pp
96 Synopsis
97 .Bd -literal -offset Ds
98 function onInvite(server, origin, channel)
99 .Ed
100 .Pp
101 Arguments
102 .Bl -tag -width 20n -compact -offset Ds
103 .It Fa server No (Server)
104 The current server.
105 .It Fa origin No (string)
106 Who invited you.
107 .It Fa channel No (string)
108 On which channel you are invited to.
109 .El
110 .\" onJoin
111 .Ss onJoin
112 User join events, this function is called when someone joins a channel.
113 .Pp
114 Synopsis
115 .Bd -literal -offset Ds
116 function onJoin(server, origin, channel)
117 .Ed
118 .Pp
119 Arguments
120 .Bl -tag -width 20n -compact -offset Ds
121 .It Fa server No (Server)
122 The current server.
123 .It Fa origin No (string)
124 The person who joined the channel.
125 .It Fa channel No (string)
126 The channel the user has joined.
127 .El
128 .\" onKick
129 .Ss onKick
130 This event is triggered when someone has been kicked from a channel.
131 .Pp
132 Synopsis
133 .Bd -literal -offset Ds
134 function onKick(server, origin, channel, target, reason)
135 .Ed
136 .Pp
137 Arguments
138 .Bl -tag -width 20n -compact -offset Ds
139 .It Fa server No (Server)
140 The current server.
141 .It Fa origin No (string)
142 Who kicked the person.
143 .It Fa channel No (string)
144 The channel.
145 .It Fa target No (string)
146 The kicked person.
147 .It Fa reason No (string)
148 An optional reason.
149 .El
150 .\" onLoad
151 .Ss onLoad
152 This function is called when irccd instance load a plugin. If this function
153 throws an error, the script is not loaded.
154 .Pp
155 Synopsis
156 .Bd -literal -offset Ds
157 function onLoad()
158 .Ed
159 .\" onMe
160 .Ss onMe
161 Action emote.
162 .Pp
163 Synopsis
164 .Bd -literal -offset Ds
165 function onMe(server, origin, channel, message)
166 .Ed
167 .Pp
168 Arguments
169 .Bl -tag -width 20n -compact -offset Ds
170 .It Fa server No (Server)
171 The current server.
172 .It Fa origin No (string)
173 The person who said something.
174 .It Fa channel No (string)
175 The channel.
176 .It Fa message No (string)
177 The message sent.
178 .El
179 .\" onMessage
180 .Ss onMessage
181 This event is triggered when someone said something on a specific channel.
182 .Pp
183 Synopsis
184 .Bd -literal -offset Ds
185 function onMessage(server, origin, channel, message)
186 .Ed
187 .Pp
188 Arguments
189 .Bl -tag -width 20n -compact -offset Ds
190 .It Fa server No (Server)
191 The current server.
192 .It Fa origin No (string)
193 The person who said something.
194 .It Fa channel No (string)
195 The channel.
196 .It Fa message No (string)
197 The message sent.
198 .El
199 .\" onMode
200 .Ss onMode
201 This event is triggered when the server changed a channel mode or your mode.
202 .Pp
203 Synopsis
204 .Bd -literal -offset Ds
205 function onMode(server, origin, channel, mode, limit, user, mask)
206 .Ed
207 .Pp
208 Arguments
209 .Bl -tag -width 20n -compact -offset Ds
210 .It Fa server No (Server)
211 The current server.
212 .It Fa origin No (string)
213 The person who changed the mode.
214 .It Fa mode No (string)
215 The new mode.
216 .El
217 .\" onNames
218 .Ss onNames
219 This event is triggered when a list of names has come.
220 .Pp
221 Synopsis
222 .Bd -literal -offset Ds
223 function onNames(server, channel, list)
224 .Ed
225 .Pp
226 Arguments
227 .Bl -tag -width 20n -compact -offset Ds
228 .It Fa server No (Server)
229 The current server.
230 .It Fa channel No (string)
231 Which channel.
232 .It Fa list No (string)
233 A sequence with all users.
234 .El
235 .\" onNick
236 .Ss onNick
237 This event is triggered when someone changed its nickname.
238 .Pp
239 Synopsis
240 .Bd -literal -offset Ds
241 function onNick(server, origin, nickname)
242 .Ed
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 old nickname.
250 .It Fa nickname No (string)
251 The new nickname.
252 .El
253 .\" onNotice
254 .Ss onNotice
255 This event is triggered when someone sent a notice to you.
256 .Pp
257 Synopsis
258 .Bd -literal -offset Ds
259 function onNotice(server, origin, notice)
260 .Ed
261 .Pp
262 Arguments
263 .Bl -tag -width 20n -compact -offset Ds
264 .It Fa server No (Server)
265 The current server.
266 .It Fa origin No (string)
267 The one who sent the notice.
268 .It Fa message No (string)
269 The notice message.
270 .El
271 .\" onPart
272 .Ss onPart
273 This event is triggered when someone has left a specific channel.
274 .Pp
275 Synopsis
276 .Bd -literal -offset Ds
277 function onPart(server, origin, channel, reason)
278 .Ed
279 .Pp
280 Arguments
281 .Bl -tag -width 20n -compact -offset Ds
282 .It Fa server No (Server)
283 The current server.
284 .It Fa origin No (string)
285 The person who left the channel.
286 .It Fa channel No (string)
287 The channel.
288 .It Fa reason No (string)
289 An optional reason.
290 .El
291 .\" onReload
292 .Ss onReload
293 Request to reload the plugin.
294 .Pp
295 This function does nothing in the irccd internals, it just calls a function that
296 you can use to reload some data.
297 .Pp
298 Synopsis
299 .Bd -literal -offset Ds
300 function onReload()
301 .Ed
302 .\" onTopic
303 .Ss onTopic
304 This event is triggered when someone changed the channel's topic.
305 .Pp
306 Synopsis
307 .Bd -literal -offset Ds
308 function onTopic(server, origin, channel, topic)
309 .Ed
310 .Pp
311 Arguments
312 .Bl -tag -width 20n -compact -offset Ds
313 .It Fa server No (Server)
314 The current server.
315 .It Fa origin No (string)
316 The person who changed the topic.
317 .It Fa channel No (string)
318 The channel.
319 .It Fa topic No (string)
320 The new topic (may be empty).
321 .El
322 .\" onUnload
323 .Ss onUnload
324 This event is triggered when the plugin is about to be unloaded.
325 .Pp
326 Synopsis
327 .Bd -literal -offset Ds
328 function onUnload()
329 .Ed
330 .\" onWhois
331 .Ss onWhois
332 This event is triggered when irccd gets information about a user.
333 .Pp
334 Synopsis
335 .Bd -literal -offset Ds
336 function onWhois(server, info)
337 .Ed
338 .Pp
339 Arguments
340 .Bl -tag -width 20n -compact -offset Ds
341 .It Fa server No (Server)
342 The current server.
343 .It Fa info No (Object)
344 The whois information.
345 .El
346 .Pp
347 The
348 .Fa info
349 is an object with the following properties:
350 .Bl -tag -width 20n -compact -offset Ds
351 .It Fa nickname No (string)
352 The user nickname.
353 .It Fa user No (string)
354 The user name.
355 .It Fa host No (string)
356 The hostname.
357 .It Fa realname No (string)
358 The real name used.
359 .It Fa channels No (array)
360 An optional list of channels joined.
361 .El
362 .\" MODULES
363 .Sh MODULES
364 The following modules are part of the official Javascript API. They are all
365 accessible as global function, variables and objects.
366 .Pp
367 All modules are categorized into pseudo namespaces that are placed into the
368 global
369 .Va Irccd
370 object. (e.g.
371 .Va Irccd.Directory , Irccd.File ) .
372 .\" {{{ Module: Irccd
373 .Ss Irccd
374 Top level irccd Javascript module.
375 .Pp
376 Contains general irccd variables and functions.
377 .Pp
378 .\" {{{ Constants
379 The following constants properties are defined:
380 .Pp
381 .Bl -tag -width 22n -compact -offset Ds
382 .It Va version No (object)
383 See below.
384 .It Va version.major No (int)
385 The major irccd version.
386 .It Va version.minor No (int)
387 The minor irccd version.
388 .It Va version.patch No (int)
389 The patch irccd version.
390 .El
391 .Pp
392 .\" }}} !Constants
393 .\" {{{ Types
394 The following objects are defined:
395 .Bl -tag -width 22n -compact -offset Ds
396 .It Va SystemError No (function)
397 An exception inheriting Error thrown by some filesystem functions.
398 .El
399 .\" }}} !Types
400 .\" }}} !Module: Irccd
401 .\" {{{ Module: Irccd.Chrono
402 .Ss Irccd.Chrono
403 This class let you measure the elapsed time.
404 .\" {{{ Methods
405 .\" {{{ Irccd.Chrono [constructor]
406 .Pp
407 Irccd.Chrono [constructor]
408 .Bd -ragged -offset indent
409 Construct a new Chrono object. The timer is automatically started on
410 construction.
411 .Pp
412 Synopsis
413 .Bd -literal -offset Ds
414 Irccd.ElapsedTimer()
415 .Ed
416 .Ed
417 .\" }}}
418 .\" {{{ Irccd.Chrono.prototype.elapsed
419 .Pp
420 Irccd.Chrono.prototype.elapsed
421 .Bd -ragged -offset indent
422 Get the number of elapsed milliseconds.
423 .Pp
424 Synopsis
425 .Bd -literal -offset Ds
426 Irccd.Chrono.prototype.elapsed()
427 .Ed
428 .Pp
429 Returns
430 .Pp
431 The elapsed time in milliseconds.
432 .Ed
433 .\" }}}
434 .\" {{{ Irccd.Chrono.prototype.pause
435 .Pp
436 Irccd.Chrono.prototype.pause
437 .Bd -ragged -offset indent
438 Pause the timer, without resetting the current elapsed time stored.
439 .Pp
440 Synopsis
441 .Bd -literal -offset Ds
442 Irccd.Chrono.prototype.pause()
443 .Ed
444 .Ed
445 .\" }}}
446 .\" {{{ Irccd.Chrono.prototype.resume
447 .Pp
448 Irccd.Chrono.prototype.resume
449 .Bd -ragged -offset indent
450 Continue accumulating additional time. Has no effect if the timer is already
451 running.
452 .Pp
453 Synopsis
454 .Bd -literal -offset Ds
455 Irccd.Chrono.prototype.restart()
456 .Ed
457 .Ed
458 .\" }}}
459 .\" {{{ Irccd.Chrono.prototype.start
460 .Pp
461 Irccd.Chrono.prototype.start
462 .Bd -ragged -offset indent
463 Starts or restarts accumulating time.
464 .Pp
465 Synopsis
466 .Bd -literal -offset Ds
467 Irccd.Chrono.prototype.start()
468 .Ed
469 .Ed
470 .\" }}}
471 .\" }}}
472 .\" }}} !Module: Irccd.Chrono
473 .\" {{{ Module: Irccd.Directory
474 .Ss Irccd.Directory
475 This module can be used to iterate, find, remove or create directories.
476 .Pp
477 Use this module with care.
478 .Pp
479 .\" {{{ Constants
480 The following constants properties are defined:
481 .Pp
482 .Bl -tag -width 20n -compact -offset Ds
483 .It Va Dot No (int)
484 list "." directory.
485 .It Va DotDot No (int)
486 list ".." directory.
487 .It Va TypeUnknown No (int)
488 unknown type file.
489 .It Va TypeDir No (int)
490 entry is a directory.
491 .It Va TypeFile No (int)
492 entry is a file.
493 .It Va TypeLink No (int)
494 entry is a link.
495 .El
496 .\" }}} !Constants
497 .\" {{{ Functions
498 .\" {{{ Irccd.Directory.find
499 .Pp
500 Irccd.Directory.find
501 .Bd -ragged -offset indent
502 .Pp
503 Find an entry by a pattern or a regular expression.
504 .Pp
505 Synopsis
506 .Bd -literal -offset Ds
507 Irccd.Directory.find(path, pattern, recursive)
508 .Ed
509 .Pp
510 Arguments
511 .Pp
512 .Bl -tag -width 20n -compact -offset Ds
513 .It Fa path No (string)
514 The base path.
515 .It Fa pattern No (mixed)
516 The regular expression or file name as string.
517 .It Fa recursive No (bool)
518 Set to true to search recursively (Optional, default: false).
519 .El
520 .Pp
521 Returns
522 .Pp
523 The path to the file or undefined if not found.
524 .Ed
525 .\" }}}
526 .\" {{{ Irccd.Directory.mkdir
527 .Pp
528 Irccd.Directory.mkdir
529 .Bd -ragged -offset indent
530 Create a directory specified by path. It will create needed subdirectories just
531 like you have invoked mkdir -p.
532 .Pp
533 Synopsis
534 .Bd -literal -offset Ds
535 Irccd.Directory.mkdir(path, mode = 0700)
536 .Ed
537 .Pp
538 Arguments
539 .Pp
540 .Bl -tag -width 20n -compact -offset Ds
541 .It Fa path No (string)
542 The path to the directory.
543 .It Fa mode No (string)
544 The mode, not available on all platforms.
545 .El
546 .Pp
547 Throws
548 .Pp
549 Any exception on error.
550 .Ed
551 .\" }}}
552 .\" {{{ Irccd.Directory.remove
553 .Pp
554 Irccd.Directory.remove
555 .Bd -ragged -offset indent
556 Remove the directory optionally recursively.
557 .Pp
558 Synopsis
559 .Bd -literal -offset Ds
560 Irccd.Directory.remove(path, recursive)
561 .Ed
562 .Pp
563 Arguments
564 .Pp
565 .Bl -tag -width 20n -compact -offset Ds
566 .It Fa path No (string)
567 The path to the directory.
568 .It Fa recursive No (bool)
569 Recursively or not (Optional, default: false).
570 .El
571 .Pp
572 Throws
573 .Pp
574 Any exception on error.
575 .Ed
576 .\" }}}
577 .\" }}} !Functions
578 .\" {{{ Methods
579 .\" {{{ Irccd.Directory [constructor]
580 .Pp
581 Irccd.Directory [constructor]
582 .Bd -ragged -offset indent
583 Open a directory.
584 .Pp
585 When constructed successfully, the object has the following properties:
586 .Pp
587 .Bl -tag -width 20n -offset indent -compact
588 .It Va path No (string)
589 the path to the directory.
590 .It Va entries No (array)
591 an array for each entry containing. See below
592 .El
593 .Pp
594 For each entry found, the array entries contains as many objects with the
595 following properties:
596 .Pp
597 .Bl -tag -width 14n -offset indent-two -compact
598 .It Va name No (string)
599 the base file name.
600 .It Va type No (int)
601 the type of file (Irccd.Directory.Type*).
602 .El
603 .Pp
604 Synopsis
605 .Bd -literal -offset Ds
606 Irccd.Directory(path, flags)
607 .Ed
608 .Pp
609 Arguments
610 .Pp
611 .Bl -tag -width 20n -compact -offset Ds
612 .It Fa path No (string)
613 The path to the directory.
614 .It Va flags No (int)
615 The OR'ed flags:
616 .Va Irccd.Directory.Dot , Irccd.Directory.DotDot
617 (Optional, default: none).
618 .El
619 .Pp
620 Throws
621 .Pp
622 Any exception on error.
623 .Ed
624 .\" }}}
625 .\" {{{ Irccd.Directory.prototype.find
626 .Pp
627 Irccd.Directory.prototype.find
628 .Bd -ragged -offset indent
629 Synonym of find static function but the path is taken from the directory object.
630 .Pp
631 Synopsis
632 .Bd -literal -offset Ds
633 Irccd.Directory.prototype.find(pattern, recursive)
634 .Ed
635 .Pp
636 Arguments
637 .Pp
638 .Bl -tag -width 20n -compact -offset Ds
639 .It Fa pattern No (mixed)
640 The regular expression or file name.
641 .It Fa recursive No (bool)
642 Set to true to search recursively (Optional, default: false).
643 .El
644 .Pp
645 Throws
646 .Pp
647 Any exception on error.
648 .Pp
649 Returns
650 .Pp
651 The path to the file or undefined if not found.
652 .Ed
653 .\" }}}
654 .\" {{{ Irccd.Directory.prototype.remove
655 .Pp
656 Irccd.Directory.prototype.remove
657 .Bd -ragged -offset indent
658 Synonym of remove static function but the path is taken from the directory
659 object.
660 .Pp
661 Synopsis
662 .Bd -literal -offset Ds
663 Irccd.Directory.prototype.remove(recursive)
664 .Ed
665 .Pp
666 Arguments
667 .Pp
668 .Bl -tag -width 20n -compact -offset Ds
669 .It Fa recursive No (bool)
670 Recursively or not (Optional, default: false).
671 .El
672 .Pp
673 Throws
674 .Pp
675 Any exception on error.
676 .Ed
677 .\" }}}
678 .\" }}} !Methods
679 .\" }}} !Module: Irccd.Directory
680 .\" {{{ Module: Irccd.File
681 .Ss Irccd.File
682 This module is available for opening and writing files on the disk.
683 .Pp
684 For convenience, some functions are available as free-functions and some as
685 object methods.
686 .\" {{{ Constants
687 The following constants properties are defined:
688 .Pp
689 .Bl -tag -width 20n -compact -offset Ds
690 .It Va SeekCur No (int)
691 Seek from the current file position.
692 .It Va SeekEnd No (int)
693 Seek from end of the file.
694 .It Va SeekSet No (int)
695 Seek from beginning of the file.
696 .El
697 .\" }}} !Constants
698 .\" {{{ Functions
699 .\" {{{ Irccd.File.basename
700 .Pp
701 Irccd.File.basename
702 .Bd -ragged -offset indent
703 Return the file basename as specified in basename C function.
704 .Pp
705 Synopsis
706 .Bd -literal -offset Ds
707 base = Irccd.File.basename(path)
708 .Ed
709 .Pp
710 Arguments
711 .Pp
712 .Bl -tag -width 20n -compact -offset Ds
713 .It Fa path No (string)
714 The path to the file.
715 .El
716 .Pp
717 Returns
718 .Pp
719 The base name.
720 .Ed
721 .\" }}}
722 .\" {{{ Irccd.File.dirname
723 .Pp
724 Irccd.File.dirname
725 .Bd -ragged -offset indent
726 Return the file directory name as specified in dirname C function.
727 .Pp
728 Synopsis
729 .Bd -literal -offset Ds
730 path = Irccd.File.dirname(path)
731 .Ed
732 .Pp
733 Arguments
734 .Pp
735 .Bl -tag -width 20n -compact -offset Ds
736 .It Fa path No (string)
737 The path to the file.
738 .El
739 .Pp
740 Returns
741 .Pp
742 The directory name.
743 .Ed
744 .\" }}}
745 .\" {{{ Irccd.File.exists
746 .Pp
747 Irccd.File.exists
748 .Bd -ragged -offset indent
749 Check if the file exists.
750 .Pp
751 Warning: using this function is usually discouraged as it may introduce a
752 possible race condition.
753 .Pp
754 Synopsis
755 .Bd -literal -offset Ds
756 ret = Irccd.File.exists(path)
757 .Ed
758 .Pp
759 Arguments
760 .Pp
761 .Bl -tag -width 20n -compact -offset Ds
762 .It Fa path No (string)
763 The path to the file.
764 .El
765 .Pp
766 Throws
767 .Pp
768 Irccd.SystemError on failure.
769 .Pp
770 Returns
771 .Pp
772 True if exists.
773 .Ed
774 .\" }}}
775 .\" {{{ Irccd.File.remove
776 .Pp
777 Irccd.File.remove
778 .Bd -ragged -offset indent
779 Remove the file at the specified path.
780 .Pp
781 Synopsis
782 .Bd -literal -offset Ds
783 Irccd.File.remove(path)
784 .Ed
785 .Pp
786 Arguments
787 .Pp
788 .Bl -tag -width 20n -compact -offset Ds
789 .It Fa path No (string)
790 The path to the file.
791 .El
792 .Pp
793 Throws
794 .Pp
795 Irccd.SystemError on failure.
796 .Ed
797 .\" }}}
798 .\" {{{ Irccd.File.stat
799 .Pp
800 Irccd.File.stat [optional]
801 .Bd -ragged -offset indent
802 Get file information at the specified path.
803 .Pp
804 Synopsis
805 .Bd -literal -offset Ds
806 info = Irccd.File.stat(path)
807 .Ed
808 .Pp
809 Arguments
810 .Pp
811 .Bl -tag -width 20n -compact -offset Ds
812 .It Fa path No (string)
813 The path to the file.
814 .El
815 .Pp
816 Throws
817 .Pp
818 Irccd.SystemError on failure.
819 .Pp
820 Returns
821 .Pp
822 An object with the following properties. Not all properties are available and
823 you must check its presence before using it.
824 .Pp
825 .Bl -tag -width 20n -compact -offset Ds
826 .It Va atime No (int)
827 The last access time.
828 .It Va blksize No (int)
829 The block size.
830 .It Va blocks No (int)
831 The number of blocks.
832 .It Va ctime No (int)
833 The creation time.
834 .It Va dev No (int)
835 The device.
836 .It Va gid No (int)
837 The group numeric id.
838 .It Va ino No (int)
839 The inode.
840 .It Va mode No (int)
841 The mode.
842 .It Va mtime No (int)
843 The modification time.
844 .It Va nlink No (int)
845 The number of hard links.
846 .It Va rdev No (int)
847 No description available.
848 .It Va size No (int)
849 The file size.
850 .It Va uid No (int)
851 The user numeric id.
852 .El
853 .Ed
854 .\" }}}
855 .\" }}} !Functions
856 .\" {{{ Methods
857 .\" {{{ Irccd.File [constructor]
858 .Pp
859 Irccd.File [constructor]
860 .Bd -ragged -offset indent
861 Open a file specified by path with the specified mode.
862 .Pp
863 Synopsis
864 .Bd -literal -offset Ds
865 Irccd.File(path, mode)
866 .Ed
867 .Pp
868 Arguments
869 .Pp
870 .Bl -tag -width 20n -compact -offset Ds
871 .It Fa path No (string)
872 The path to the file.
873 .It Fa mode No (string)
874 The mode string.
875 .El
876 .Pp
877 The
878 .Fa mode
879 is the same as if called by fopen, see the documentation of
880 .Xr fopen 3
881 for more information about modes.
882 .Pp
883 Throws
884 .Pp
885 Irccd.SystemError on failure.
886 .Ed
887 .\" }}}
888 .\" {{{ Irccd.File.prototype.basename
889 .Pp
890 Irccd.File.prototype.basename
891 .Bd -ragged -offset indent
892 Synonym of Irccd.File.basename static function but with the path taken from the
893 object itself.
894 .Pp
895 Synopsis
896 .Bd -literal -offset Ds
897 path = Irccd.File.prototype.basename()
898 .Ed
899 .Pp
900 Returns
901 .Pp
902 The base name.
903 .Ed
904 .\" }}}
905 .\" {{{ Irccd.File.prototype.close
906 .Pp
907 Irccd.File.prototype.close
908 .Bd -ragged -offset indent
909 Force close of the file, automatically called when object is collected.
910 .Pp
911 Synopsis
912 .Bd -literal -offset Ds
913 Irccd.File.prototype.close()
914 .Ed
915 .Ed
916 .\" }}}
917 .\" {{{ Irccd.File.prototype.dirname
918 .Pp
919 Irccd.File.prototype.dirname
920 .Bd -ragged -offset indent
921 Synonym of Irccd.File.dirname static function but with the path taken from the
922 object itself.
923 .Pp
924 Synopsis
925 .Bd -literal -offset Ds
926 path = Irccd.File.prototype.dirname()
927 .Ed
928 .Pp
929 Returns
930 .Pp
931 The directory name.
932 .Ed
933 .\" }}}
934 .\" {{{ Irccd.File.prototype.lines
935 .Pp
936 Irccd.File.prototype.lines
937 .Bd -ragged -offset indent
938 Read all lines and return an array.
939 .Pp
940 Synopsis
941 .Bd -literal -offset Ds
942 list = Irccd.File.prototype.lines()
943 .Ed
944 .Pp
945 Throws
946 .Pp
947 Irccd.SystemError on failure.
948 .Pp
949 Returns
950 .Pp
951 An array with all lines.
952 .Ed
953 .\" }}}
954 .\" {{{ Irccd.File.prototype.read
955 .Pp
956 Irccd.File.prototype.read
957 .Bd -ragged -offset indent
958 Read the specified amount of characters or the whole file.
959 .Pp
960 Synopsis
961 .Bd -literal -offset Ds
962 str = Irccd.File.prototype.read(amount)
963 .Ed
964 .Pp
965 Arguments
966 .Pp
967 .Bl -tag -width 20n -compact -offset Ds
968 .It Fa amount No (int)
969 The amount of characters or -1 to read all (Optional, default: -1).
970 .El
971 .Pp
972 Throws
973 .Pp
974 Irccd.SystemError on failure.
975 .Pp
976 Returns
977 .Pp
978 The string.
979 .Ed
980 .\" }}}
981 .\" {{{ Irccd.File.prototype.readline
982 .Pp
983 Irccd.File.prototype.readline
984 .Bd -ragged -offset indent
985 Read the next line available.
986 .Pp
987 Warning: this method is slow and its usage is discouraged on large files.
988 Consider using Irccd.File.prototype.lines function if you want to read a file
989 line per line.
990 .Pp
991 Synopsis
992 .Bd -literal -offset Ds
993 line = Irccd.File.prototype.readline()
994 .Ed
995 .Pp
996 Throws
997 .Pp
998 Irccd.SystemError on failure.
999 .Pp
1000 Returns
1001 .Pp
1002 The next line or undefined if EOF.
1003 .Ed
1004 .\" }}}
1005 .\" {{{ Irccd.File.prototype.remove
1006 .Pp
1007 Irccd.File.prototype.remove
1008 .Bd -ragged -offset indent
1009 Synonym of Irccd.File.remove static function but with the path taken from the
1010 object itself.
1011 .Pp
1012 Synopsis
1013 .Bd -literal -offset Ds
1014 Irccd.File.prototype.remove()
1015 .Ed
1016 .Pp
1017 Throws
1018 .Pp
1019 Irccd.SystemError on failure.
1020 .Ed
1021 .\" }}}
1022 .\" {{{ Irccd.File.prototype.seek
1023 .Pp
1024 Irccd.File.prototype.seek
1025 .Bd -ragged -offset indent
1026 Sets the position in the file.
1027 .Pp
1028 Synopsis
1029 .Bd -literal -offset Ds
1030 Irccd.File.prototype.seek(type, amount)
1031 .Ed
1032 .Pp
1033 Arguments
1034 .Pp
1035 .Bl -tag -width 20n -compact -offset Ds
1036 .It Fa type No (int)
1037 The type of setting
1038 .Fa ( Irccd.File.SeekSet , Irccd.File.SeekCur , Irccd.File.SeekSet ) .
1039 .It Fa amount No (int)
1040 The new offset.
1041 .El
1042 .Pp
1043 Throws
1044 .Pp
1045 Irccd.SystemError on failure.
1046 .Ed
1047 .\" }}}
1048 .\" {{{ Irccd.File.prototype.stat
1049 .Pp
1050 Irccd.File.prototype.stat [optional]
1051 .Bd -ragged -offset indent
1052 Synonym of Irccd.File.stat static function but with the path taken from the
1053 object itself.
1054 .Pp
1055 Synopsis
1056 .Bd -literal -offset Ds
1057 info = Irccd.File.prototype.stat()
1058 .Ed
1059 .Pp
1060 Throws
1061 .Pp
1062 Irccd.SystemError on failure.
1063 .Pp
1064 Returns
1065 .Pp
1066 The information object.
1067 .Ed
1068 .\" }}}
1069 .\" {{{ Irccd.File.prototype.tell
1070 .Pp
1071 Irccd.File.prototype.tell
1072 .Bd -ragged -offset indent
1073 Get the actual position in the file.
1074 .Pp
1075 Synopsis
1076 .Bd -literal -offset Ds
1077 pos = Irccd.File.prototype.tell()
1078 .Ed
1079 .Pp
1080 Throws
1081 .Pp
1082 Irccd.SystemError on failure.
1083 .Pp
1084 Returns
1085 .Pp
1086 The position.
1087 .Ed
1088 .\" }}}
1089 .\" {{{ Irccd.File.prototype.write
1090 .Pp
1091 Irccd.File.prototype.write
1092 .Bd -ragged -offset indent
1093 Write some characters to the file.
1094 .Pp
1095 Synopsis
1096 .Bd -literal -offset Ds
1097 Irccd.File.prototype.write(data)
1098 .Ed
1099 .Pp
1100 Arguments
1101 .Pp
1102 .Bl -tag -width 20n -compact -offset Ds
1103 .It Fa data No (string)
1104 The character to write.
1105 .El
1106 .Pp
1107 Throws
1108 .Pp
1109 Irccd.SystemError on failure.
1110 .Pp
1111 Returns
1112 .Pp
1113 The number of bytes written.
1114 .Ed
1115 .\" }}}
1116 .\" }}} !Methods
1117 .\" }}} !Module: Irccd.File
1118 .\" {{{ Module: Irccd.Logger
1119 .Ss Irccd.Logger
1120 This module must be used to log something. It will add messages to the logging
1121 system configured in the irccd.conf file.
1122 .Pp
1123 For instance, if user has chosen to log into syslog, this module will log at
1124 syslog too.
1125 .Pp
1126 Any plugin can log messages, the message will be prepended by the plugin name to
1127 be easily identifiable.
1128 .\" {{{ Functions
1129 .\" {{{ Irccd.Logger.debug
1130 .Pp
1131 Irccd.Logger.debug
1132 .Bd -ragged -offset indent
1133 Adds a debug message, this is only appended to the journal if irccd was compiled
1134 in Debug mode.
1135 .Pp
1136 Synopsis
1137 .Bd -literal -offset Ds
1138 Irccd.Logger.debug(message)
1139 .Ed
1140 .Pp
1141 Arguments
1142 .Pp
1143 .Bl -tag -width 20n -compact -offset Ds
1144 .It Fa message No (string)
1145 The message.
1146 .El
1147 .Ed
1148 .\" }}}
1149 .\" {{{ Irccd.Logger.info
1150 .Pp
1151 Irccd.Logger.info
1152 .Bd -ragged -offset indent
1153 Log something. The message is logged only if irccd is running with verbose
1154 messages enabled.
1155 .Pp
1156 Synopsis
1157 .Bd -literal -offset Ds
1158 Irccd.Logger.info(message)
1159 .Ed
1160 .Pp
1161 Arguments
1162 .Pp
1163 .Bl -tag -width 20n -compact -offset Ds
1164 .It Fa message No (string)
1165 The message.
1166 .El
1167 .Ed
1168 .\" }}}
1169 .\" {{{ Irccd.Logger.warning
1170 .Pp
1171 Irccd.Logger.warning
1172 .Bd -ragged -offset indent
1173 Log a warning. The message will always be logged.
1174 .Pp
1175 Synopsis
1176 .Bd -literal -offset Ds
1177 Irccd.Logger.warning(message)
1178 .Ed
1179 .Pp
1180 Arguments
1181 .Pp
1182 .Bl -tag -width 20n -compact -offset Ds
1183 .It Fa message No (string)
1184 The message.
1185 .El
1186 .Ed
1187 .\" }}}
1188 .\" }}} !Functions
1189 .\" }}} !Module: Irccd.Logger
1190 .\" {{{ Module: Irccd.Plugin
1191 .Ss Irccd.Plugin
1192 This module let you manage plugins.
1193 .Pp
1194 .\" {{{ Constants
1195 The following constants properties are defined and contain each key-value pairs
1196 from the user configuration file.
1197 .Pp
1198 .Bl -tag -width 20n -compact -offset Ds
1199 .It Va config No (Object)
1200 Contains the
1201 .Va [plugin.<name>]
1202 section.
1203 .It Va paths No (Object)
1204 Contains the
1205 .Va [paths.<name>]
1206 section.
1207 .It Va templates No (Object)
1208 Contains the
1209 .Va [format.<name>]
1210 section.
1211 .El
1212 .\" }}} !Constants
1213 .\" {{{ Functions
1214 .\" {{{ Irccd.Plugin.info
1215 .Pp
1216 Irccd.Plugin.info
1217 .Bd -ragged -offset indent
1218 Get information about a plugin.
1219 .Pp
1220 Synopsis
1221 .Bd -literal -offset Ds
1222 info = Irccd.Plugin.info(name)
1223 .Ed
1224 .Pp
1225 Arguments
1226 .Pp
1227 .Bl -tag -width 20n -compact -offset Ds
1228 .It Fa name No (string)
1229 The plugin identifier, if not specified the current plugin is selected.
1230 .El
1231 .Pp
1232 Returns
1233 .Pp
1234 The plugin information or undefined if the plugin was not found. The object has
1235 the following properties:
1236 .Pp
1237 .Bl -tag -width 20n -compact -offset Ds
1238 .It Va name No (string)
1239 The plugin identifier.
1240 .It Va author No (string)
1241 The author.
1242 .It Va license No (string)
1243 The license.
1244 .It Va summary No (string)
1245 A short description.
1246 .It Va version No (string)
1247 The version.
1248 .El
1249 .Ed
1250 .\" }}}
1251 .\" {{{ Irccd.Plugin.list
1252 .Pp
1253 Irccd.Plugin.list
1254 .Bd -ragged -offset indent
1255 Get the list of plugins, the array returned contains all plugin names as
1256 strings.
1257 .Pp
1258 Synopsis
1259 .Bd -literal -offset Ds
1260 list = Irccd.Plugin.list()
1261 .Ed
1262 .Pp
1263 Returns
1264 .Pp
1265 The list of all plugin names.
1266 .Ed
1267 .\" }}}
1268 .\" {{{ Irccd.Plugin.load
1269 .Pp
1270 Irccd.Plugin.load
1271 .Bd -ragged -offset indent
1272 Load a plugin by name. This function will search through the standard
1273 directories.
1274 .Pp
1275 Synopsis
1276 .Bd -literal -offset Ds
1277 Irccd.Plugin.load(name)
1278 .Ed
1279 .Pp
1280 Arguments
1281 .Pp
1282 .Bl -tag -width 20n -compact -offset Ds
1283 .It Fa name No (string)
1284 The plugin identifier.
1285 .El
1286 .Pp
1287 Throws
1288 .Pp
1289 .Bl -tag -width 20n -compact -offset Ds
1290 .It Va Error
1291 On errors.
1292 .It Va ReferenceError
1293 If the plugin was not found.
1294 .El
1295 .Ed
1296 .\" }}}
1297 .\" {{{ Irccd.Plugin.reload
1298 .Pp
1299 Irccd.Plugin.reload
1300 .Bd -ragged -offset indent
1301 Reload a plugin by name.
1302 .Pp
1303 Synopsis
1304 .Bd -literal -offset Ds
1305 Irccd.Plugin.reload(name)
1306 .Ed
1307 .Pp
1308 Arguments
1309 .Pp
1310 .Bl -tag -width 20n -compact -offset Ds
1311 .It Fa name No (string)
1312 The plugin identifier.
1313 .El
1314 .Pp
1315 Throws
1316 .Pp
1317 .Bl -tag -width 20n -compact -offset Ds
1318 .It Va Error
1319 On errors.
1320 .It Va ReferenceError
1321 If the plugin was not found.
1322 .El
1323 .Ed
1324 .\" }}}
1325 .\" {{{ Irccd.Plugin.unload
1326 .Pp
1327 Irccd.Plugin.unload
1328 .Bd -ragged -offset indent
1329 Unload a plugin by name and remove it.
1330 .Pp
1331 Synopsis
1332 .Bd -literal -offset Ds
1333 Irccd.Plugin.unload(name)
1334 .Ed
1335 .Pp
1336 Arguments
1337 .Pp
1338 .Bl -tag -width 20n -compact -offset Ds
1339 .It Fa name No (string)
1340 The plugin identifier.
1341 .El
1342 .Pp
1343 Throws
1344 .Pp
1345 .Bl -tag -width 20n -compact -offset Ds
1346 .It Va Error
1347 On errors.
1348 .It Va ReferenceError
1349 If the plugin was not found.
1350 .El
1351 .Ed
1352 .\" }}}
1353 .\" }}} !Functions
1354 .\" }}} !Module: Irccd.Plugin
1355 .\" {{{ Module: Irccd.Server
1356 .Ss Irccd.Server
1357 This module is the object that you received in almost all IRC event
1358 (e.g. onConnect). You can use its methods to do your required actions on the
1359 server.
1360 .\" {{{ Functions
1361 .\" {{{ Irccd.Server.add
1362 .Pp
1363 Irccd.Server.add
1364 .Bd -ragged -offset indent
1365 Add a new server to the irccd instance.
1366 .Pp
1367 Synopsis
1368 .Bd -literal -offset Ds
1369 Irccd.Server.add(server)
1370 .Ed
1371 .Pp
1372 Arguments
1373 .Pp
1374 .Bl -tag -width 20n -compact -offset Ds
1375 .It Fa server No (Server)
1376 The server object to add.
1377 .El
1378 .Ed
1379 .\" }}}
1380 .\" {{{ Irccd.Server.find
1381 .Pp
1382 Irccd.Server.find
1383 .Bd -ragged -offset indent
1384 Find a server by name.
1385 .Pp
1386 Synopsis
1387 .Bd -literal -offset Ds
1388 server = Irccd.Server.find(name)
1389 .Ed
1390 .Pp
1391 Arguments
1392 .Pp
1393 .Bl -tag -width 20n -compact -offset Ds
1394 .It Fa name No (string)
1395 The server name.
1396 .El
1397 .Pp
1398 Returns
1399 .Pp
1400 The server object or undefined if not found.
1401 .Ed
1402 .\" }}}
1403 .\" {{{ Irccd.Server.list
1404 .Pp
1405 Irccd.Server.list
1406 .Bd -ragged -offset indent
1407 List all servers in a map.
1408 .Pp
1409 Synopsis
1410 .Bd -literal -offset Ds
1411 table = Irccd.Server.list()
1412 .Ed
1413 .Pp
1414 Returns
1415 .Pp
1416 The table of all servers as key-value pairs where key is the server identifier
1417 and value the object itself.
1418 .Ed
1419 .\" }}}
1420 .\" {{{ Irccd.Server.remove
1421 .Pp
1422 Irccd.Server.remove
1423 .Bd -ragged -offset indent
1424 Remove a server from the irccd instance and disconnect it.
1425 .Pp
1426 Synopsis
1427 .Bd -literal -offset Ds
1428 Irccd.Server.remove(name)
1429 .Ed
1430 .Pp
1431 Arguments
1432 .Pp
1433 .Bl -tag -width 20n -compact -offset Ds
1434 .It Fa name No (string)
1435 The server name.
1436 .El
1437 .Ed
1438 .\" }}}
1439 .\" }}} !Functions
1440 .\" {{{ Methods
1441 .\" {{{ Irccd.Server [constructor]
1442 .Pp
1443 Irccd.Server [constructor]
1444 .Bd -ragged -offset indent
1445 Construct a new server.
1446 .Pp
1447 Synopsis
1448 .Bd -literal -offset Ds
1449 Irccd.Server(info)
1450 .Ed
1451 .Pp
1452 Arguments
1453 .Pp
1454 .Bl -tag -width 20n -compact -offset Ds
1455 .It Fa info No (object)
1456 Object information.
1457 .El
1458 .Pp
1459 The
1460 .Fa info
1461 argument may have the following properties:
1462 .Bl -tag -width 20n -compact -offset Ds
1463 .It Fa name No (string)
1464 The unique identifier name.
1465 .It Fa hostname No (string)
1466 The host or IP address.
1467 .It Fa ipv4 No (bool)
1468 Enable ipv4 (Optional, default: true).
1469 .It Fa ipv6 No (bool)
1470 Enable ipv6, (Optional, default: true).
1471 .It Fa port No (int)
1472 The port number, (Optional, default: 6667).
1473 .It Fa password No (string)
1474 The password, (Optional, default: undefined).
1475 .It Fa channels No (array)
1476 Array of channels (Optional, default: empty).
1477 .It Fa ssl No (bool)
1478 True to use ssl, (Optional, default: false).
1479 .It Fa nickname No (string)
1480 Nickname, (Optional, default: irccd).
1481 .It Fa username No (string)
1482 User name, (Optional, default: irccd).
1483 .It Fa realname No (string)
1484 Real name, (Optional, default: IRC Client Daemon).
1485 .It Fa commandChar No (string)
1486 Plugin prefix character, (Optional, default: "!").
1487 .El
1488 .Pp
1489 Warning: at least ipv4 and ipv6 must be set (which is the default).
1490 .Ed
1491 .\" }}}
1492 .\" {{{ Irccd.Server.prototype.info
1493 .Pp
1494 Irccd.Server.prototype.info
1495 .Bd -ragged -offset indent
1496 Get server information.
1497 .Pp
1498 Synopsis
1499 .Bd -literal -offset Ds
1500 info = Irccd.Server.prototype.info()
1501 .Ed
1502 .Pp
1503 Returns
1504 .Pp
1505 The server information. The object have the following properties:
1506 .Bl -tag -width 20n -compact -offset Ds
1507 .It Va name No (string)
1508 The server unique name.
1509 .It Va hostname No (string)
1510 The host name.
1511 .It Va port No (int)
1512 The port number.
1513 .It Va ssl No (bool)
1514 True if using ssl.
1515 .It Va channels No (array)
1516 An array of all channels.
1517 .It Va realname No (string)
1518 The current real name.
1519 .It Va username No (string)
1520 The user name.
1521 .It Va nickname No (string)
1522 The current nickname.
1523 .El
1524 .Ed
1525 .\" }}}
1526 .\" {{{ Irccd.Server.prototype.invite
1527 .Pp
1528 Irccd.Server.prototype.invite
1529 .Bd -ragged -offset indent
1530 Invite the specified target on the channel.
1531 .Pp
1532 Synopsis
1533 .Bd -literal -offset Ds
1534 Irccd.Server.prototype.invite(target, channel)
1535 .Ed
1536 .Pp
1537 Arguments
1538 .Pp
1539 .Bl -tag -width 20n -compact -offset Ds
1540 .It Fa target No (string)
1541 The target to invite.
1542 .It Fa channel No (string)
1543 The channel.
1544 .El
1545 .Ed
1546 .\" }}}
1547 .\" {{{ Irccd.Server.prototype.isSelf
1548 .Pp
1549 Irccd.Server.prototype.isSelf
1550 .Bd -ragged -offset indent
1551 Check if the nickname targets the bot.
1552 .Pp
1553 Synopsis
1554 .Bd -literal -offset Ds
1555 res = Server.prototype.isSelf(nickname)
1556 .Ed
1557 .Pp
1558 Arguments
1559 .Pp
1560 .Bl -tag -width 20n -compact -offset Ds
1561 .It Fa nickname No (string)
1562 The nickname to check.
1563 .El
1564 .Pp
1565 Returns
1566 .Pp
1567 True if nickname is same as the bot.
1568 .Ed
1569 .\" }}}
1570 .\" {{{ Irccd.Server.prototype.join
1571 .Pp
1572 Irccd.Server.prototype.join
1573 .Bd -ragged -offset indent
1574 Join the specified channel, the password is optional.
1575 .Pp
1576 Synopsis
1577 .Bd -literal -offset Ds
1578 Irccd.Server.prototype.join(channel, password)
1579 .Ed
1580 .Pp
1581 Arguments
1582 .Pp
1583 .Bl -tag -width 20n -compact -offset Ds
1584 .It Fa channel No (string)
1585 The channel to join.
1586 .It Fa password No (string)
1587 An optional password.
1588 .El
1589 .Ed
1590 .\" }}}
1591 .\" {{{ Irccd.Server.prototype.kick
1592 .Pp
1593 Irccd.Server.prototype.kick
1594 .Bd -ragged -offset indent
1595 Kick the specified target from the channel, the reason is optional.
1596 .Pp
1597 Synopsis
1598 .Bd -literal -offset Ds
1599 Server.prototype.kick(nickname, channel, reason)
1600 .Ed
1601 .Pp
1602 Arguments
1603 .Pp
1604 .Bl -tag -width 20n -compact -offset Ds
1605 .It Fa nickname No (string)
1606 The person to kick.
1607 .It Fa channel No (string)
1608 From which channel.
1609 .It Fa reason No (string)
1610 A reason (Optional, default: undefined).
1611 .El
1612 .Ed
1613 .\" }}}
1614 .\" {{{ Irccd.Server.prototype.me
1615 .Pp
1616 Irccd.Server.prototype.me
1617 .Bd -ragged -offset indent
1618 Send an action emote.
1619 .Pp
1620 Synopsis
1621 .Bd -literal -offset Ds
1622 Irccd.Server.prototype.me(target, message)
1623 .Ed
1624 .Pp
1625 Arguments
1626 .Pp
1627 .Bl -tag -width 20n -compact -offset Ds
1628 .It Fa target No (string)
1629 A nick or a channel.
1630 .It Fa message No (string)
1631 The message to send.
1632 .El
1633 .Ed
1634 .\" }}}
1635 .\" {{{ Irccd.Server.prototype.message
1636 .Pp
1637 Irccd.Server.prototype.message
1638 .Bd -ragged -offset indent
1639 Send a message to the specified target or channel.
1640 .Pp
1641 Synopsis
1642 .Bd -literal -offset Ds
1643 Irccd.Server.prototype.message(target, message)
1644 .Ed
1645 .Pp
1646 Arguments
1647 .Pp
1648 .Bl -tag -width 20n -compact -offset Ds
1649 .It Fa target No (string)
1650 The target.
1651 .It Fa message No (string)
1652 The message to send.
1653 .El
1654 .Ed
1655 .\" }}}
1656 .\" {{{ Irccd.Server.prototype.mode
1657 .Pp
1658 Irccd.Server.prototype.mode
1659 .Bd -ragged -offset indent
1660 Change irccd's user mode or a channel mode.
1661 .Pp
1662 Synopsis
1663 .Bd -literal -offset Ds
1664 Irccd.Server.prototype.mode(channel, mode, limit, user, mode)
1665 .Ed
1666 .Pp
1667 Arguments
1668 .Pp
1669 .Bl -tag -width 20n -compact -offset Ds
1670 .It Fa channel No (string)
1671 A channel or your nicknam.
1672 .It Fa mode No (string)
1673 The new mode.
1674 .It Fa limit No (string)
1675 An optional limit.
1676 .It Fa user No (string)
1677 An optional use.
1678 .It Fa mask No (string)
1679 An optional mas.
1680 .El
1681 .Ed
1682 .\" }}}
1683 .\" {{{ Irccd.Server.prototype.names
1684 .Pp
1685 Irccd.Server.prototype.names
1686 .Bd -ragged -offset indent
1687 Get the list of names. This function will generate the onNames event.
1688 .Pp
1689 Synopsis
1690 .Bd -literal -offset Ds
1691 Irccd.Server.prototype.names(channel)
1692 .Ed
1693 .Pp
1694 Arguments
1695 .Pp
1696 .Bl -tag -width 20n -compact -offset Ds
1697 .It Fa channel No (string)
1698 The channel name.
1699 .El
1700 .Ed
1701 .\" }}}
1702 .\" {{{ Irccd.Server.prototype.nick
1703 .Pp
1704 Irccd.Server.prototype.nick
1705 .Bd -ragged -offset indent
1706 Change irccd's nickname.
1707 .Pp
1708 Synopsis
1709 .Bd -literal -offset Ds
1710 Irccd.Server.prototype.nick(nickname)
1711 .Ed
1712 .Pp
1713 Arguments
1714 .Pp
1715 .Bl -tag -width 20n -compact -offset Ds
1716 .It Fa nickname No (string)
1717 The new nickname.
1718 .El
1719 .Ed
1720 .\" }}}
1721 .\" {{{ Irccd.Server.prototype.notice
1722 .Pp
1723 Irccd.Server.prototype.notice
1724 .Bd -ragged -offset indent
1725 Send a private notice to the specified target.
1726 .Pp
1727 Synopsis
1728 .Bd -literal -offset Ds
1729 Irccd.Server.prototype.notice(nickname, message)
1730 .Ed
1731 .Pp
1732 Arguments
1733 .Pp
1734 .Bl -tag -width 20n -compact -offset Ds
1735 .It Fa nickname No (string)
1736 The target nickname.
1737 .It Fa message No (string)
1738 The notice message.
1739 .El
1740 .Ed
1741 .\" }}}
1742 .\" {{{ Irccd.Server.prototype.part
1743 .Pp
1744 Irccd.Server.prototype.part
1745 .Bd -ragged -offset indent
1746 Leave the specified channel, the reason is optional.
1747 .Pp
1748 Synopsis
1749 .Bd -literal -offset Ds
1750 Irccd.Server.prototype.part(channel, reason)
1751 .Ed
1752 .Pp
1753 Arguments
1754 .Pp
1755 .Bl -tag -width 20n -compact -offset Ds
1756 .It Fa channel No (string)
1757 The channel to leave.
1758 .It Fa reason No (string)
1759 A reason (Optional, default: undefined).
1760 .El
1761 .Ed
1762 .\" }}}
1763 .\" {{{ Irccd.Server.prototype.toString
1764 .Pp
1765 Irccd.Server.prototype.toString
1766 .Bd -ragged -offset indent
1767 Convert object as a string.
1768 .Pp
1769 Because each server has a unique identifier, this method allows adding a server
1770 a property key.
1771 .Pp
1772 Synopsis
1773 .Bd -literal -offset Ds
1774 id = Irccd.Server.prototype.toString()
1775 .Ed
1776 .Pp
1777 Returns
1778 .Pp
1779 The server identifier.
1780 .Ed
1781 .\" }}}
1782 .\" {{{ Irccd.Server.prototype.topic
1783 .Pp
1784 Irccd.Server.prototype.topic
1785 .Bd -ragged -offset indent
1786 Change the topic of the specified channel.
1787 .Pp
1788 Synopsis
1789 .Bd -literal -offset Ds
1790 Irccd.Server.prototype.topic(channel, topic)
1791 .Ed
1792 .Pp
1793 Arguments
1794 .Pp
1795 .Bl -tag -width 20n -compact -offset Ds
1796 .It Fa channel No (string)
1797 The channel.
1798 .It Fa topic No (string)
1799 The new topic.
1800 .El
1801 .Ed
1802 .\" }}}
1803 .\" {{{ Irccd.Server.prototype.whois
1804 .Pp
1805 Irccd.Server.prototype.whois
1806 .Bd -ragged -offset indent
1807 Get whois information from a user. The function will generate onWhois event.
1808 .Pp
1809 Synopsis
1810 .Bd -literal -offset Ds
1811 Irccd.Server.prototype.whois(target)
1812 .Ed
1813 .Pp
1814 Arguments
1815 .Pp
1816 .Bl -tag -width 20n -compact -offset Ds
1817 .It Fa target No (string)
1818 The target.
1819 .El
1820 .Ed
1821 .\" }}}
1822 .\" }}} !Methods
1823 .\" }}} !Module: Irccd.Server
1824 .\" {{{ Module: Irccd.System
1825 .Ss Irccd.System
1826 System inspection.
1827 .Pp
1828 Use this module if you want to inspect the system independently.
1829 .\" {{{ Functions
1830 .\" {{{ Irccd.System.env
1831 .Pp
1832 Irccd.System.env
1833 .Bd -ragged -offset indent
1834 Get a environment variable.
1835 .Pp
1836 Synopsis
1837 .Bd -literal -offset Ds
1838 value = Irccd.System.env(name)
1839 .Ed
1840 .Pp
1841 Arguments
1842 .Pp
1843 .Bl -tag -width 20n -compact -offset Ds
1844 .It Fa name No (string)
1845 The environment variable name.
1846 .El
1847 .Pp
1848 Returns
1849 .Pp
1850 The variable or an empty string.
1851 .Ed
1852 .\" }}}
1853 .\" {{{ Irccd.System.exec
1854 .Pp
1855 Irccd.System.exec
1856 .Bd -ragged -offset indent
1857 Execute a system command.
1858 .Pp
1859 Synopsis
1860 .Bd -literal -offset Ds
1861 Irccd.System.exec(cmd)
1862 .Ed
1863 .Pp
1864 Arguments
1865 .Pp
1866 .Bl -tag -width 20n -compact -offset Ds
1867 .It Fa cmd No (string)
1868 The command to execute.
1869 .El
1870 .Ed
1871 .\" }}}
1872 .\" {{{ Irccd.System.home
1873 .Pp
1874 Irccd.System.home
1875 .Bd -ragged -offset indent
1876 Get the home directory. This function should be used with care, plugin should
1877 not use user's home to store files.
1878 .Pp
1879 Synopsis
1880 .Bd -literal -offset Ds
1881 home = Irccd.System.home()
1882 .Ed
1883 .Pp
1884 Returns
1885 .Pp
1886 The user home directory.
1887 .Ed
1888 .\" }}}
1889 .\" {{{ Irccd.System.name
1890 .Pp
1891 Irccd.System.name
1892 .Bd -ragged -offset indent
1893 Get the operating system name. Returns one of:
1894 .Pp
1895 .Bl -bullet -compact
1896 .It
1897 Linux
1898 .It
1899 Windows
1900 .It
1901 FreeBSD
1902 .It
1903 DragonFlyBSD
1904 .It
1905 OpenBSD
1906 .It
1907 NetBSD
1908 .It
1909 macOS
1910 .It
1911 Android
1912 .It
1913 Aix
1914 .It
1915 Haiku
1916 .It
1917 iOS
1918 .It
1919 Solaris
1920 .It
1921 Unknown
1922 .El
1923 .Pp
1924 Synopsis
1925 .Bd -literal -offset Ds
1926 name = Irccd.System.name()
1927 .Ed
1928 .Pp
1929 Returns
1930 .Pp
1931 The operating system name.
1932 .Ed
1933 .\" }}}
1934 .\" {{{ Irccd.System.popen [optional]
1935 .Pp
1936 Irccd.System.popen [optional]
1937 .Bd -ragged -offset indent
1938 Wrapper for
1939 .Xr popen 3
1940 if the function is available.
1941 .Pp
1942 Synopsis
1943 .Bd -literal -offset Ds
1944 handle = Irccd.System.popen(cmd, mode)
1945 .Ed
1946 .Pp
1947 Arguments
1948 .Pp
1949 .Bl -tag -width 20n -compact -offset Ds
1950 .It Fa cmd No (string)
1951 The command to execute.
1952 .It Fa mode No (string)
1953 The mode (e.g. r).
1954 .El
1955 .Pp
1956 Throws
1957 .Pp
1958 Irccd.SystemError on failure.
1959 .Pp
1960 Returns
1961 .Pp
1962 An Irccd.File object.
1963 .Ed
1964 .\" }}}
1965 .\" {{{ Irccd.System.sleep
1966 .Pp
1967 Irccd.System.sleep
1968 .Bd -ragged -offset indent
1969 Sleep for seconds. Suspend the execution thread.
1970 .Pp
1971 Synopsis
1972 .Bd -literal -offset Ds
1973 Irccd.System.sleep(sec)
1974 .Ed
1975 .Ed
1976 .\" }}}
1977 .\" {{{ Irccd.System.ticks
1978 .Pp
1979 Irccd.System.ticks
1980 .Bd -ragged -offset indent
1981 Get the time spent from start. Get how many milliseconds spent since the irccd
1982 startup.
1983 .Pp
1984 Synopsis
1985 .Bd -literal -offset Ds
1986 msec = Irccd.System.ticks()
1987 .Ed
1988 .Pp
1989 Returns
1990 .Pp
1991 The number of milliseconds.
1992 .Ed
1993 .\" }}}
1994 .\" {{{ Irccd.System.uptime
1995 .Pp
1996 Irccd.System.uptime
1997 .Bd -ragged -offset indent
1998 Get the system uptime. This function returns the number of seconds elapsed since
1999 the system boot up.
2000 .Pp
2001 Synopsis
2002 .Bd -literal -offset Ds
2003 secs = Irccd.System.uptime()
2004 .Ed
2005 .Pp
2006 Returns
2007 .Pp
2008 The number of seconds.
2009 .Ed
2010 .\" }}}
2011 .\" {{{ Irccd.System.usleep
2012 .Pp
2013 Irccd.System.usleep
2014 .Bd -ragged -offset indent
2015 Sleep for milliseconds. Suspend the execution thread.
2016 .Pp
2017 Synopsis
2018 .Bd -literal -offset Ds
2019 Irccd.System.usleep(msec)
2020 .Ed
2021 .Pp
2022 Arguments
2023 .Pp
2024 .Bl -tag -width 20n -compact -offset Ds
2025 .It Fa msec No (int)
2026 The number of milliseconds.
2027 .El
2028 .Ed
2029 .\" }}}
2030 .\" {{{ Irccd.System.version
2031 .Pp
2032 Irccd.System.version
2033 .Bd -ragged -offset indent
2034 Get the operating system version. Result of this function is system dependant.
2035 .Pp
2036 Synopsis
2037 .Bd -literal -offset Ds
2038 version = Irccd.System.version()
2039 .Ed
2040 .Pp
2041 Returns
2042 .Pp
2043 The version as a string.
2044 .Ed
2045 .\" }}}
2046 .\" }}} !Functions
2047 .\" }}} !Module: Irccd.System
2048 .\" {{{ Module: Irccd.Timer
2049 .Ss Irccd.Timer
2050 Create repetitive or one-shot timers.
2051 .Pp
2052 .\" {{{ Constants
2053 The following constants properties are defined:
2054 .Pp
2055 .Bl -tag -width 20n -compact -offset Ds
2056 .It Va Single No (int)
2057 The timer is single-shot.
2058 .It Va Repeat No (int)
2059 The timer is looping.
2060 .El
2061 .\" }}}
2062 .\" {{{ Methods
2063 .\" {{{ Irccd.Timer [constructor]
2064 .Pp
2065 Irccd.Timer [constructor]
2066 .Bd -ragged -offset indent
2067 Create a new timer object but do not start it immediately.
2068 .Pp
2069 Synopsis
2070 .Bd -literal -offset Ds
2071 Irccd.Timer(type, delay, callback)
2072 .Ed
2073 .Pp
2074 Arguments
2075 .Pp
2076 .Bl -tag -width 20n -compact -offset Ds
2077 .It Fa type No (int)
2078 Type of timer (
2079 .Fa Irccd.Timer.Repeat
2080 or
2081 .Fa Irccd.Timer.Single ) .
2082 .It Fa delay No (int)
2083 The interval in milliseconds.
2084 .It Fa callback No (function)
2085 The function to call.
2086 .El
2087 .Pp
2088 Example:
2089 .Bd -literal -offset Ds
2090 var t = new Irccd.Timer(Irccd.Timer.Repeat, 1000, function () {
2091 // Do your action, this will be called every 1 second.
2092 });
2093 .Ed
2094 .Ed
2095 .\" }}}
2096 .\" {{{ Irccd.Timer.prototype.start
2097 .Pp
2098 Irccd.Timer.prototype.start
2099 .Bd -ragged -offset indent
2100 Start the timer.
2101 .Pp
2102 Synopsis
2103 .Bd -literal -offset Ds
2104 Irccd.Timer.prototype.start()
2105 .Ed
2106 .Ed
2107 .\" }}}
2108 .\" {{{ Irccd.Timer.prototype.stop
2109 .Pp
2110 Irccd.Timer.prototype.stop
2111 .Bd -ragged -offset indent
2112 Stop the timer.
2113 .Pp
2114 Synopsis
2115 .Bd -literal -offset Ds
2116 Irccd.Timer.prototype.stop()
2117 .Ed
2118 .Ed
2119 .\" }}}
2120 .\" }}} !Methods
2121 .\" }}} !Module: Irccd.Timer
2122 .\" {{{ Module: Irccd.Unicode
2123 .Ss Irccd.Unicode
2124 Check for character categories.
2125 .\" {{{ Functions
2126 .\" {{{ Irccd.Unicode.isDigit
2127 .Pp
2128 Irccd.Unicode.isDigit
2129 .Bd -ragged -offset indent
2130 Check if the unicode character is a digit.
2131 .Pp
2132 Synopsis
2133 .Bd -literal -offset Ds
2134 ret = Irccd.Unicode.isDigit(code)
2135 .Ed
2136 .Pp
2137 Arguments
2138 .Pp
2139 .Bl -tag -width 20n -compact -offset Ds
2140 .It Fa code No (string)
2141 The code point.
2142 .El
2143 .Pp
2144 Returns
2145 .Pp
2146 True if digit.
2147 .Ed
2148 .\" }}}
2149 .\" {{{ Irccd.Unicode.isLetter
2150 .Pp
2151 Irccd.Unicode.isLetter
2152 .Bd -ragged -offset indent
2153 Check if the unicode character is a letter.
2154 .Pp
2155 Synopsis
2156 .Bd -literal -offset Ds
2157 ret = Irccd.Unicode.isLetter(code)
2158 .Ed
2159 .Pp
2160 Arguments
2161 .Pp
2162 .Bl -tag -width 20n -compact -offset Ds
2163 .It Fa code No (string)
2164 The code point.
2165 .El
2166 .Pp
2167 Returns
2168 .Pp
2169 True if letter.
2170 .Ed
2171 .\" }}}
2172 .\" {{{ Irccd.Unicode.isLower
2173 .Pp
2174 Irccd.Unicode.isLower
2175 .Bd -ragged -offset indent
2176 Check if the unicode character is lower case.
2177 .Pp
2178 Synopsis
2179 .Bd -literal -offset Ds
2180 ret = Irccd.Unicode.isLower(code)
2181 .Ed
2182 .Pp
2183 Arguments
2184 .Pp
2185 .Bl -tag -width 20n -compact -offset Ds
2186 .It Fa code No (string)
2187 The code point.
2188 .El
2189 .Pp
2190 Returns
2191 .Pp
2192 True if lower case.
2193 .Ed
2194 .\" }}} !Functions
2195 .\" {{{ Irccd.Unicode.isSpace
2196 .Pp
2197 Irccd.Unicode.isSpace
2198 .Bd -ragged -offset indent
2199 Check if the unicode character is a space.
2200 .Pp
2201 Synopsis
2202 .Bd -literal -offset Ds
2203 ret = Irccd.Unicode.isSpace(code)
2204 .Ed
2205 .Pp
2206 Arguments
2207 .Pp
2208 .Bl -tag -width 20n -compact -offset Ds
2209 .It Fa code No (string)
2210 The code point.
2211 .El
2212 .Pp
2213 Returns
2214 .Pp
2215 True if space.
2216 .Ed
2217 .\" }}}
2218 .\" {{{ Irccd.Unicode.isTitle
2219 .Pp
2220 Irccd.Unicode.isTitle
2221 .Bd -ragged -offset indent
2222 Check if the unicode character is title case.
2223 .Pp
2224 Synopsis
2225 .Bd -literal -offset Ds
2226 ret = Irccd.Unicode.isTitle(code)
2227 .Ed
2228 .Pp
2229 Arguments
2230 .Pp
2231 .Bl -tag -width 20n -compact -offset Ds
2232 .It Fa code No (string)
2233 The code point.
2234 .El
2235 .Pp
2236 Returns
2237 .Pp
2238 True if title case.
2239 .Ed
2240 .\" }}}
2241 .\" {{{ Irccd.Unicode.isUppwer
2242 .Pp
2243 Irccd.Unicode.isUpper
2244 .Bd -ragged -offset indent
2245 Check if the unicode character is upper case.
2246 .Pp
2247 Synopsis
2248 .Bd -literal -offset Ds
2249 ret = Irccd.Unicode.isUpper(code)
2250 .Ed
2251 .Pp
2252 Arguments
2253 .Pp
2254 .Bl -tag -width 20n -compact -offset Ds
2255 .It Fa code No (string)
2256 The code point.
2257 .El
2258 .Pp
2259 Returns
2260 .Pp
2261 True if upper case.
2262 .Ed
2263 .\" }}}
2264 .\" }}} !Functions
2265 .\" }}} !Module: Irccd.Unicode
2266 .\" {{{ Module: Irccd.Util
2267 .Ss Irccd.Util
2268 Various utilities.
2269 .\" {{{ Functions
2270 .\" {{{ Irccd.Util.cut
2271 .Pp
2272 Irccd.Util.cut
2273 .Bd -ragged -offset indent
2274 Cut a piece of data into several lines.
2275 .Pp
2276 The argument
2277 .Fa data
2278 is a string or a list of strings. In any case, all strings are first splitted by
2279 spaces and trimmed. This ensure that useless whitespaces are discarded.
2280 .Pp
2281 The argument
2282 .Fa maxc
2283 controls the maximum of characters allowed per line, it can be a positive
2284 integer. If undefined is given, a default of 72 is used.
2285 .Pp
2286 The argument
2287 .Fa maxl
2288 controls the maximum of lines allowed. It can be a positive integer or undefined
2289 for an infinite list.
2290 .Pp
2291 If
2292 .Fa maxl
2293 is used as a limit and the data can not fit within the bounds,
2294 undefined is returned.
2295 .Pp
2296 An empty list may be returned if empty strings were found.
2297 .Pp
2298 Synopsis
2299 .Bd -literal -offset Ds
2300 lines = Irccd.Util.cut(data, maxc, maxl)
2301 .Ed
2302 .Pp
2303 Arguments
2304 .Pp
2305 .Bl -tag -width 20n -compact -offset Ds
2306 .It Fa data No (mixed)
2307 A string or an array of strings.
2308 .It Fa maxc No (int)
2309 Max number of colums (Optional, default: 72).
2310 .It Fa maxl No (int)
2311 Max number of lines (Optional, default: undefined).
2312 .El
2313 .Pp
2314 Throws
2315 .Pp
2316 .Bl -tag -width 20n -compact -offset Ds
2317 .It Va RangeError
2318 If maxl or maxc are negative numbers.
2319 .It Va RangeError
2320 If one word length was bigger than maxc.
2321 .It Va TypeError
2322 If data is not a string or a list of strings.
2323 .El
2324 .Pp
2325 Returns
2326 .Pp
2327 A list of strings ready to be sent or undefined if the data is too big.
2328 .Ed
2329 .\" }}}
2330 .\" {{{ Irccd.Util.format
2331 .Pp
2332 Irccd.Util.format
2333 .Bd -ragged -offset indent
2334 Format a string according to the template system.
2335 .Pp
2336 See the documentation about the template format in
2337 .Xr irccd-templates 7 .
2338 .Pp
2339 Synopsis
2340 .Bd -literal -offset Ds
2341 str = Irccd.Util.format(input, params)
2342 .Ed
2343 .Pp
2344 Arguments
2345 .Pp
2346 .Bl -tag -width 20n -compact -offset Ds
2347 .It Fa input No (string)
2348 The text to update.
2349 .It Fa params No (Object)
2350 The parameters. For each keyword you want to replace in the
2351 .Ar input ,
2352 add a new entry into the object. Note: the special
2353 .Va date
2354 object key is reserved and must be set to a timestamp if desired.
2355 .El
2356 .Pp
2357 Returns
2358 .Pp
2359 The converted text.
2360 .Pp
2361 Remarks
2362 .Pp
2363 Be very careful when you use this function with untrusted input. Do never pass
2364 untrusted content (e.g. user message) as input parameter.
2365 .Pp
2366 For example, the following code is unsafe:
2367 .Bd -literal -offset Ds
2368 function onMessage(server, channel, origin, message)
2369 {
2370 // DON'T DO THIS.
2371 server.message(channel, Irccd.Util.format("@{red}" + message + "@{}");
2372 }
2373 .Ed
2374 .Pp
2375 If a user sends a message like ${HOME}, it will prints the user home directory,
2376 which is a high security issue if you have environment variables with passwords.
2377 .Pp
2378 Instead, always use a literal string using a replacement with the user input:
2379 .Bd -literal -offset Ds
2380 function onMessage(server, channel, origin, message)
2381 {
2382 // CORRECT.
2383 server.message(channel, Irccd.Util.format("@{red}#{message}@{}", {
2384 message: message
2385 });
2386 }
2387 .Ed
2388 .Ed
2389 .\" }}}
2390 .\" {{{ Irccd.Util.splithost
2391 .Pp
2392 Irccd.Util.splithost
2393 .Bd -ragged -offset indent
2394 Extract the host from a user, for instance with foo!~foo@localhost,
2395 .Em localhost
2396 will be returned.
2397 .Pp
2398 Synopsis
2399 .Bd -literal -offset Ds
2400 hostname = Irccd.Util.splithost(user)
2401 .Ed
2402 .Pp
2403 Arguments
2404 .Pp
2405 .Bl -tag -width 20n -compact -offset Ds
2406 .It Fa user No (string)
2407 The user to split.
2408 .El
2409 .Pp
2410 Returns
2411 .Pp
2412 The host
2413 .Ed
2414 .\" }}}
2415 .\" {{{ Irccd.Util.splituser
2416 .Pp
2417 Irccd.Util.splituser
2418 .Bd -ragged -offset indent
2419 Extract the name from a user, for instance with foo!~bar@localhost,
2420 .Em foo
2421 will be returned.
2422 .Pp
2423 Synopsis
2424 .Bd -literal -offset Ds
2425 nick = Irccd.Util.splituser(user)
2426 .Ed
2427 .Pp
2428 Arguments
2429 .Pp
2430 .Bl -tag -width 20n -compact -offset Ds
2431 .It Fa user No (string)
2432 The user to split.
2433 .El
2434 .Pp
2435 Returns
2436 .Pp
2437 The nickname.
2438 .Ed
2439 .\" }}}
2440 .\" }}} !Functions
2441 .\" }}} !Module: Irccd.Util
2442 .\" SEE ALSO
2443 .Sh SEE ALSO
2444 .Xr irccd 1