changeset 1002:ec5461750efd

man: add Irccd.Rule and Irccd.Hook manual pages
author David Demelier <markand@malikania.fr>
date Sat, 13 Feb 2021 22:15:16 +0100
parents b01f5d65d62a
children bbb3d3075ec2
files MIGRATING.md irccd/jsapi-irccd.c man/CMakeLists.txt man/irccd-api-chrono.3 man/irccd-api-hook.3 man/irccd-api-rule.3 man/irccd-api-timer.3 man/irccd-api-util.3 man/irccd-api.3
diffstat 9 files changed, 189 insertions(+), 15 deletions(-) [+]
line wrap: on
line diff
--- a/MIGRATING.md	Sat Feb 13 10:09:00 2021 +0100
+++ b/MIGRATING.md	Sat Feb 13 22:15:16 2021 +0100
@@ -46,6 +46,11 @@
 Javascript API
 --------------
 
+### Module Irccd
+
+- The property `Irccd.version` and their properties have been renamed to
+  `CamelCase` for consistency with other constants from other modules.
+
 ### Module File
 
 - The method `File.readline` is no longer marked as slow.
--- a/irccd/jsapi-irccd.c	Sat Feb 13 10:09:00 2021 +0100
+++ b/irccd/jsapi-irccd.c	Sat Feb 13 22:15:16 2021 +0100
@@ -304,12 +304,12 @@
 	/* Irccd.version (property) */
 	duk_push_object(ctx);
 	duk_push_int(ctx, IRCCD_VERSION_MAJOR);
-	duk_put_prop_string(ctx, -2, "major");
+	duk_put_prop_string(ctx, -2, "Major");
 	duk_push_int(ctx, IRCCD_VERSION_MINOR);
-	duk_put_prop_string(ctx, -2, "minor");
+	duk_put_prop_string(ctx, -2, "Minor");
 	duk_push_int(ctx, IRCCD_VERSION_PATCH);
-	duk_put_prop_string(ctx, -2, "patch");
-	duk_put_prop_string(ctx, -2, "version");
+	duk_put_prop_string(ctx, -2, "Patch");
+	duk_put_prop_string(ctx, -2, "Version");
 
 	/* Create the system_error that inherits from Error. */
 	duk_push_c_function(ctx, SystemError_constructor, 2);
--- a/man/CMakeLists.txt	Sat Feb 13 10:09:00 2021 +0100
+++ b/man/CMakeLists.txt	Sat Feb 13 22:15:16 2021 +0100
@@ -29,8 +29,10 @@
 	${man_SOURCE_DIR}/irccd-api-chrono.3
 	${man_SOURCE_DIR}/irccd-api-directory.3
 	${man_SOURCE_DIR}/irccd-api-file.3
+	${man_SOURCE_DIR}/irccd-api-hook.3
 	${man_SOURCE_DIR}/irccd-api-logger.3
 	${man_SOURCE_DIR}/irccd-api-plugin.3
+	${man_SOURCE_DIR}/irccd-api-rule.3
 	${man_SOURCE_DIR}/irccd-api-server.3
 	${man_SOURCE_DIR}/irccd-api-system.3
 	${man_SOURCE_DIR}/irccd-api-timer.3
--- a/man/irccd-api-chrono.3	Sat Feb 13 10:09:00 2021 +0100
+++ b/man/irccd-api-chrono.3	Sat Feb 13 22:15:16 2021 +0100
@@ -23,6 +23,7 @@
 .\" SYNOPSIS
 .Sh SYNOPSIS
 .Fn Irccd.Chrono
