Mercurial > irccd
changeset 932:0e11221c9bcc
man: split irccd-api into individual ones
author | David Demelier <markand@malikania.fr> |
---|---|
date | Tue, 05 Jan 2021 22:25:47 +0100 |
parents | c78ad0799e68 |
children | a29cd04e3878 |
files | CHANGES.md man/CMakeLists.txt man/irccd-api-chrono.3 man/irccd-api-directory.3 man/irccd-api-file.3 man/irccd-api-logger.3 man/irccd-api-plugin.3 man/irccd-api-server.3 man/irccd-api-system.3 man/irccd-api-timer.3 man/irccd-api-unicode.3 man/irccd-api-util.3 man/irccd-api.3 man/irccd-api.7 |
diffstat | 14 files changed, 1696 insertions(+), 2471 deletions(-) [+] |
line wrap: on
line diff
--- a/CHANGES.md Tue Jan 05 22:13:47 2021 +0100 +++ b/CHANGES.md Tue Jan 05 22:25:47 2021 +0100 @@ -1,6 +1,12 @@ IRC Client Daemon CHANGES ========================= +irccd current +---------------------- + +- Split irccd-api manual page into individual irccd-api-<module> for a better + readability. + irccd 3.1.1 2021-01-04 ----------------------
--- a/man/CMakeLists.txt Tue Jan 05 22:13:47 2021 +0100 +++ b/man/CMakeLists.txt Tue Jan 05 22:25:47 2021 +0100 @@ -20,7 +20,17 @@ set( MANPAGES - irccd-api.7 + irccd-api-chrono.3 + irccd-api-directory.3 + irccd-api-file.3 + irccd-api-logger.3 + irccd-api-plugin.3 + irccd-api-server.3 + irccd-api-system.3 + irccd-api-timer.3 + irccd-api-unicode.3 + irccd-api-util.3 + irccd-api.3 irccd-ipc.7 irccd-templates.7 irccd-test.1
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/irccd-api-chrono.3 Tue Jan 05 22:25:47 2021 +0100 @@ -0,0 +1,63 @@ +.\" +.\" Copyright (c) 2013-2020 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-CHRONO 3 +.Os +.\" NAME +.Sh NAME +.Nm Irccd.Chrono +.Nd irccd chrono API +.\" SYNOPSIS +.Sh SYNOPSIS +.Fn Irccd.Chrono +.Fn Irccd.Chrono.prototype.elapsed +.Fn Irccd.Chrono.prototype.pause +.Fn Irccd.Chrono.prototype.resume +.Fn Irccd.Chrono.prototype.start +.\" DESCRIPTION +.Sh DESCRIPTION +This module keeps track of elapsed time. +.\" METHODS +.Sh METHODS +.\" Irccd.Chrono +The +.Fn Irccd.Chrono +constructor function creates a chrono object at the current time. +.Pp +.\" Irccd.Chrono.prototype.elapsed +The +.Fn Irccd.Chrono.prototype.elapsed +method returns the number of milliseconds elapsed since last the object was +started or constructed. +.Pp +.\" Irccd.Chrono.prototype.pause +The +.Fn Irccd.Chrono.prototype.pause +method pauses the timer, without resetting the current elapsed time stored. +.Pp +.\" Irccd.Chrono.prototype.resume +The +.Fn Irccd.Chrono.prototype.resume +method resume accumulating additional time. Has no effect if the timer is +already running. +.Pp +.\" Irccd.Chrono.prototype.start +The +.Fn Irccd.Chrono.prototype.start +method starts or restarts accumulating time. +.\" SEE ALSO +.Sh SEE ALSO +.Xr irccd-api 3
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/irccd-api-directory.3 Tue Jan 05 22:25:47 2021 +0100 @@ -0,0 +1,145 @@ +.\" +.\" Copyright (c) 2013-2020 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-DIRECTORY 3 +.Os +.\" NAME +.Sh NAME +.Nm Irccd.Directory +.Nd directory iteration and inspection API +.\" SYNOPSIS +.Sh SYNOPSIS +.Vt Irccd.Directory.Dot +.Vt Irccd.Directory.DotDot +.Vt Irccd.Directory.TypeDir +.Vt Irccd.Directory.TypeFile +.Vt Irccd.Directory.TypeLink +.Vt Irccd.Directory.TypeUnknown +.Fn Irccd.Directory "path, flags" +.Fn Irccd.Directory.find "path, pattern, recursive = false" +.Fn Irccd.Directory.mkdir "path, mode = 0700" +.Fn Irccd.Directory.remove "path, recursive = false" +.Fn Irccd.Directory.prototype.find "pattern, recursive" +.Fn Irccd.Directory.prototype.remove "recursive = false" +.\" DESCRIPTION +.Sh DESCRIPTION +This module can be used to iterate, find, remove or create directories. +.Pp +Use this module with care. +.\" CONSTANTS +.Sh CONSTANTS +The following constants properties are defined: +.Pp +.Bl -tag -width 18n +.It Va Dot No (int) +List "." directory. +.It Va DotDot No (int) +List ".." directory. +.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. +.It Va TypeUnknown No (int) +Unknown type file. +.El +.\" METHODS +.Sh METHODS +.\" Irccd.Directory.find +The +.Fn Irccd.Directory.find +method finds an entry at root +.Fa path +by a pattern or a regular expression depending on the object +.Fa pattern . +The optional boolean argument +.Fa recursive +can be set to true to recursively find. Returns the path to the file if found. +.Pp +.\" Irccd.Directory.mkdir +The +.Fn Irccd.Directory.mkdir +method creates the directory +.Fa path +and all its parents. +.\" Irccd.Directory.remove +.Pp +The +.Fn Irccd.Directory.remove +method removes the directory +.Fa path +optionally recursively if boolean argument +.Fa recursive +is true. +.Pp +.\" Irccd.Directory [constructor] +The +.Fn Irccd.Directory +function constructor opens a directory at the given +.Fa path . +The optional +.Fa flags +argument is a bitwise integer containing either +.Vt Irccd.Directory.Dot , Irccd.Directory.DotDot +to respectively list directories +.Pa \&. +and +.Pa .. . +When constructed successfully, the object has the following properties: +.Pp +.Bl -tag -width 18n -offset indent -compact +.It Va path No (string) +the path to the directory. +.It Va entries No (array) +an array for each entry. See below +.El +.Pp +For each entry found, the array +.Va 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 +.\" Irccd.Directory.prototype.find +The +.Fn Irccd.Directory.prototype.find +method is the synonym of +.Fn Irccd.Directory.find +method but the path is taken from the directory object. +.Pp +.\" Irccd.Directory.prototype.remove +The +.Fn Irccd.Directory.prototype.remove +method is a synonym of +.Fn Irccd.Directory.remove +method but the path is taken from the directory object. +.\" EXCEPTIONS +.Sh EXCEPTIONS +.Bl -tag -width 20n +.It Bq Er Irccd.SystemError +On I/O errors. +.It Bq Er Error +On other errors. +.El +.\" SEE ALSO +.Sh SEE ALSO +.Xr irccd-api 3
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/irccd-api-file.3 Tue Jan 05 22:25:47 2021 +0100 @@ -0,0 +1,232 @@ +.\" +.\" Copyright (c) 2013-2020 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-FILE 3 +.Os +.\" NAME +.Sh NAME +.Nm Irccd.File +.Nd file I/O API +.\" SYNOPSIS +.Sh SYNOPSIS +.Vt Irccd.File.SeekCur +.Vt Irccd.File.SeekEnd +.Vt Irccd.File.SeekSet +.Fn Irccd.File.basename "path" +.Fn Irccd.File.dirname "path" +.Fn Irccd.File.exists "path" +.Fn Irccd.File.remove "path" +.Fn Irccd.File.stat "path" +.Fn Irccd.File "path, mode" +.Fn Irccd.File.prototype.basename +.Fn Irccd.File.prototype.close +.Fn Irccd.File.prototype.dirname +.Fn Irccd.File.prototype.lines +.Fn Irccd.File.prototype.read "amount = undefined" +.Fn Irccd.File.prototype.readline +.Fn Irccd.File.prototype.remove +.Fn Irccd.File.prototype.seek "type, amount" +.Fn Irccd.File.prototype.stat +.Fn Irccd.File.prototype.tell +.Fn Irccd.File.prototype.write "data" +.\" DESCRIPTION +.Sh DESCRIPTION +This module provides routines for opening and writing files on the disk. +.Pp +For convenience, some functions are available as static functions and some as +object methods. +.\" CONSTANTS +.Sh CONSTANTS +The following constants properties are defined: +.Pp +.Bl -tag +.It Va Irccd.File.SeekCur No (int) +Seek from the current file position. +.It Va Irccd.File.SeekEnd No (int) +Seek from end of the file. +.It Va Irccd.File.SeekSet No (int) +Seek from beginning of the file. +.El +.\" METHODS +.Sh METHODS +.\" Irccd.File.basename +The +.Fn Irccd.File.basename +method returns the file basename from +.Fa path +as specified in +.Xr basename 3 +POSIX function. +.Pp +.\" Irccd.File.dirname +The +.Fn Irccd.File.dirname +method returns the file directory name from +.Fa path +as specified in +.Xr dirname 3 +POSIX function. +.Pp +.\" Irccd.File.exists +The +.Fn Irccd.File.exists +method checks if the file specified by +.Fa path +exists and returns true to indicate success. Warning: using this function is +usually discouraged as it may introduce a possible race condition. +.Pp +.\" Irccd.File.remove +The +.Fn Irccd.File.remove +method removes the file at the given +.Fa path . +.Pp +.\" Irccd.File.stat +The optional +.Fn Irccd.File.stat +method returns information from the file at the specified +.Fa path . +The returned object has 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 +.Pp +.\" Irccd.File +The +.Fn Irccd.File +function constructor opens a file specified by +.Fa path +with the specified +.Fa mode +similar to +.Xr fopen 3 +C standard function. +.Pp +.\" Irccd.File.prototype.basename +The +.Fn Irccd.File.prototype.basename +method is the synonym of +.Fn Irccd.File.basename +method but the path is taken from the file object. +.Pp +.\" Irccd.File.prototype.close +The +.Fn Irccd.File.prototype.close +method closes the file. It is usually not required as already closed in the +destructor. +.Pp +.\" Irccd.File.prototype.dirname +The +.Fn Irccd.File.prototype.dirname +method is the synonym of +.Fn Irccd.File.dirname +method but the path is taken from the file object. +.Pp +.\" Irccd.File.prototype.lines +The +.Fn Irccd.File.prototype.lines +method reads all lines and return an array. +.Pp +.\" Irccd.File.prototype.read +The +.Fn Irccd.File.prototype.read +method reads the specified +.Fa amount +of characters or the whole file if undefined. +.Pp +.\" Irccd.File.prototype.readline +The +.Fn Irccd.File.prototype.readline +method reads the next line available and returns it. If EOF was reached, +returns undefined. Warning: this method is slow and its usage is discouraged on +large files. Consider using +.Fn Irccd.File.prototype.lines +function if you want to read a file line per line. +.Pp +.\" Irccd.File.prototype.remove +The +.Fn Irccd.File.prototype.remove +method is the synonym of +.Fn Irccd.File.remove +method but the path is taken from the file object. +.Pp +.\" Irccd.File.prototype.seek +The +.Fn Irccd.File.prototype.seek +method sets the position in the file to the position +.Fa amount . +The type argument must be one of +.Vt Irccd.File.SeekCur , Irccd.File.SeekEnd +or +.Vt Irccd.File.SeekSet . +.Pp +.\" Irccd.File.prototype.stat +The optional +.Fn Irccd.File.prototype.stat +method is the synonym of +.Fn Irccd.File.stat +method but the path is taken from the file object. +.Pp +.\" Irccd.File.prototype.tell +The +.Fn Irccd.File.prototype.tell +methods returns the current position in the file. +.Pp +.\" Irccd.File.prototype.write +The +.Fn Irccd.File.prototype.write +method writes the string +.Fa data +to the file. +.Pp +.\" EXCEPTIONS +.Sh EXCEPTIONS +.Bl -tag -width 20n +.It Bq Er Irccd.SystemError +On I/O errors. +.It Bq Er Error +On other errors. +.El +.\" SEE ALSO +.Sh SEE ALSO +.Xr irccd-api 3
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/irccd-api-logger.3 Tue Jan 05 22:25:47 2021 +0100 @@ -0,0 +1,64 @@ +.\" +.\" Copyright (c) 2013-2020 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-LOGGER 3 +.Os +.\" NAME +.Sh NAME +.Nm Irccd.Logger +.Nd logging API +.\" SYNOPSIS +.Sh SYNOPSIS +.Fn Irccd.Logger.debug "message" +.Fn Irccd.Logger.info "message" +.Fn Irccd.Logger.warning "message" +.\" DESCRIPTION +.Sh DESCRIPTION +This module must be used to log messages. It will add messages to the logging +system configured in the +.Xr irccd.conf 5 +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. +.\" METHODS +.Sh METHODS +.\" Irccd.Logger.debug +The +.Fn Irccd.Logger.debug +method adds a debug +.Fa message , +this is only appended to the journal if irccd was compiled in Debug mode. +.Pp +.\" Irccd.Logger.info +The +.Fn Irccd.Logger.info +method adds a informational +.Fa message . +The message is logged only if irccd is running with verbose messages enabled. +.Pp +.\" Irccd.Logger.warning +The +.Fn Irccd.Logger.warning +method adds a warning +.Fa message . +The message will always be logged. +.\" SEE ALSO +.Sh SEE ALSO +.Xr irccd-api 3
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/irccd-api-plugin.3 Tue Jan 05 22:25:47 2021 +0100 @@ -0,0 +1,114 @@ +.\" +.\" Copyright (c) 2013-2020 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-PLUGIN 3 +.Os +.\" NAME +.Sh NAME +.Nm Irccd.Plugin +.Nd irccd plugin API +.\" SYNOPSIS +.Sh SYNOPSIS +.Vt Irccd.Plugin.config +.Vt Irccd.Plugin.paths +.Vt Irccd.Plugin.templates +.Fn Irccd.Plugin.info "name" +.Fn Irccd.Plugin.list +.Fn Irccd.Plugin.load "name" +.Fn Irccd.Plugin.reload "name" +.Fn Irccd.Plugin.unload "name" +.\" DESCRIPTION +.Sh DESCRIPTION +This module let you manage plugins. +.Pp +.\" CONSTANTS +.Sh CONSTANTS +The following constants properties are defined and contain each key-value pairs +from the user +.Xr irccd.conf 5 +file. +.Pp +.Bl -tag +.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 [templates.<name>] +section. +.El +.\" METHODS +.Sh METHODS +.\" Irccd.Plugin.info +The +.Fn Irccd.Plugin.info +method returns the information about a plugin as an object. +.Pp +The returned object if the plugin was found 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 +.Pp +.\" Irccd.Plugin.list +The +.Fn Irccd.Plugin.list +method returns an array of string containing all plugin names. +.Pp +.\" Irccd.Plugin.load +The +.Fn Irccd.Plugin.load +method loads a plugin by its +.Fa name . +This function will search through the standard directories. +.Pp +.\" Irccd.Plugin.reload +The +.Fn Irccd.Plugin.reload +method reloads a plugin by its +.Fa name . +.Pp +.\" Irccd.Plugin.unload +The +.Fn Irccd.Plugin.unload +method unloads a plugin by its +.Fa name +and removes it. +.\" EXCEPTIONS +.Sh EXCEPTIONS +.Bl -tag -width Er +.It Bq Er ReferenceError +If the plugin was not found. +.It Bq Er Error +On other errors. +.El +.\" SEE ALSO +.Sh SEE ALSO +.Xr irccd-api 3
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/irccd-api-server.3 Tue Jan 05 22:25:47 2021 +0100 @@ -0,0 +1,264 @@ +.\" +.\" Copyright (c) 2013-2020 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-SERVER 3 +.Os +.\" NAME +.Sh NAME +.Nm Irccd.Unicode +.Nd server management +.\" SYNOPSIS +.Sh SYNOPSIS +.Fn Irccd.Server.add "server" +.Fn Irccd.Server.find "name" +.Fn Irccd.Server.list +.Fn Irccd.Server.remove "name" +.Fn Irccd.Server "parameters" +.Fn Irccd.Server.prototype.info +.Fn Irccd.Server.prototype.invite "target, channel" +.Fn Irccd.Server.prototype.isSelf "nickname" +.Fn Irccd.Server.prototype.join "channel, password = undefined" +.Fn Irccd.Server.prototype.kick "target, channel, reason = undefined" +.Fn Irccd.Server.prototype.me "target, message" +.Fn Irccd.Server.prototype.message "target, message" +.Fn Irccd.Server.prototype.mode "target, mode, limit, user, mode" +.Fn Irccd.Server.prototype.names "channel" +.Fn Irccd.Server.prototype.nick "nickname" +.Fn Irccd.Server.prototype.notice "target, message" +.Fn Irccd.Server.prototype.part "channel, reason = undefined" +.Fn Irccd.Server.prototype.toString +.Fn Irccd.Server.prototype.topic "target, topic" +.Fn Irccd.Server.prototype.whois "target" +.\" DESCRIPTION +.Sh DESCRIPTION +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. +.\" METHODS +.Sh METHODS +.\" Irccd.Server.add +The +.Fn Irccd.Server.add +method adds the new +.Fa server +into the irccd instance. +.Pp +.\" Irccd.Server.find +The +.Fn Irccd.Server.find +method finds a server by its +.Fa name +and returns it. +.Pp +.\" Irccd.Server.list +The +.Fn Irccd.Server.list +method returns a map of all running servers. The table of all servers as +key-value pairs where key is the server identifier and value the object itself. +.Pp +.\" Irccd.Server.remove +The +.Fn Irccd.Server.remove +method removes the server specified by +.Fa name +from the irccd instance and disconnects it. +.Pp +.\" Irccd.Server +The +.Fn Irccd.Server +constructor function creates a new server with settings in the +.Fa parameters +object which may have the following properties: +.Pp +.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 +.\" Irccd.Server.prototype.info +The +.Fn Irccd.Server.prototype.info +method returns the server information. The object have the following +properties: +.Pp +.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 +.Pp +.\" Irccd.Server.prototype.invite +The +.Fn Irccd.Server.prototype.invite +method invites the specified +.Fa target +on the given +.Fa channel . +.Pp +.\" Irccd.Server.prototype.isSelf +The +.Fn Irccd.Server.prototype.isSelf +method returns true if +.Fa nickname +targets the bot. +.Pp +.\" Irccd.Server.prototype.join +The +.Fn Irccd.Server.prototype.join +method joins the specified +.Fa channel +with an optional +.Fa password . +.Pp +.\" Irccd.Server.prototype.kick +The +.Fn Irccd.Server.prototype.kick +method kicks the specified +.Fa target +from the +.Fa channel , +the +.Fa reason +is optional. +.Pp +.\" Irccd.Server.prototype.me +The +.Fn Irccd.Server.prototype.me +method sends an action emote +.Fa message +to the given +.Fa target . +.Pp +.\" Irccd.Server.prototype.message +The +.Fn Irccd.Server.prototype.message +method sends the +.Fa message +to the specified +.Fa target . +.Pp +.\" Irccd.Server.prototype.mode +The +.Fn Irccd.Server.prototype.mode +method changes irccd's user mode or a channel mode. If the +.Fa target +is the bot's nickname, it changes its +.Fa mode . +otherwise it changes the channel one. +The optional argument +.Fa limit , user +and +.Fa mask +are required depending on the mode mask. See IRC specification for more +details. +.Pp +.\" Irccd.Server.prototype.names +The +.Fn Irccd.Server.prototype.names +method requests a list of names for the given +.Fa channel . +This function will generate the onNames event. +.Pp +.\" Irccd.Server.prototype.nick +The +.Fn Irccd.Server.prototype.nick +method changes the bot's +.Fa nickname . +.Pp +.\" Irccd.Server.prototype.notice +The +.Fn Irccd.Server.prototype.notice +method sends a private notice +.Fa message +to the specified +.Fa target . +.Pp +.\" Irccd.Server.prototype.part +The +.Fn Irccd.Server.prototype.part +method leaves the specified +.Fa channel , +using an optional +.Fa reason +if not null. +.Pp +.\" Irccd.Server.prototype.toString +The +.Fn Irccd.Server.prototype.toString +method converts the server to string by returning its unique identifier. +Because each server has a unique identifier, this method allows adding a server +as property key in maps. +.Pp +.\" Irccd.Server.prototype.topic +The +.Fn Irccd.Server.prototype.topic +method sets the topic to +.Fa topic +in the given +.Fa channel . +.Pp +.\" Irccd.Server.prototype.whois +The +.Fn Irccd.Server.prototype.whois +method requests whois information for the +.Fa target . +This function will generate onWhois event. +.Pp +.\" EXCEPTIONS +.Sh EXCEPTIONS +.Bl -tag -width 22n +.It Bq Er Irccd.ServerError +Thrown on server errors. Usually on invalid arguments. +.It Bq Er Error +On other errors. +.El +.\" SEE ALSO +.Sh SEE ALSO +.Xr irccd-api 3
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/irccd-api-system.3 Tue Jan 05 22:25:47 2021 +0100 @@ -0,0 +1,147 @@ +.\" +.\" Copyright (c) 2013-2020 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-SYSTEM 3 +.Os +.\" NAME +.Sh NAME +.Nm Irccd.System +.Nd system inspection API +.\" SYNOPSIS +.Sh SYNOPSIS +.Fn Irccd.System.env "name" +.Fn Irccd.System.exec "cmd" +.Fn Irccd.System.home +.Fn Irccd.System.name +.Fn Irccd.System.popen "cmd, mode" +.Fn Irccd.System.sleep "seconds" +.Fn Irccd.System.ticks +.Fn Irccd.System.uptime +.Fn Irccd.System.usleep "microseconds" +.Fn Irccd.System.version +.\" DESCRIPTION +.Sh DESCRIPTION +System inspection and utilities. +.\" METHODS +.Sh METHODS +.\" Irccd.System.env +The +.Fn Irccd.System.env +method returns the value of the environment variable +.Fa name +or undefined if empty. +.Pp +.\" Irccd.System.exec +The +.Fn Irccd.System.exec +method executes the command +.Fa cmd +as if invoked with the standard C +.Xr system 3 +function. +.Pp +.\" Irccd.System.home +The +.Fn Irccd.System.home +returns the home directory. This function should be used with care, plugin +should not use user's home to store files. +.Pp +.\" Irccd.System.name +The +.Fn Irccd.System.name +returns the operating system name. Returns one of: +.Pp +.Bl -bullet -compact -offset Ds +.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 +.\" Irccd.System.popen +The +.Fn Irccd.System.popen +method is a wrapper for +.Xr popen 3 . +It opens the command +.Fa cmd +with the given +.Fa mode +and returns a +.Vt Irccd.File +object. This function is optional. +.Pp +.\" Irccd.System.sleep +The +.Fn Irccd.System.sleep +method suspends the execution thread for the given amount of +.Fa seconds . +.Pp +.\" Irccd.System.ticks +The +.Fn Irccd.System.ticks +method returns the time spent since irccd startup in milliseconds. +.Pp +.\" Irccd.System.uptime +The +.Fn Irccd.System.uptime +returns the system uptime in seconds. +.Pp +.\" Irccd.System.usleep +The +.Fn Irccd.System.usleep +method suspends the execution thread for the given amount of +.Fa microseconds . +.Pp +.\" Irccd.System.version +The +.Fn Irccd.System.version +function returns the operating system version as a string. Result of this +function is system dependant. +.\" EXCEPTIONS +.Sh EXCEPTIONS +.Bl -tag -width 20n +.It Bq Er Irccd.SystemError +On system errors. +.It Bq Er Error +On other errors. +.El +.\" SEE ALSO +.Sh SEE ALSO +.Xr irccd-api 3 , +.Xr irccd-api-file 3
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/irccd-api-timer.3 Tue Jan 05 22:25:47 2021 +0100 @@ -0,0 +1,89 @@ +.\" +.\" Copyright (c) 2013-2020 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-TIMER 3 +.Os +.\" NAME +.Sh NAME +.Nm Irccd.Timer +.Nd irccd timer API +.\" SYNOPSIS +.Sh SYNOPSIS +.Vt Irccd.Timer.Single +.Vt Irccd.Timer.Repeat +.Fn Irccd.Timer "type, delay, callback" +.Fn Irccd.Timer.prototype.start +.Fn Irccd.Timer.prototype.stop +.\" DESCRIPTION +.Sh DESCRIPTION +This API provides periodic timers. +.Pp +Even though they are generated at periodic interval they do run in the same +thread and do not require special user mutexes. +.\" CONSTANTS +.Sh CONSTANTS +The following constants properties are defined: +.Pp +.Bl -tag +.It Va Irccd.Timer.Single No (int) +The timer is single-shot. +.It Va Irccd.Timer.Repeat No (int) +The timer is looping. +.El +.\" METHODS +.Sh METHODS +.\" Irccd.Timer() +The +.Fn Irccd.Timer +constructor function creates a new timer object with the given +.Fa delay +expressed in milliseconds and the function +.Fa callback +to be called when the timer expires. The argument +.Fa type +is either +.Vt Irccd.Timer.Single +to create a one-shot timer or +.Vt Irccd.Timer.Repeat +to make a infinite timer. +.Pp +.\" Irccd.Timer.prototype.start +The +.Fn Irccd.Timer.prototype.start +method will effectively start the timer. It does nothing if the timer is +already running. +.Pp +.\" Irccd.Timer.prototype.stop +The +.Fn Irccd.Timer.prototype.stop +will stop the timer. It does nothing if the timer is already stopped. +.\" EXAMPLES +.Sh EXAMPLES +Create a timer that will repeat every 1 second. +.Bd -literal +var t = new Irccd.Timer(Irccd.Timer.Repeat, 1000, function () { + // Do your action, this will be called every 1 second. +}); +.Ed +.\" EXCEPTIONS +.Sh EXCEPTIONS +.Bl -tag -width Er +.It Bq Er Error +On other errors. +.El +.\" SEE ALSO +.Sh SEE ALSO +.Xr irccd-api 3
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/irccd-api-unicode.3 Tue Jan 05 22:25:47 2021 +0100 @@ -0,0 +1,79 @@ +.\" +.\" Copyright (c) 2013-2020 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-UNICODE 3 +.Os +.\" NAME +.Sh NAME +.Nm Irccd.Unicode +.Nd unicode management API +.\" SYNOPSIS +.Sh SYNOPSIS +.Fn Irccd.Unicode.isDigit "code" +.Fn Irccd.Unicode.isLetter "code" +.Fn Irccd.Unicode.isLower "code" +.Fn Irccd.Unicode.isSpace "code" +.Fn Irccd.Unicode.isTitle "code" +.Fn Irccd.Unicode.isUpper "code" +.\" DESCRIPTION +.Sh DESCRIPTION +Inspect unicode character classes. +.\" METHODS +.Sh METHODS +.\" Irccd.Unicode.isDigit +The +.Fn Irccd.Unicode.isDigit +method returns true if the code point +.Fa code +is a digit. +.Pp +.\" Irccd.Unicode.isLetter +The +.Fn Irccd.Unicode.isLetter +method returns true if code point +.Fa code +is a letter. +.Pp +.\" Irccd.Unicode.isLower +The +.Fn Irccd.Unicode.isLower +method returns true if the code point +.Fa code +is lower cased. +.Pp +.\" Irccd.Unicode.isSpace +The +.Fn Irccd.Unicode.isSpace +method returns true if the code point +.Fa code +is a space. +.Pp +.\" Irccd.Unicode.isTitle +The +.Fn Irccd.Unicode.isTitle +method returns true if the code point +.Fa code +is considered title case. +.Pp +.\" Irccd.Unicode.isUpper +The +.Fn Irccd.Unicode.isUpper +method returns true if the code point +.Fa code +is upper cased. +.\" SEE ALSO +.Sh SEE ALSO +.Xr irccd-api 3
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/irccd-api-util.3 Tue Jan 05 22:25:47 2021 +0100 @@ -0,0 +1,126 @@ +.\" +.\" Copyright (c) 2013-2020 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-UTIL 3 +.Os +.\" NAME +.Sh NAME +.Nm Irccd.Util +.Nd irccd utilities API +.\" SYNOPSIS +.Sh SYNOPSIS +.Fn Irccd.Util.cut "data, maxc, maxl" +.Fn Irccd.Util.format "input, parameters" +.Fn Irccd.Util.splithost "user" +.Fn Irccd.Util.splituser "user" +.\" DESCRIPTION +.Sh DESCRIPTION +This module provides various utilities. +.\" METHODS +.Sh METHODS +.\" Irccd.Util.Cut +The +.Fn Irccd.Util.cut +method splits the +.Fa data +into several lines returned as an array of strings. It may be a string or an +array of strings. +.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 +.\" Irccd.Util.format +The +.Fn Irccd.Util.format +method formats the string +.Fa input +according to the template system. The object +.Fa parameters +should be filled for each keyword to replace in the input. The reserved keyword +.Dq date +must be used to replace a date if necessary and should contain an integer +timestamp. The function returns the converted text. +.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 +.Pp +.\" Irccd.Util.splithost +The +.Fn Irccd.Util.splithost +method returns the host component from the specified +.Fa user +string. +.Pp +.\" Irccd.Util.splituser +The +.Fn Irccd.Util.splituser +method returns the user component from the specified +.Fa user +string. +.\" EXCEPTIONS +.Sh EXCEPTIONS +.Bl -tag -width Er +.It Bq Er RangeError +If +.Fa maxl +or +.Fa maxc +are negative numbers. +.It Bq Er RangeError +If one word length was bigger than +.Fa maxc . +.It Bq Er TypeError +If +.Fa data +is not a string or a list of strings. +.El
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/irccd-api.3 Tue Jan 05 22:25:47 2021 +0100 @@ -0,0 +1,356 @@ +.\" +.\" Copyright (c) 2013-2020 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 +.\" SYNOPSIS +.Sh SYNOPSIS +.Ss Modules +.Vt Irccd +.Vt Irccd.Chrono +.Vt Irccd.Directory +.Vt Irccd.File +.Vt Irccd.Logger +.Vt Irccd.Plugin +.Vt Irccd.Server +.Vt Irccd.System +.Vt Irccd.Timer +.Vt Irccd.Unicode +.Vt Irccd.Util +.Ss Events +.Fn onCommand "server, origin, channel, message" +.Fn onConnect "server" +.Fn onDisonnect "server" +.Fn onInvite "server, origin, channel" +.Fn onJoin "server, origin, channel" +.Fn onKick "server, origin, channel, target, reason" +.Fn onLoad " +.Fn onMe "server, origin, channel, message" +.Fn onMessage "server, origin, channel, message" +.Fn onMode "server, origin, channel, mode, limit, user, mask" +.Fn onNames "server, channel, list" +.Fn onNick "server, origin, nickname" +.Fn onNotice "server, origin, notice" +.Fn onPart "server, origin, channel, reason" +.Fn onReload " +.Fn onTopic "server, origin, channel, topic" +.Fn onUnload " +.Fn onWhois "server, info" +.El +.\" 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 +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 +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 +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 +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 +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 +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. +.\" onMe +.Ss onMe +Action emote. +.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 +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 +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 +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 +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 +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 +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. +.\" onTopic +.Ss onTopic +This event is triggered when someone changed the channel's topic. +.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. +.\" onWhois +.Ss onWhois +This event is triggered when irccd gets information about a user. +.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 ) . +See dedicated manual pages for information of all submodules. +.\" CONSTANTS +.Sh CONSTANTS +.\" Constants +The following constants properties are defined: +.Pp +.Bl -tag +.It Va Irccd.version No (object) +See below. +.It Va Irccd.version.major No (int) +The major irccd version. +.It Va Irccd.version.minor No (int) +The minor irccd version. +.It Va Irccd.version.patch No (int) +The patch irccd version. +.El +.Pp +.\" EXCEPTIONS +.Sh EXCEPTIONS +The following exceptions are defined: +.Bl -tag +.It Va Irccd.SystemError +An exception inheriting Error thrown by some filesystem functions. +.It Va Irccd.ServerError +Thrown from Irccd.Server module. +.It Va Irccd.PluginError +Throw from Irccd.Plugin module. +.El +.\" SEE ALSO +.Sh SEE ALSO +.Xr irccd 1 +.Xr irccd-api-chrono 3 , +.Xr irccd-api-directory 3 , +.Xr irccd-api-file 3 , +.Xr irccd-api-logger 3 , +.Xr irccd-api-plugin 3 , +.Xr irccd-api-server 3 , +.Xr irccd-api-system 3 , +.Xr irccd-api-timer 3 , +.Xr irccd-api-unicode 3 , +.Xr irccd-api-util 3
--- a/man/irccd-api.7 Tue Jan 05 22:13:47 2021 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,2470 +0,0 @@ -.\" -.\" Copyright (c) 2013-2020 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 -.\" SYNOPSIS -.Sh SYNOPSIS -.Bl -item -compact -.It -.Va Irccd -.It -.Va Irccd.Chrono -.It -.Va Irccd.Directory -.It -.Va Irccd.File -.It -.Va Irccd.Logger -.It -.Va Irccd.Plugin -.It -.Va Irccd.Server -.It -.Va Irccd.System -.It -.Va Irccd.Timer -.It -.Va Irccd.Unicode -.It -.Va Irccd.Util -.El -.\" 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 [templates.<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 microseconds. 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