Mercurial > irccd
diff man/irccd-api.7 @ 845:00a4720c4874
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 |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/irccd-api.7 Mon Jul 08 16:15:57 2019 +0200 @@ -0,0 +1,2444 @@ +.\" +.\" Copyright (c) 2013-2019 David Demelier <markand@malikania.fr> +.\" +.\" Permission to use, copy, modify, and/or distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd @IRCCD_MAN_DATE@ +.Dt IRCCD-API 7 +.Os +.\" NAME +.Sh NAME +.Nm irccd-api +.Nd irccd Javascript API +.\" DESCRIPTION +.Sh DESCRIPTION +This documentation shows the API reference for the official irccd Javascript +API. +.Pp +Any function that is indicated as +.Em optional +in square brackets means it may not exist on your platform. A quick check in +Javascript will let you test its presence. +.\" EVENTS +.Sh EVENTS +The following is a list of events that Javascript plugins support. All functions +are completely optional and may be omitted. If you want to support a function +just implement it as global Javascript function. +.\" onCommand +.Ss onCommand +Special commands are not real IRC events. They are called from channel messages +with a specific syntax using a delimiter and the plugin name. +.Pp +For instance, with default irccd parameters, saying on a channel +.Ar "!ask foo" +will call the special command of the plugin named +.Nm ask . +.Pp +Synopsis +.Bd -literal -offset Ds +function onCommand(server, origin, channel, message) +.Ed +.Pp +Arguments +.Bl -tag -width 20n -compact -offset Ds +.It Fa server No (Server) +The current server. +.It Fa origin No (string) +Who invoked the command. +.It Fa channel No (string) +The channel where the message comes from. +.It Fa message No (string) +The real message, without the ! part. +.El +.\" onConnect +.Ss onConnect +This callback is called when the irccd instance successfully connect to a +server. +.Pp +Synopsis +.Bd -literal -offset Ds +function onConnect(server) +.Ed +.Pp +Arguments +.Bl -tag -width 20n -compact -offset Ds +.It Fa server No (Server) +The current server. +.El +.\" onDisconnect +.Ss onDisconnect +This callback is called when a server has been disconnected by any way. +.Pp +Synopsis +.Bd -literal -offset Ds +function onDisonnect(server) +.Ed +.Pp +Arguments +.Bl -tag -width 20n -compact -offset Ds +.It Fa server No (Server) +The current server. +.El +.\" onInvite +.Ss onInvite +This event is called when someone is inviting you to a channel. +.Pp +Synopsis +.Bd -literal -offset Ds +function onInvite(server, origin, channel) +.Ed +.Pp +Arguments +.Bl -tag -width 20n -compact -offset Ds +.It Fa server No (Server) +The current server. +.It Fa origin No (string) +Who invited you. +.It Fa channel No (string) +On which channel you are invited to. +.El +.\" onJoin +.Ss onJoin +User join events, this function is called when someone joins a channel. +.Pp +Synopsis +.Bd -literal -offset Ds +function onJoin(server, origin, channel) +.Ed +.Pp +Arguments +.Bl -tag -width 20n -compact -offset Ds +.It Fa server No (Server) +The current server. +.It Fa origin No (string) +The person who joined the channel. +.It Fa channel No (string) +The channel the user has joined. +.El +.\" onKick +.Ss onKick +This event is triggered when someone has been kicked from a channel. +.Pp +Synopsis +.Bd -literal -offset Ds +function onKick(server, origin, channel, target, reason) +.Ed +.Pp +Arguments +.Bl -tag -width 20n -compact -offset Ds +.It Fa server No (Server) +The current server. +.It Fa origin No (string) +Who kicked the person. +.It Fa channel No (string) +The channel. +.It Fa target No (string) +The kicked person. +.It Fa reason No (string) +An optional reason. +.El +.\" onLoad +.Ss onLoad +This function is called when irccd instance load a plugin. If this function +throws an error, the script is not loaded. +.Pp +Synopsis +.Bd -literal -offset Ds +function onLoad() +.Ed +.\" onMe +.Ss onMe +Action emote. +.Pp +Synopsis +.Bd -literal -offset Ds +function onMe(server, origin, channel, message) +.Ed +.Pp +Arguments +.Bl -tag -width 20n -compact -offset Ds +.It Fa server No (Server) +The current server. +.It Fa origin No (string) +The person who said something. +.It Fa channel No (string) +The channel. +.It Fa message No (string) +The message sent. +.El +.\" onMessage +.Ss onMessage +This event is triggered when someone said something on a specific channel. +.Pp +Synopsis +.Bd -literal -offset Ds +function onMessage(server, origin, channel, message) +.Ed +.Pp +Arguments +.Bl -tag -width 20n -compact -offset Ds +.It Fa server No (Server) +The current server. +.It Fa origin No (string) +The person who said something. +.It Fa channel No (string) +The channel. +.It Fa message No (string) +The message sent. +.El +.\" onMode +.Ss onMode +This event is triggered when the server changed a channel mode or your mode. +.Pp +Synopsis +.Bd -literal -offset Ds +function onMode(server, origin, channel, mode, limit, user, mask) +.Ed +.Pp +Arguments +.Bl -tag -width 20n -compact -offset Ds +.It Fa server No (Server) +The current server. +.It Fa origin No (string) +The person who changed the mode. +.It Fa mode No (string) +The new mode. +.El +.\" onNames +.Ss onNames +This event is triggered when a list of names has come. +.Pp +Synopsis +.Bd -literal -offset Ds +function onNames(server, channel, list) +.Ed +.Pp +Arguments +.Bl -tag -width 20n -compact -offset Ds +.It Fa server No (Server) +The current server. +.It Fa channel No (string) +Which channel. +.It Fa list No (string) +A sequence with all users. +.El +.\" onNick +.Ss onNick +This event is triggered when someone changed its nickname. +.Pp +Synopsis +.Bd -literal -offset Ds +function onNick(server, origin, nickname) +.Ed +.Pp +Arguments +.Bl -tag -width 20n -compact -offset Ds +.It Fa server No (Server) +The current server. +.It Fa origin No (string) +The old nickname. +.It Fa nickname No (string) +The new nickname. +.El +.\" onNotice +.Ss onNotice +This event is triggered when someone sent a notice to you. +.Pp +Synopsis +.Bd -literal -offset Ds +function onNotice(server, origin, notice) +.Ed +.Pp +Arguments +.Bl -tag -width 20n -compact -offset Ds +.It Fa server No (Server) +The current server. +.It Fa origin No (string) +The one who sent the notice. +.It Fa message No (string) +The notice message. +.El +.\" onPart +.Ss onPart +This event is triggered when someone has left a specific channel. +.Pp +Synopsis +.Bd -literal -offset Ds +function onPart(server, origin, channel, reason) +.Ed +.Pp +Arguments +.Bl -tag -width 20n -compact -offset Ds +.It Fa server No (Server) +The current server. +.It Fa origin No (string) +The person who left the channel. +.It Fa channel No (string) +The channel. +.It Fa reason No (string) +An optional reason. +.El +.\" onReload +.Ss onReload +Request to reload the plugin. +.Pp +This function does nothing in the irccd internals, it just calls a function that +you can use to reload some data. +.Pp +Synopsis +.Bd -literal -offset Ds +function onReload() +.Ed +.\" onTopic +.Ss onTopic +This event is triggered when someone changed the channel's topic. +.Pp +Synopsis +.Bd -literal -offset Ds +function onTopic(server, origin, channel, topic) +.Ed +.Pp +Arguments +.Bl -tag -width 20n -compact -offset Ds +.It Fa server No (Server) +The current server. +.It Fa origin No (string) +The person who changed the topic. +.It Fa channel No (string) +The channel. +.It Fa topic No (string) +The new topic (may be empty). +.El +.\" onUnload +.Ss onUnload +This event is triggered when the plugin is about to be unloaded. +.Pp +Synopsis +.Bd -literal -offset Ds +function onUnload() +.Ed +.\" onWhois +.Ss onWhois +This event is triggered when irccd gets information about a user. +.Pp +Synopsis +.Bd -literal -offset Ds +function onWhois(server, info) +.Ed +.Pp +Arguments +.Bl -tag -width 20n -compact -offset Ds +.It Fa server No (Server) +The current server. +.It Fa info No (Object) +The whois information. +.El +.Pp +The +.Fa info +is an object with the following properties: +.Bl -tag -width 20n -compact -offset Ds +.It Fa nickname No (string) +The user nickname. +.It Fa user No (string) +The user name. +.It Fa host No (string) +The hostname. +.It Fa realname No (string) +The real name used. +.It Fa channels No (array) +An optional list of channels joined. +.El +.\" MODULES +.Sh MODULES +The following modules are part of the official Javascript API. They are all +accessible as global function, variables and objects. +.Pp +All modules are categorized into pseudo namespaces that are placed into the +global +.Va Irccd +object. (e.g. +.Va Irccd.Directory , Irccd.File ) . +.\" {{{ Module: Irccd +.Ss Irccd +Top level irccd Javascript module. +.Pp +Contains general irccd variables and functions. +.Pp +.\" {{{ Constants +The following constants properties are defined: +.Pp +.Bl -tag -width 22n -compact -offset Ds +.It Va version No (object) +See below. +.It Va version.major No (int) +The major irccd version. +.It Va version.minor No (int) +The minor irccd version. +.It Va version.patch No (int) +The patch irccd version. +.El +.Pp +.\" }}} !Constants +.\" {{{ Types +The following objects are defined: +.Bl -tag -width 22n -compact -offset Ds +.It Va SystemError No (function) +An exception inheriting Error thrown by some filesystem functions. +.El +.\" }}} !Types +.\" }}} !Module: Irccd +.\" {{{ Module: Irccd.Chrono +.Ss Irccd.Chrono +This class let you measure the elapsed time. +.\" {{{ Methods +.\" {{{ Irccd.Chrono [constructor] +.Pp +Irccd.Chrono [constructor] +.Bd -ragged -offset indent +Construct a new Chrono object. The timer is automatically started on +construction. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.ElapsedTimer() +.Ed +.Ed +.\" }}} +.\" {{{ Irccd.Chrono.prototype.elapsed +.Pp +Irccd.Chrono.prototype.elapsed +.Bd -ragged -offset indent +Get the number of elapsed milliseconds. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Chrono.prototype.elapsed() +.Ed +.Pp +Returns +.Pp +The elapsed time in milliseconds. +.Ed +.\" }}} +.\" {{{ Irccd.Chrono.prototype.pause +.Pp +Irccd.Chrono.prototype.pause +.Bd -ragged -offset indent +Pause the timer, without resetting the current elapsed time stored. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Chrono.prototype.pause() +.Ed +.Ed +.\" }}} +.\" {{{ Irccd.Chrono.prototype.resume +.Pp +Irccd.Chrono.prototype.resume +.Bd -ragged -offset indent +Continue accumulating additional time. Has no effect if the timer is already +running. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Chrono.prototype.restart() +.Ed +.Ed +.\" }}} +.\" {{{ Irccd.Chrono.prototype.start +.Pp +Irccd.Chrono.prototype.start +.Bd -ragged -offset indent +Starts or restarts accumulating time. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Chrono.prototype.start() +.Ed +.Ed +.\" }}} +.\" }}} +.\" }}} !Module: Irccd.Chrono +.\" {{{ Module: Irccd.Directory +.Ss Irccd.Directory +This module can be used to iterate, find, remove or create directories. +.Pp +Use this module with care. +.Pp +.\" {{{ Constants +The following constants properties are defined: +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Va Dot No (int) +list "." directory. +.It Va DotDot No (int) +list ".." directory. +.It Va TypeUnknown No (int) +unknown type file. +.It Va TypeDir No (int) +entry is a directory. +.It Va TypeFile No (int) +entry is a file. +.It Va TypeLink No (int) +entry is a link. +.El +.\" }}} !Constants +.\" {{{ Functions +.\" {{{ Irccd.Directory.find +.Pp +Irccd.Directory.find +.Bd -ragged -offset indent +.Pp +Find an entry by a pattern or a regular expression. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Directory.find(path, pattern, recursive) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa path No (string) +The base path. +.It Fa pattern No (mixed) +The regular expression or file name as string. +.It Fa recursive No (bool) +Set to true to search recursively (Optional, default: false). +.El +.Pp +Returns +.Pp +The path to the file or undefined if not found. +.Ed +.\" }}} +.\" {{{ Irccd.Directory.mkdir +.Pp +Irccd.Directory.mkdir +.Bd -ragged -offset indent +Create a directory specified by path. It will create needed subdirectories just +like you have invoked mkdir -p. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Directory.mkdir(path, mode = 0700) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa path No (string) +The path to the directory. +.It Fa mode No (string) +The mode, not available on all platforms. +.El +.Pp +Throws +.Pp +Any exception on error. +.Ed +.\" }}} +.\" {{{ Irccd.Directory.remove +.Pp +Irccd.Directory.remove +.Bd -ragged -offset indent +Remove the directory optionally recursively. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Directory.remove(path, recursive) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa path No (string) +The path to the directory. +.It Fa recursive No (bool) +Recursively or not (Optional, default: false). +.El +.Pp +Throws +.Pp +Any exception on error. +.Ed +.\" }}} +.\" }}} !Functions +.\" {{{ Methods +.\" {{{ Irccd.Directory [constructor] +.Pp +Irccd.Directory [constructor] +.Bd -ragged -offset indent +Open a directory. +.Pp +When constructed successfully, the object has the following properties: +.Pp +.Bl -tag -width 20n -offset indent -compact +.It Va path No (string) +the path to the directory. +.It Va entries No (array) +an array for each entry containing. See below +.El +.Pp +For each entry found, the array entries contains as many objects with the +following properties: +.Pp +.Bl -tag -width 14n -offset indent-two -compact +.It Va name No (string) +the base file name. +.It Va type No (int) +the type of file (Irccd.Directory.Type*). +.El +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Directory(path, flags) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa path No (string) +The path to the directory. +.It Va flags No (int) +The OR'ed flags: +.Va Irccd.Directory.Dot , Irccd.Directory.DotDot +(Optional, default: none). +.El +.Pp +Throws +.Pp +Any exception on error. +.Ed +.\" }}} +.\" {{{ Irccd.Directory.prototype.find +.Pp +Irccd.Directory.prototype.find +.Bd -ragged -offset indent +Synonym of find static function but the path is taken from the directory object. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Directory.prototype.find(pattern, recursive) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa pattern No (mixed) +The regular expression or file name. +.It Fa recursive No (bool) +Set to true to search recursively (Optional, default: false). +.El +.Pp +Throws +.Pp +Any exception on error. +.Pp +Returns +.Pp +The path to the file or undefined if not found. +.Ed +.\" }}} +.\" {{{ Irccd.Directory.prototype.remove +.Pp +Irccd.Directory.prototype.remove +.Bd -ragged -offset indent +Synonym of remove static function but the path is taken from the directory +object. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Directory.prototype.remove(recursive) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa recursive No (bool) +Recursively or not (Optional, default: false). +.El +.Pp +Throws +.Pp +Any exception on error. +.Ed +.\" }}} +.\" }}} !Methods +.\" }}} !Module: Irccd.Directory +.\" {{{ Module: Irccd.File +.Ss Irccd.File +This module is available for opening and writing files on the disk. +.Pp +For convenience, some functions are available as free-functions and some as +object methods. +.\" {{{ Constants +The following constants properties are defined: +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Va SeekCur No (int) +Seek from the current file position. +.It Va SeekEnd No (int) +Seek from end of the file. +.It Va SeekSet No (int) +Seek from beginning of the file. +.El +.\" }}} !Constants +.\" {{{ Functions +.\" {{{ Irccd.File.basename +.Pp +Irccd.File.basename +.Bd -ragged -offset indent +Return the file basename as specified in basename C function. +.Pp +Synopsis +.Bd -literal -offset Ds +base = Irccd.File.basename(path) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa path No (string) +The path to the file. +.El +.Pp +Returns +.Pp +The base name. +.Ed +.\" }}} +.\" {{{ Irccd.File.dirname +.Pp +Irccd.File.dirname +.Bd -ragged -offset indent +Return the file directory name as specified in dirname C function. +.Pp +Synopsis +.Bd -literal -offset Ds +path = Irccd.File.dirname(path) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa path No (string) +The path to the file. +.El +.Pp +Returns +.Pp +The directory name. +.Ed +.\" }}} +.\" {{{ Irccd.File.exists +.Pp +Irccd.File.exists +.Bd -ragged -offset indent +Check if the file exists. +.Pp +Warning: using this function is usually discouraged as it may introduce a +possible race condition. +.Pp +Synopsis +.Bd -literal -offset Ds +ret = Irccd.File.exists(path) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa path No (string) +The path to the file. +.El +.Pp +Throws +.Pp +Irccd.SystemError on failure. +.Pp +Returns +.Pp +True if exists. +.Ed +.\" }}} +.\" {{{ Irccd.File.remove +.Pp +Irccd.File.remove +.Bd -ragged -offset indent +Remove the file at the specified path. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.File.remove(path) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa path No (string) +The path to the file. +.El +.Pp +Throws +.Pp +Irccd.SystemError on failure. +.Ed +.\" }}} +.\" {{{ Irccd.File.stat +.Pp +Irccd.File.stat [optional] +.Bd -ragged -offset indent +Get file information at the specified path. +.Pp +Synopsis +.Bd -literal -offset Ds +info = Irccd.File.stat(path) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa path No (string) +The path to the file. +.El +.Pp +Throws +.Pp +Irccd.SystemError on failure. +.Pp +Returns +.Pp +An object with the following properties. Not all properties are available and +you must check its presence before using it. +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Va atime No (int) +The last access time. +.It Va blksize No (int) +The block size. +.It Va blocks No (int) +The number of blocks. +.It Va ctime No (int) +The creation time. +.It Va dev No (int) +The device. +.It Va gid No (int) +The group numeric id. +.It Va ino No (int) +The inode. +.It Va mode No (int) +The mode. +.It Va mtime No (int) +The modification time. +.It Va nlink No (int) +The number of hard links. +.It Va rdev No (int) +No description available. +.It Va size No (int) +The file size. +.It Va uid No (int) +The user numeric id. +.El +.Ed +.\" }}} +.\" }}} !Functions +.\" {{{ Methods +.\" {{{ Irccd.File [constructor] +.Pp +Irccd.File [constructor] +.Bd -ragged -offset indent +Open a file specified by path with the specified mode. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.File(path, mode) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa path No (string) +The path to the file. +.It Fa mode No (string) +The mode string. +.El +.Pp +The +.Fa mode +is the same as if called by fopen, see the documentation of +.Xr fopen 3 +for more information about modes. +.Pp +Throws +.Pp +Irccd.SystemError on failure. +.Ed +.\" }}} +.\" {{{ Irccd.File.prototype.basename +.Pp +Irccd.File.prototype.basename +.Bd -ragged -offset indent +Synonym of Irccd.File.basename static function but with the path taken from the +object itself. +.Pp +Synopsis +.Bd -literal -offset Ds +path = Irccd.File.prototype.basename() +.Ed +.Pp +Returns +.Pp +The base name. +.Ed +.\" }}} +.\" {{{ Irccd.File.prototype.close +.Pp +Irccd.File.prototype.close +.Bd -ragged -offset indent +Force close of the file, automatically called when object is collected. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.File.prototype.close() +.Ed +.Ed +.\" }}} +.\" {{{ Irccd.File.prototype.dirname +.Pp +Irccd.File.prototype.dirname +.Bd -ragged -offset indent +Synonym of Irccd.File.dirname static function but with the path taken from the +object itself. +.Pp +Synopsis +.Bd -literal -offset Ds +path = Irccd.File.prototype.dirname() +.Ed +.Pp +Returns +.Pp +The directory name. +.Ed +.\" }}} +.\" {{{ Irccd.File.prototype.lines +.Pp +Irccd.File.prototype.lines +.Bd -ragged -offset indent +Read all lines and return an array. +.Pp +Synopsis +.Bd -literal -offset Ds +list = Irccd.File.prototype.lines() +.Ed +.Pp +Throws +.Pp +Irccd.SystemError on failure. +.Pp +Returns +.Pp +An array with all lines. +.Ed +.\" }}} +.\" {{{ Irccd.File.prototype.read +.Pp +Irccd.File.prototype.read +.Bd -ragged -offset indent +Read the specified amount of characters or the whole file. +.Pp +Synopsis +.Bd -literal -offset Ds +str = Irccd.File.prototype.read(amount) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa amount No (int) +The amount of characters or -1 to read all (Optional, default: -1). +.El +.Pp +Throws +.Pp +Irccd.SystemError on failure. +.Pp +Returns +.Pp +The string. +.Ed +.\" }}} +.\" {{{ Irccd.File.prototype.readline +.Pp +Irccd.File.prototype.readline +.Bd -ragged -offset indent +Read the next line available. +.Pp +Warning: this method is slow and its usage is discouraged on large files. +Consider using Irccd.File.prototype.lines function if you want to read a file +line per line. +.Pp +Synopsis +.Bd -literal -offset Ds +line = Irccd.File.prototype.readline() +.Ed +.Pp +Throws +.Pp +Irccd.SystemError on failure. +.Pp +Returns +.Pp +The next line or undefined if EOF. +.Ed +.\" }}} +.\" {{{ Irccd.File.prototype.remove +.Pp +Irccd.File.prototype.remove +.Bd -ragged -offset indent +Synonym of Irccd.File.remove static function but with the path taken from the +object itself. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.File.prototype.remove() +.Ed +.Pp +Throws +.Pp +Irccd.SystemError on failure. +.Ed +.\" }}} +.\" {{{ Irccd.File.prototype.seek +.Pp +Irccd.File.prototype.seek +.Bd -ragged -offset indent +Sets the position in the file. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.File.prototype.seek(type, amount) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa type No (int) +The type of setting +.Fa ( Irccd.File.SeekSet , Irccd.File.SeekCur , Irccd.File.SeekSet ) . +.It Fa amount No (int) +The new offset. +.El +.Pp +Throws +.Pp +Irccd.SystemError on failure. +.Ed +.\" }}} +.\" {{{ Irccd.File.prototype.stat +.Pp +Irccd.File.prototype.stat [optional] +.Bd -ragged -offset indent +Synonym of Irccd.File.stat static function but with the path taken from the +object itself. +.Pp +Synopsis +.Bd -literal -offset Ds +info = Irccd.File.prototype.stat() +.Ed +.Pp +Throws +.Pp +Irccd.SystemError on failure. +.Pp +Returns +.Pp +The information object. +.Ed +.\" }}} +.\" {{{ Irccd.File.prototype.tell +.Pp +Irccd.File.prototype.tell +.Bd -ragged -offset indent +Get the actual position in the file. +.Pp +Synopsis +.Bd -literal -offset Ds +pos = Irccd.File.prototype.tell() +.Ed +.Pp +Throws +.Pp +Irccd.SystemError on failure. +.Pp +Returns +.Pp +The position. +.Ed +.\" }}} +.\" {{{ Irccd.File.prototype.write +.Pp +Irccd.File.prototype.write +.Bd -ragged -offset indent +Write some characters to the file. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.File.prototype.write(data) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa data No (string) +The character to write. +.El +.Pp +Throws +.Pp +Irccd.SystemError on failure. +.Pp +Returns +.Pp +The number of bytes written. +.Ed +.\" }}} +.\" }}} !Methods +.\" }}} !Module: Irccd.File +.\" {{{ Module: Irccd.Logger +.Ss Irccd.Logger +This module must be used to log something. It will add messages to the logging +system configured in the irccd.conf file. +.Pp +For instance, if user has chosen to log into syslog, this module will log at +syslog too. +.Pp +Any plugin can log messages, the message will be prepended by the plugin name to +be easily identifiable. +.\" {{{ Functions +.\" {{{ Irccd.Logger.debug +.Pp +Irccd.Logger.debug +.Bd -ragged -offset indent +Adds a debug message, this is only appended to the journal if irccd was compiled +in Debug mode. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Logger.debug(message) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa message No (string) +The message. +.El +.Ed +.\" }}} +.\" {{{ Irccd.Logger.info +.Pp +Irccd.Logger.info +.Bd -ragged -offset indent +Log something. The message is logged only if irccd is running with verbose +messages enabled. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Logger.info(message) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa message No (string) +The message. +.El +.Ed +.\" }}} +.\" {{{ Irccd.Logger.warning +.Pp +Irccd.Logger.warning +.Bd -ragged -offset indent +Log a warning. The message will always be logged. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Logger.warning(message) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa message No (string) +The message. +.El +.Ed +.\" }}} +.\" }}} !Functions +.\" }}} !Module: Irccd.Logger +.\" {{{ Module: Irccd.Plugin +.Ss Irccd.Plugin +This module let you manage plugins. +.Pp +.\" {{{ Constants +The following constants properties are defined and contain each key-value pairs +from the user configuration file. +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Va config No (Object) +Contains the +.Va [plugin.<name>] +section. +.It Va paths No (Object) +Contains the +.Va [paths.<name>] +section. +.It Va templates No (Object) +Contains the +.Va [format.<name>] +section. +.El +.\" }}} !Constants +.\" {{{ Functions +.\" {{{ Irccd.Plugin.info +.Pp +Irccd.Plugin.info +.Bd -ragged -offset indent +Get information about a plugin. +.Pp +Synopsis +.Bd -literal -offset Ds +info = Irccd.Plugin.info(name) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa name No (string) +The plugin identifier, if not specified the current plugin is selected. +.El +.Pp +Returns +.Pp +The plugin information or undefined if the plugin was not found. The object has +the following properties: +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Va name No (string) +The plugin identifier. +.It Va author No (string) +The author. +.It Va license No (string) +The license. +.It Va summary No (string) +A short description. +.It Va version No (string) +The version. +.El +.Ed +.\" }}} +.\" {{{ Irccd.Plugin.list +.Pp +Irccd.Plugin.list +.Bd -ragged -offset indent +Get the list of plugins, the array returned contains all plugin names as +strings. +.Pp +Synopsis +.Bd -literal -offset Ds +list = Irccd.Plugin.list() +.Ed +.Pp +Returns +.Pp +The list of all plugin names. +.Ed +.\" }}} +.\" {{{ Irccd.Plugin.load +.Pp +Irccd.Plugin.load +.Bd -ragged -offset indent +Load a plugin by name. This function will search through the standard +directories. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Plugin.load(name) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa name No (string) +The plugin identifier. +.El +.Pp +Throws +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Va Error +On errors. +.It Va ReferenceError +If the plugin was not found. +.El +.Ed +.\" }}} +.\" {{{ Irccd.Plugin.reload +.Pp +Irccd.Plugin.reload +.Bd -ragged -offset indent +Reload a plugin by name. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Plugin.reload(name) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa name No (string) +The plugin identifier. +.El +.Pp +Throws +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Va Error +On errors. +.It Va ReferenceError +If the plugin was not found. +.El +.Ed +.\" }}} +.\" {{{ Irccd.Plugin.unload +.Pp +Irccd.Plugin.unload +.Bd -ragged -offset indent +Unload a plugin by name and remove it. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Plugin.unload(name) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa name No (string) +The plugin identifier. +.El +.Pp +Throws +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Va Error +On errors. +.It Va ReferenceError +If the plugin was not found. +.El +.Ed +.\" }}} +.\" }}} !Functions +.\" }}} !Module: Irccd.Plugin +.\" {{{ Module: Irccd.Server +.Ss Irccd.Server +This module is the object that you received in almost all IRC event +(e.g. onConnect). You can use its methods to do your required actions on the +server. +.\" {{{ Functions +.\" {{{ Irccd.Server.add +.Pp +Irccd.Server.add +.Bd -ragged -offset indent +Add a new server to the irccd instance. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Server.add(server) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa server No (Server) +The server object to add. +.El +.Ed +.\" }}} +.\" {{{ Irccd.Server.find +.Pp +Irccd.Server.find +.Bd -ragged -offset indent +Find a server by name. +.Pp +Synopsis +.Bd -literal -offset Ds +server = Irccd.Server.find(name) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa name No (string) +The server name. +.El +.Pp +Returns +.Pp +The server object or undefined if not found. +.Ed +.\" }}} +.\" {{{ Irccd.Server.list +.Pp +Irccd.Server.list +.Bd -ragged -offset indent +List all servers in a map. +.Pp +Synopsis +.Bd -literal -offset Ds +table = Irccd.Server.list() +.Ed +.Pp +Returns +.Pp +The table of all servers as key-value pairs where key is the server identifier +and value the object itself. +.Ed +.\" }}} +.\" {{{ Irccd.Server.remove +.Pp +Irccd.Server.remove +.Bd -ragged -offset indent +Remove a server from the irccd instance and disconnect it. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Server.remove(name) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa name No (string) +The server name. +.El +.Ed +.\" }}} +.\" }}} !Functions +.\" {{{ Methods +.\" {{{ Irccd.Server [constructor] +.Pp +Irccd.Server [constructor] +.Bd -ragged -offset indent +Construct a new server. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Server(info) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa info No (object) +Object information. +.El +.Pp +The +.Fa info +argument may have the following properties: +.Bl -tag -width 20n -compact -offset Ds +.It Fa name No (string) +The unique identifier name. +.It Fa hostname No (string) +The host or IP address. +.It Fa ipv4 No (bool) +Enable ipv4 (Optional, default: true). +.It Fa ipv6 No (bool) +Enable ipv6, (Optional, default: true). +.It Fa port No (int) +The port number, (Optional, default: 6667). +.It Fa password No (string) +The password, (Optional, default: undefined). +.It Fa channels No (array) +Array of channels (Optional, default: empty). +.It Fa ssl No (bool) +True to use ssl, (Optional, default: false). +.It Fa nickname No (string) +Nickname, (Optional, default: irccd). +.It Fa username No (string) +User name, (Optional, default: irccd). +.It Fa realname No (string) +Real name, (Optional, default: IRC Client Daemon). +.It Fa commandChar No (string) +Plugin prefix character, (Optional, default: "!"). +.El +.Pp +Warning: at least ipv4 and ipv6 must be set (which is the default). +.Ed +.\" }}} +.\" {{{ Irccd.Server.prototype.info +.Pp +Irccd.Server.prototype.info +.Bd -ragged -offset indent +Get server information. +.Pp +Synopsis +.Bd -literal -offset Ds +info = Irccd.Server.prototype.info() +.Ed +.Pp +Returns +.Pp +The server information. The object have the following properties: +.Bl -tag -width 20n -compact -offset Ds +.It Va name No (string) +The server unique name. +.It Va hostname No (string) +The host name. +.It Va port No (int) +The port number. +.It Va ssl No (bool) +True if using ssl. +.It Va channels No (array) +An array of all channels. +.It Va realname No (string) +The current real name. +.It Va username No (string) +The user name. +.It Va nickname No (string) +The current nickname. +.El +.Ed +.\" }}} +.\" {{{ Irccd.Server.prototype.invite +.Pp +Irccd.Server.prototype.invite +.Bd -ragged -offset indent +Invite the specified target on the channel. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Server.prototype.invite(target, channel) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa target No (string) +The target to invite. +.It Fa channel No (string) +The channel. +.El +.Ed +.\" }}} +.\" {{{ Irccd.Server.prototype.isSelf +.Pp +Irccd.Server.prototype.isSelf +.Bd -ragged -offset indent +Check if the nickname targets the bot. +.Pp +Synopsis +.Bd -literal -offset Ds +res = Server.prototype.isSelf(nickname) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa nickname No (string) +The nickname to check. +.El +.Pp +Returns +.Pp +True if nickname is same as the bot. +.Ed +.\" }}} +.\" {{{ Irccd.Server.prototype.join +.Pp +Irccd.Server.prototype.join +.Bd -ragged -offset indent +Join the specified channel, the password is optional. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Server.prototype.join(channel, password) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa channel No (string) +The channel to join. +.It Fa password No (string) +An optional password. +.El +.Ed +.\" }}} +.\" {{{ Irccd.Server.prototype.kick +.Pp +Irccd.Server.prototype.kick +.Bd -ragged -offset indent +Kick the specified target from the channel, the reason is optional. +.Pp +Synopsis +.Bd -literal -offset Ds +Server.prototype.kick(nickname, channel, reason) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa nickname No (string) +The person to kick. +.It Fa channel No (string) +From which channel. +.It Fa reason No (string) +A reason (Optional, default: undefined). +.El +.Ed +.\" }}} +.\" {{{ Irccd.Server.prototype.me +.Pp +Irccd.Server.prototype.me +.Bd -ragged -offset indent +Send an action emote. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Server.prototype.me(target, message) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa target No (string) +A nick or a channel. +.It Fa message No (string) +The message to send. +.El +.Ed +.\" }}} +.\" {{{ Irccd.Server.prototype.message +.Pp +Irccd.Server.prototype.message +.Bd -ragged -offset indent +Send a message to the specified target or channel. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Server.prototype.message(target, message) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa target No (string) +The target. +.It Fa message No (string) +The message to send. +.El +.Ed +.\" }}} +.\" {{{ Irccd.Server.prototype.mode +.Pp +Irccd.Server.prototype.mode +.Bd -ragged -offset indent +Change irccd's user mode or a channel mode. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Server.prototype.mode(channel, mode, limit, user, mode) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa channel No (string) +A channel or your nicknam. +.It Fa mode No (string) +The new mode. +.It Fa limit No (string) +An optional limit. +.It Fa user No (string) +An optional use. +.It Fa mask No (string) +An optional mas. +.El +.Ed +.\" }}} +.\" {{{ Irccd.Server.prototype.names +.Pp +Irccd.Server.prototype.names +.Bd -ragged -offset indent +Get the list of names. This function will generate the onNames event. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Server.prototype.names(channel) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa channel No (string) +The channel name. +.El +.Ed +.\" }}} +.\" {{{ Irccd.Server.prototype.nick +.Pp +Irccd.Server.prototype.nick +.Bd -ragged -offset indent +Change irccd's nickname. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Server.prototype.nick(nickname) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa nickname No (string) +The new nickname. +.El +.Ed +.\" }}} +.\" {{{ Irccd.Server.prototype.notice +.Pp +Irccd.Server.prototype.notice +.Bd -ragged -offset indent +Send a private notice to the specified target. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Server.prototype.notice(nickname, message) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa nickname No (string) +The target nickname. +.It Fa message No (string) +The notice message. +.El +.Ed +.\" }}} +.\" {{{ Irccd.Server.prototype.part +.Pp +Irccd.Server.prototype.part +.Bd -ragged -offset indent +Leave the specified channel, the reason is optional. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Server.prototype.part(channel, reason) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa channel No (string) +The channel to leave. +.It Fa reason No (string) +A reason (Optional, default: undefined). +.El +.Ed +.\" }}} +.\" {{{ Irccd.Server.prototype.toString +.Pp +Irccd.Server.prototype.toString +.Bd -ragged -offset indent +Convert object as a string. +.Pp +Because each server has a unique identifier, this method allows adding a server +a property key. +.Pp +Synopsis +.Bd -literal -offset Ds +id = Irccd.Server.prototype.toString() +.Ed +.Pp +Returns +.Pp +The server identifier. +.Ed +.\" }}} +.\" {{{ Irccd.Server.prototype.topic +.Pp +Irccd.Server.prototype.topic +.Bd -ragged -offset indent +Change the topic of the specified channel. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Server.prototype.topic(channel, topic) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa channel No (string) +The channel. +.It Fa topic No (string) +The new topic. +.El +.Ed +.\" }}} +.\" {{{ Irccd.Server.prototype.whois +.Pp +Irccd.Server.prototype.whois +.Bd -ragged -offset indent +Get whois information from a user. The function will generate onWhois event. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Server.prototype.whois(target) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa target No (string) +The target. +.El +.Ed +.\" }}} +.\" }}} !Methods +.\" }}} !Module: Irccd.Server +.\" {{{ Module: Irccd.System +.Ss Irccd.System +System inspection. +.Pp +Use this module if you want to inspect the system independently. +.\" {{{ Functions +.\" {{{ Irccd.System.env +.Pp +Irccd.System.env +.Bd -ragged -offset indent +Get a environment variable. +.Pp +Synopsis +.Bd -literal -offset Ds +value = Irccd.System.env(name) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa name No (string) +The environment variable name. +.El +.Pp +Returns +.Pp +The variable or an empty string. +.Ed +.\" }}} +.\" {{{ Irccd.System.exec +.Pp +Irccd.System.exec +.Bd -ragged -offset indent +Execute a system command. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.System.exec(cmd) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa cmd No (string) +The command to execute. +.El +.Ed +.\" }}} +.\" {{{ Irccd.System.home +.Pp +Irccd.System.home +.Bd -ragged -offset indent +Get the home directory. This function should be used with care, plugin should +not use user's home to store files. +.Pp +Synopsis +.Bd -literal -offset Ds +home = Irccd.System.home() +.Ed +.Pp +Returns +.Pp +The user home directory. +.Ed +.\" }}} +.\" {{{ Irccd.System.name +.Pp +Irccd.System.name +.Bd -ragged -offset indent +Get the operating system name. Returns one of: +.Pp +.Bl -bullet -compact +.It +Linux +.It +Windows +.It +FreeBSD +.It +DragonFlyBSD +.It +OpenBSD +.It +NetBSD +.It +macOS +.It +Android +.It +Aix +.It +Haiku +.It +iOS +.It +Solaris +.It +Unknown +.El +.Pp +Synopsis +.Bd -literal -offset Ds +name = Irccd.System.name() +.Ed +.Pp +Returns +.Pp +The operating system name. +.Ed +.\" }}} +.\" {{{ Irccd.System.popen [optional] +.Pp +Irccd.System.popen [optional] +.Bd -ragged -offset indent +Wrapper for +.Xr popen 3 +if the function is available. +.Pp +Synopsis +.Bd -literal -offset Ds +handle = Irccd.System.popen(cmd, mode) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa cmd No (string) +The command to execute. +.It Fa mode No (string) +The mode (e.g. r). +.El +.Pp +Throws +.Pp +Irccd.SystemError on failure. +.Pp +Returns +.Pp +An Irccd.File object. +.Ed +.\" }}} +.\" {{{ Irccd.System.sleep +.Pp +Irccd.System.sleep +.Bd -ragged -offset indent +Sleep for seconds. Suspend the execution thread. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.System.sleep(sec) +.Ed +.Ed +.\" }}} +.\" {{{ Irccd.System.ticks +.Pp +Irccd.System.ticks +.Bd -ragged -offset indent +Get the time spent from start. Get how many milliseconds spent since the irccd +startup. +.Pp +Synopsis +.Bd -literal -offset Ds +msec = Irccd.System.ticks() +.Ed +.Pp +Returns +.Pp +The number of milliseconds. +.Ed +.\" }}} +.\" {{{ Irccd.System.uptime +.Pp +Irccd.System.uptime +.Bd -ragged -offset indent +Get the system uptime. This function returns the number of seconds elapsed since +the system boot up. +.Pp +Synopsis +.Bd -literal -offset Ds +secs = Irccd.System.uptime() +.Ed +.Pp +Returns +.Pp +The number of seconds. +.Ed +.\" }}} +.\" {{{ Irccd.System.usleep +.Pp +Irccd.System.usleep +.Bd -ragged -offset indent +Sleep for milliseconds. Suspend the execution thread. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.System.usleep(msec) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa msec No (int) +The number of milliseconds. +.El +.Ed +.\" }}} +.\" {{{ Irccd.System.version +.Pp +Irccd.System.version +.Bd -ragged -offset indent +Get the operating system version. Result of this function is system dependant. +.Pp +Synopsis +.Bd -literal -offset Ds +version = Irccd.System.version() +.Ed +.Pp +Returns +.Pp +The version as a string. +.Ed +.\" }}} +.\" }}} !Functions +.\" }}} !Module: Irccd.System +.\" {{{ Module: Irccd.Timer +.Ss Irccd.Timer +Create repetitive or one-shot timers. +.Pp +.\" {{{ Constants +The following constants properties are defined: +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Va Single No (int) +The timer is single-shot. +.It Va Repeat No (int) +The timer is looping. +.El +.\" }}} +.\" {{{ Methods +.\" {{{ Irccd.Timer [constructor] +.Pp +Irccd.Timer [constructor] +.Bd -ragged -offset indent +Create a new timer object but do not start it immediately. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Timer(type, delay, callback) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa type No (int) +Type of timer ( +.Fa Irccd.Timer.Repeat +or +.Fa Irccd.Timer.Single ) . +.It Fa delay No (int) +The interval in milliseconds. +.It Fa callback No (function) +The function to call. +.El +.Pp +Example: +.Bd -literal -offset Ds +var t = new Irccd.Timer(Irccd.Timer.Repeat, 1000, function () { + // Do your action, this will be called every 1 second. +}); +.Ed +.Ed +.\" }}} +.\" {{{ Irccd.Timer.prototype.start +.Pp +Irccd.Timer.prototype.start +.Bd -ragged -offset indent +Start the timer. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Timer.prototype.start() +.Ed +.Ed +.\" }}} +.\" {{{ Irccd.Timer.prototype.stop +.Pp +Irccd.Timer.prototype.stop +.Bd -ragged -offset indent +Stop the timer. +.Pp +Synopsis +.Bd -literal -offset Ds +Irccd.Timer.prototype.stop() +.Ed +.Ed +.\" }}} +.\" }}} !Methods +.\" }}} !Module: Irccd.Timer +.\" {{{ Module: Irccd.Unicode +.Ss Irccd.Unicode +Check for character categories. +.\" {{{ Functions +.\" {{{ Irccd.Unicode.isDigit +.Pp +Irccd.Unicode.isDigit +.Bd -ragged -offset indent +Check if the unicode character is a digit. +.Pp +Synopsis +.Bd -literal -offset Ds +ret = Irccd.Unicode.isDigit(code) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa code No (string) +The code point. +.El +.Pp +Returns +.Pp +True if digit. +.Ed +.\" }}} +.\" {{{ Irccd.Unicode.isLetter +.Pp +Irccd.Unicode.isLetter +.Bd -ragged -offset indent +Check if the unicode character is a letter. +.Pp +Synopsis +.Bd -literal -offset Ds +ret = Irccd.Unicode.isLetter(code) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa code No (string) +The code point. +.El +.Pp +Returns +.Pp +True if letter. +.Ed +.\" }}} +.\" {{{ Irccd.Unicode.isLower +.Pp +Irccd.Unicode.isLower +.Bd -ragged -offset indent +Check if the unicode character is lower case. +.Pp +Synopsis +.Bd -literal -offset Ds +ret = Irccd.Unicode.isLower(code) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa code No (string) +The code point. +.El +.Pp +Returns +.Pp +True if lower case. +.Ed +.\" }}} !Functions +.\" {{{ Irccd.Unicode.isSpace +.Pp +Irccd.Unicode.isSpace +.Bd -ragged -offset indent +Check if the unicode character is a space. +.Pp +Synopsis +.Bd -literal -offset Ds +ret = Irccd.Unicode.isSpace(code) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa code No (string) +The code point. +.El +.Pp +Returns +.Pp +True if space. +.Ed +.\" }}} +.\" {{{ Irccd.Unicode.isTitle +.Pp +Irccd.Unicode.isTitle +.Bd -ragged -offset indent +Check if the unicode character is title case. +.Pp +Synopsis +.Bd -literal -offset Ds +ret = Irccd.Unicode.isTitle(code) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa code No (string) +The code point. +.El +.Pp +Returns +.Pp +True if title case. +.Ed +.\" }}} +.\" {{{ Irccd.Unicode.isUppwer +.Pp +Irccd.Unicode.isUpper +.Bd -ragged -offset indent +Check if the unicode character is upper case. +.Pp +Synopsis +.Bd -literal -offset Ds +ret = Irccd.Unicode.isUpper(code) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa code No (string) +The code point. +.El +.Pp +Returns +.Pp +True if upper case. +.Ed +.\" }}} +.\" }}} !Functions +.\" }}} !Module: Irccd.Unicode +.\" {{{ Module: Irccd.Util +.Ss Irccd.Util +Various utilities. +.\" {{{ Functions +.\" {{{ Irccd.Util.cut +.Pp +Irccd.Util.cut +.Bd -ragged -offset indent +Cut a piece of data into several lines. +.Pp +The argument +.Fa data +is a string or a list of strings. In any case, all strings are first splitted by +spaces and trimmed. This ensure that useless whitespaces are discarded. +.Pp +The argument +.Fa maxc +controls the maximum of characters allowed per line, it can be a positive +integer. If undefined is given, a default of 72 is used. +.Pp +The argument +.Fa maxl +controls the maximum of lines allowed. It can be a positive integer or undefined +for an infinite list. +.Pp +If +.Fa maxl +is used as a limit and the data can not fit within the bounds, +undefined is returned. +.Pp +An empty list may be returned if empty strings were found. +.Pp +Synopsis +.Bd -literal -offset Ds +lines = Irccd.Util.cut(data, maxc, maxl) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa data No (mixed) +A string or an array of strings. +.It Fa maxc No (int) +Max number of colums (Optional, default: 72). +.It Fa maxl No (int) +Max number of lines (Optional, default: undefined). +.El +.Pp +Throws +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Va RangeError +If maxl or maxc are negative numbers. +.It Va RangeError +If one word length was bigger than maxc. +.It Va TypeError +If data is not a string or a list of strings. +.El +.Pp +Returns +.Pp +A list of strings ready to be sent or undefined if the data is too big. +.Ed +.\" }}} +.\" {{{ Irccd.Util.format +.Pp +Irccd.Util.format +.Bd -ragged -offset indent +Format a string according to the template system. +.Pp +See the documentation about the template format in +.Xr irccd-templates 7 . +.Pp +Synopsis +.Bd -literal -offset Ds +str = Irccd.Util.format(input, params) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa input No (string) +The text to update. +.It Fa params No (Object) +The parameters. For each keyword you want to replace in the +.Ar input , +add a new entry into the object. Note: the special +.Va date +object key is reserved and must be set to a timestamp if desired. +.El +.Pp +Returns +.Pp +The converted text. +.Pp +Remarks +.Pp +Be very careful when you use this function with untrusted input. Do never pass +untrusted content (e.g. user message) as input parameter. +.Pp +For example, the following code is unsafe: +.Bd -literal -offset Ds +function onMessage(server, channel, origin, message) +{ + // DON'T DO THIS. + server.message(channel, Irccd.Util.format("@{red}" + message + "@{}"); +} +.Ed +.Pp +If a user sends a message like ${HOME}, it will prints the user home directory, +which is a high security issue if you have environment variables with passwords. +.Pp +Instead, always use a literal string using a replacement with the user input: +.Bd -literal -offset Ds +function onMessage(server, channel, origin, message) +{ + // CORRECT. + server.message(channel, Irccd.Util.format("@{red}#{message}@{}", { + message: message + }); +} +.Ed +.Ed +.\" }}} +.\" {{{ Irccd.Util.splithost +.Pp +Irccd.Util.splithost +.Bd -ragged -offset indent +Extract the host from a user, for instance with foo!~foo@localhost, +.Em localhost +will be returned. +.Pp +Synopsis +.Bd -literal -offset Ds +hostname = Irccd.Util.splithost(user) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa user No (string) +The user to split. +.El +.Pp +Returns +.Pp +The host +.Ed +.\" }}} +.\" {{{ Irccd.Util.splituser +.Pp +Irccd.Util.splituser +.Bd -ragged -offset indent +Extract the name from a user, for instance with foo!~bar@localhost, +.Em foo +will be returned. +.Pp +Synopsis +.Bd -literal -offset Ds +nick = Irccd.Util.splituser(user) +.Ed +.Pp +Arguments +.Pp +.Bl -tag -width 20n -compact -offset Ds +.It Fa user No (string) +The user to split. +.El +.Pp +Returns +.Pp +The nickname. +.Ed +.\" }}} +.\" }}} !Functions +.\" }}} !Module: Irccd.Util +.\" SEE ALSO +.Sh SEE ALSO +.Xr irccd 1