+.Vt Irccd.Chrono.prototype.elapsed
 .Fn Irccd.Chrono.prototype.reset
 .\" DESCRIPTION
 .Sh DESCRIPTION
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/irccd-api-hook.3	Sat Feb 13 22:15:16 2021 +0100
@@ -0,0 +1,70 @@
+.\"
+.\" Copyright (c) 2013-2021 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-HOOK 3
+.Os
+.\" NAME
+.Sh NAME
+.Nm Irccd.Hook
+.Nd irccd hook API
+.\" SYNOPSIS
+.Sh SYNOPSIS
+.Fn Irccd.Hook.add "name, path"
+.Fn Irccd.Hook.list
+.Fn irccd.Hook.remove "name"
+.\" DESCRIPTION
+.Sh DESCRIPTION
+Add, remove and list hooks.
+.\" METHODS
+.Sh METHODS
+.\" Irccd.Hook.add
+The
+.Fn Irccd.Hook.add
+method adds the rule specified by
+.Fa path
+with the identifier
+.Fa name .
+The API does not check the presence of the hook file and therefore can be used
+before the hook actually exists on the filesystem.
+.Pp
+.\" Irccd.Hook.list
+The
+.Fn Irccd.Hook.list
+method return an array of object for all hooks loaded. Each entry consists of
+two properties:
+.Fa name
+and
+.Fa path
+which denotes the hook's name and its filesystem path respectively.
+.Pp
+.\" Irccd.Hook.remove
+The
+.Fn Irccd.Hook.remove
+method removes the hook specified by
+.Fa name .
+.\" EXCEPTIONS
+.Sh EXCEPTIONS
+.Bl -tag -width Er
+.It Bq Er Error
+Thrown from
+.Fn Irccd.Hook.add
+if a hook with
+.Fa name
+already exists.
+.El
+.\" SEE ALSO
+.Sh SEE ALSO
+.Xr irccd-api 3
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/irccd-api-rule.3	Sat Feb 13 22:15:16 2021 +0100
@@ -0,0 +1,96 @@
+.\"
+.\" Copyright (c) 2013-2021 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-RULE 3
+.Os
+.\" NAME
+.Sh NAME
+.Nm Irccd.Rule
+.Nd irccd rule API
+.\" SYNOPSIS
+.Sh SYNOPSIS
+.Vt Irccd.Rule.Accept
+.Vt Irccd.Rule.Drop
+.Fn Irccd.Rule.add "index, rule"
+.Fn Irccd.Rule.clear
+.Fn Irccd.Rule.list
+.Fn Irccd.Rule.remove "index"
+.\" DESCRIPTION
+.Sh DESCRIPTION
+This module let you inspect, manage and/or create or delete rules.
+.Pp
+Rules are created and obtained in JSON form with the following properties:
+.Pp
+.Bl -tag -compact -width "channels (array)"
+.It Va action No (int)
+Action to do for this rule. Must be either
+.Fa Irccd.Rule.Accept
+or
+.Fa Irccd.Rule.Drop .
+.It Va servers No (array)
+List of servers to match as array of strings targeting server identifiers.
+.It Va channels No (array)
+List of channels to match
+.It Va origins No (array)
+List of origins (the full nickname and user hostname) to match.
+.It Va events No (array)
+List of events to match. See
+.Xr irccd 1
+manual page for available values.
+.It Va plugins No (array)
+List of plugins to match as array of string targeting plugin identifiers.
+.El
+.\" METHODS
+.Sh METHODS
+.\" Irccd.Rule.add
+The
+.Fn Irccd.Rule.add
+method adds the new
+.Ar rule
+at the given
+.Ar index
+which can be null, in this case the rule is added to the end.
+.Pp
+.\" Irccd.Rule.clear
+The
+.Fn Irccd.Rule.clear
+method remove all rules.
+.Pp
+.\" Irccd.Rule.list
+The
+.Fn Irccd.Rule.list
+method returns all rules as an array of JSON description.
+.Pp
+.\" Irccd.Rule.remove
+The
+.Fn Irccd.Rule.remove
+function removes the rule at the given
+.Ar index .
+.\" EXCEPTIONS
+.Sh EXCEPTIONS
+.Bl -tag -width Er
+.It Bq Er RangeError
+Thrown in
+.Fn Irccd.Rule.remove
+if the
+.Ar index
+value was out of bounds.
+.It Bq Er TypeError
+If the rule action was invalid.
+.El
+.\" SEE ALSO
+.Sh SEE ALSO
+.Xr irccd-api 3
--- a/man/irccd-api-timer.3	Sat Feb 13 10:09:00 2021 +0100
+++ b/man/irccd-api-timer.3	Sat Feb 13 22:15:16 2021 +0100
@@ -1,5 +1,5 @@
 .\"
-.\" Copyright (c) 2013-2020 David Demelier <markand@malikania.fr>
+.\" Copyright (c) 2013-2021 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
--- a/man/irccd-api-util.3	Sat Feb 13 10:09:00 2021 +0100
+++ b/man/irccd-api-util.3	Sat Feb 13 22:15:16 2021 +0100
@@ -1,5 +1,5 @@
 .\"
-.\" Copyright (c) 2013-2020 David Demelier <markand@malikania.fr>
+.\" Copyright (c) 2013-2021 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
@@ -31,7 +31,7 @@
 This module provides various utilities.
 .\" METHODS
 .Sh METHODS
-.\" Irccd.Util.Cut
+.\" Irccd.Util.cut
 The
 .Fn Irccd.Util.cut
 method splits the
--- a/man/irccd-api.3	Sat Feb 13 10:09:00 2021 +0100
+++ b/man/irccd-api.3	Sat Feb 13 22:15:16 2021 +0100
@@ -27,8 +27,10 @@
 .Vt Irccd.Chrono
 .Vt Irccd.Directory
 .Vt Irccd.File
+.Vt Irccd.Hook
 .Vt Irccd.Logger
 .Vt Irccd.Plugin
+.Vt Irccd.Rule
 .Vt Irccd.Server
 .Vt Irccd.System
 .Vt Irccd.Timer
@@ -320,13 +322,13 @@
 The following constants properties are defined:
 .Pp
 .Bl -tag
-.It Va Irccd.version No (object)
+.It Va Irccd.Version No (object)
 See below.
-.It Va Irccd.version.major No (int)
+.It Va Irccd.Version.Major No (int)
 The major irccd version.
-.It Va Irccd.version.minor No (int)
+.It Va Irccd.Version.Minor No (int)
 The minor irccd version.
-.It Va Irccd.version.patch No (int)
+.It Va Irccd.Version.Patch No (int)
 The patch irccd version.
 .El
 .Pp
@@ -336,10 +338,6 @@
 .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
@@ -347,8 +345,10 @@
 .Xr irccd-api-chrono 3 ,
 .Xr irccd-api-directory 3 ,
 .Xr irccd-api-file 3 ,
+.Xr irccd-api-hook 3 ,
 .Xr irccd-api-logger 3 ,
 .Xr irccd-api-plugin 3 ,
+.Xr irccd-api-rule 3 ,
 .Xr irccd-api-server 3 ,
 .Xr irccd-api-system 3 ,
 .Xr irccd-api-timer 3 ,