Mercurial > irccd
view man/irccd-api.7 @ 887:d1cfe59eed06 release-3.0 3.0.1
misc: update before 3.0.1
author | David Demelier <markand@malikania.fr> |
---|---|
date | Sun, 01 Sep 2019 17:08:59 +0200 |
parents | 0a9b03e5239e |
children | e205d19a6d26 |
line wrap: on
line source
.\" .\" Copyright (c) 2013-2019 David Demelier <markand@malikania.fr> .\" .\" Permission to use, copy, modify, and/or distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" .Dd @IRCCD_MAN_DATE@ .Dt IRCCD-API 7 .Os .\" NAME .Sh NAME .Nm irccd-api .Nd irccd Javascript API .\" 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 milliseconds. Suspend the execution thread. .Pp Synopsis .Bd -literal -offset Ds Irccd.System.usleep(msec) .Ed .Pp Arguments .Pp .Bl -tag -width 20n -compact -offset Ds .It Fa msec No (int) The number of milliseconds. .El .Ed .\" }}} .\" {{{ Irccd.System.version .Pp Irccd.System.version .Bd -ragged -offset indent Get the operating system version. Result of this function is system dependant. .Pp Synopsis .Bd -literal -offset Ds version = Irccd.System.version() .Ed .Pp Returns .Pp The version as a string. .Ed .\" }}} .\" }}} !Functions .\" }}} !Module: Irccd.System .\" {{{ Module: Irccd.Timer .Ss Irccd.Timer Create repetitive or one-shot timers. .Pp .\" {{{ Constants The following constants properties are defined: .Pp .Bl -tag -width 20n -compact -offset Ds .It Va Single No (int) The timer is single-shot. .It Va Repeat No (int) The timer is looping. .El .\" }}} .\" {{{ Methods .\" {{{ Irccd.Timer [constructor] .Pp Irccd.Timer [constructor] .Bd -ragged -offset indent Create a new timer object but do not start it immediately. .Pp Synopsis .Bd -literal -offset Ds Irccd.Timer(type, delay, callback) .Ed .Pp Arguments .Pp .Bl -tag -width 20n -compact -offset Ds .It Fa type No (int) Type of timer ( .Fa Irccd.Timer.Repeat or .Fa Irccd.Timer.Single ) . .It Fa delay No (int) The interval in milliseconds. .It Fa callback No (function) The function to call. .El .Pp Example: .Bd -literal -offset Ds var t = new Irccd.Timer(Irccd.Timer.Repeat, 1000, function () { // Do your action, this will be called every 1 second. }); .Ed .Ed .\" }}} .\" {{{ Irccd.Timer.prototype.start .Pp Irccd.Timer.prototype.start .Bd -ragged -offset indent Start the timer. .Pp Synopsis .Bd -literal -offset Ds Irccd.Timer.prototype.start() .Ed .Ed .\" }}} .\" {{{ Irccd.Timer.prototype.stop .Pp Irccd.Timer.prototype.stop .Bd -ragged -offset indent Stop the timer. .Pp Synopsis .Bd -literal -offset Ds Irccd.Timer.prototype.stop() .Ed .Ed .\" }}} .\" }}} !Methods .\" }}} !Module: Irccd.Timer .\" {{{ Module: Irccd.Unicode .Ss Irccd.Unicode Check for character categories. .\" {{{ Functions .\" {{{ Irccd.Unicode.isDigit .Pp Irccd.Unicode.isDigit .Bd -ragged -offset indent Check if the unicode character is a digit. .Pp Synopsis .Bd -literal -offset Ds ret = Irccd.Unicode.isDigit(code) .Ed .Pp Arguments .Pp .Bl -tag -width 20n -compact -offset Ds .It Fa code No (string) The code point. .El .Pp Returns .Pp True if digit. .Ed .\" }}} .\" {{{ Irccd.Unicode.isLetter .Pp Irccd.Unicode.isLetter .Bd -ragged -offset indent Check if the unicode character is a letter. .Pp Synopsis .Bd -literal -offset Ds ret = Irccd.Unicode.isLetter(code) .Ed .Pp Arguments .Pp .Bl -tag -width 20n -compact -offset Ds .It Fa code No (string) The code point. .El .Pp Returns .Pp True if letter. .Ed .\" }}} .\" {{{ Irccd.Unicode.isLower .Pp Irccd.Unicode.isLower .Bd -ragged -offset indent Check if the unicode character is lower case. .Pp Synopsis .Bd -literal -offset Ds ret = Irccd.Unicode.isLower(code) .Ed .Pp Arguments .Pp .Bl -tag -width 20n -compact -offset Ds .It Fa code No (string) The code point. .El .Pp Returns .Pp True if lower case. .Ed .\" }}} !Functions .\" {{{ Irccd.Unicode.isSpace .Pp Irccd.Unicode.isSpace .Bd -ragged -offset indent Check if the unicode character is a space. .Pp Synopsis .Bd -literal -offset Ds ret = Irccd.Unicode.isSpace(code) .Ed .Pp Arguments .Pp .Bl -tag -width 20n -compact -offset Ds .It Fa code No (string) The code point. .El .Pp Returns .Pp True if space. .Ed .\" }}} .\" {{{ Irccd.Unicode.isTitle .Pp Irccd.Unicode.isTitle .Bd -ragged -offset indent Check if the unicode character is title case. .Pp Synopsis .Bd -literal -offset Ds ret = Irccd.Unicode.isTitle(code) .Ed .Pp Arguments .Pp .Bl -tag -width 20n -compact -offset Ds .It Fa code No (string) The code point. .El .Pp Returns .Pp True if title case. .Ed .\" }}} .\" {{{ Irccd.Unicode.isUppwer .Pp Irccd.Unicode.isUpper .Bd -ragged -offset indent Check if the unicode character is upper case. .Pp Synopsis .Bd -literal -offset Ds ret = Irccd.Unicode.isUpper(code) .Ed .Pp Arguments .Pp .Bl -tag -width 20n -compact -offset Ds .It Fa code No (string) The code point. .El .Pp Returns .Pp True if upper case. .Ed .\" }}} .\" }}} !Functions .\" }}} !Module: Irccd.Unicode .\" {{{ Module: Irccd.Util .Ss Irccd.Util Various utilities. .\" {{{ Functions .\" {{{ Irccd.Util.cut .Pp Irccd.Util.cut .Bd -ragged -offset indent Cut a piece of data into several lines. .Pp The argument .Fa data is a string or a list of strings. In any case, all strings are first splitted by spaces and trimmed. This ensure that useless whitespaces are discarded. .Pp The argument .Fa maxc controls the maximum of characters allowed per line, it can be a positive integer. If undefined is given, a default of 72 is used. .Pp The argument .Fa maxl controls the maximum of lines allowed. It can be a positive integer or undefined for an infinite list. .Pp If .Fa maxl is used as a limit and the data can not fit within the bounds, undefined is returned. .Pp An empty list may be returned if empty strings were found. .Pp Synopsis .Bd -literal -offset Ds lines = Irccd.Util.cut(data, maxc, maxl) .Ed .Pp Arguments .Pp .Bl -tag -width 20n -compact -offset Ds .It Fa data No (mixed) A string or an array of strings. .It Fa maxc No (int) Max number of colums (Optional, default: 72). .It Fa maxl No (int) Max number of lines (Optional, default: undefined). .El .Pp Throws .Pp .Bl -tag -width 20n -compact -offset Ds .It Va RangeError If maxl or maxc are negative numbers. .It Va RangeError If one word length was bigger than maxc. .It Va TypeError If data is not a string or a list of strings. .El .Pp Returns .Pp A list of strings ready to be sent or undefined if the data is too big. .Ed .\" }}} .\" {{{ Irccd.Util.format .Pp Irccd.Util.format .Bd -ragged -offset indent Format a string according to the template system. .Pp See the documentation about the template format in .Xr irccd-templates 7 . .Pp Synopsis .Bd -literal -offset Ds str = Irccd.Util.format(input, params) .Ed .Pp Arguments .Pp .Bl -tag -width 20n -compact -offset Ds .It Fa input No (string) The text to update. .It Fa params No (Object) The parameters. For each keyword you want to replace in the .Ar input , add a new entry into the object. Note: the special .Va date object key is reserved and must be set to a timestamp if desired. .El .Pp Returns .Pp The converted text. .Pp Remarks .Pp Be very careful when you use this function with untrusted input. Do never pass untrusted content (e.g. user message) as input parameter. .Pp For example, the following code is unsafe: .Bd -literal -offset Ds function onMessage(server, channel, origin, message) { // DON'T DO THIS. server.message(channel, Irccd.Util.format("@{red}" + message + "@{}"); } .Ed .Pp If a user sends a message like ${HOME}, it will prints the user home directory, which is a high security issue if you have environment variables with passwords. .Pp Instead, always use a literal string using a replacement with the user input: .Bd -literal -offset Ds function onMessage(server, channel, origin, message) { // CORRECT. server.message(channel, Irccd.Util.format("@{red}#{message}@{}", { message: message }); } .Ed .Ed .\" }}} .\" {{{ Irccd.Util.splithost .Pp Irccd.Util.splithost .Bd -ragged -offset indent Extract the host from a user, for instance with foo!~foo@localhost, .Em localhost will be returned. .Pp Synopsis .Bd -literal -offset Ds hostname = Irccd.Util.splithost(user) .Ed .Pp Arguments .Pp .Bl -tag -width 20n -compact -offset Ds .It Fa user No (string) The user to split. .El .Pp Returns .Pp The host .Ed .\" }}} .\" {{{ Irccd.Util.splituser .Pp Irccd.Util.splituser .Bd -ragged -offset indent Extract the name from a user, for instance with foo!~bar@localhost, .Em foo will be returned. .Pp Synopsis .Bd -literal -offset Ds nick = Irccd.Util.splituser(user) .Ed .Pp Arguments .Pp .Bl -tag -width 20n -compact -offset Ds .It Fa user No (string) The user to split. .El .Pp Returns .Pp The nickname. .Ed .\" }}} .\" }}} !Functions .\" }}} !Module: Irccd.Util .\" SEE ALSO .Sh SEE ALSO .Xr irccd 1