Mercurial > irccd

annotate man/irccd-api-util.3 @ 1136:f06e9761cc90

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
misc: update copyright years
author David Demelier <markand@malikania.fr>
date Sun, 02 Jan 2022 10:20:57 +0100
parents ec5461750efd
children c165e975f144
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
932
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
1 .\"
1136
f06e9761cc90 misc: update copyright years
David Demelier <markand@malikania.fr>
parents: 1002
diff changeset
2 .\" Copyright (c) 2013-2022 David Demelier <markand@malikania.fr>
932
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
3 .\"
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
4 .\" Permission to use, copy, modify, and/or distribute this software for any
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
5 .\" purpose with or without fee is hereby granted, provided that the above
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
6 .\" copyright notice and this permission notice appear in all copies.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
7 .\"
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
15 .\"
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
16 .Dd @IRCCD_MAN_DATE@
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
17 .Dt IRCCD-API-UTIL 3
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
18 .Os
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
19 .\" NAME
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
20 .Sh NAME
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
21 .Nm Irccd.Util
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
22 .Nd irccd utilities API
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
23 .\" SYNOPSIS
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
24 .Sh SYNOPSIS
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
25 .Fn Irccd.Util.cut "data, maxc, maxl"
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
26 .Fn Irccd.Util.format "input, parameters"
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
27 .Fn Irccd.Util.splithost "user"
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
28 .Fn Irccd.Util.splituser "user"
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
29 .\" DESCRIPTION
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
30 .Sh DESCRIPTION
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
31 This module provides various utilities.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
32 .\" METHODS
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
33 .Sh METHODS
1002
ec5461750efd man: add Irccd.Rule and Irccd.Hook manual pages
David Demelier <markand@malikania.fr>
parents: 963
diff changeset
34 .\" Irccd.Util.cut
932
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
35 The
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
36 .Fn Irccd.Util.cut
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
37 method splits the
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
38 .Fa data
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
39 into several lines returned as an array of strings. It may be a string or an
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
40 array of strings.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
41 .Pp
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
42 The argument
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
43 .Fa maxc
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
44 controls the maximum of characters allowed per line, it can be a positive
963
371e1cc2c697 tests: add 80% of the Javascript API
David Demelier <markand@malikania.fr>
parents: 932
diff changeset
45 integer. If undefined is given, a default of 72 is used. The argument
932
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
46 .Fa maxl
963
371e1cc2c697 tests: add 80% of the Javascript API
David Demelier <markand@malikania.fr>
parents: 932
diff changeset
47 controls the maximum of lines allowed. It can be a positive integer or
371e1cc2c697 tests: add 80% of the Javascript API
David Demelier <markand@malikania.fr>
parents: 932
diff changeset
48 undefined for an infinite list. An empty list may be returned if empty strings
371e1cc2c697 tests: add 80% of the Javascript API
David Demelier <markand@malikania.fr>
parents: 932
diff changeset
49 were found.
932
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
50 .Pp
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
51 .\" Irccd.Util.format
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
52 The
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
53 .Fn Irccd.Util.format
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
54 method formats the string
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
55 .Fa input
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
56 according to the template system. The object
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
57 .Fa parameters
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
58 should be filled for each keyword to replace in the input. The reserved keyword
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
59 .Dq date
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
60 must be used to replace a date if necessary and should contain an integer
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
61 timestamp. The function returns the converted text.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
62 .Pp
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
63 Be very careful when you use this function with untrusted input. Do never pass
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
64 untrusted content (e.g. user message) as input parameter.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
65 .Pp
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
66 For example, the following code is unsafe:
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
67 .Bd -literal -offset Ds
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
68 function onMessage(server, channel, origin, message)
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
69 {
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
70 // DON'T DO THIS.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
71 server.message(channel, Irccd.Util.format("@{red}" + message + "@{}");
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
72 }
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
73 .Ed
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
74 .Pp
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
75 If a user sends a message like ${HOME}, it will prints the user home directory,
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
76 which is a high security issue if you have environment variables with passwords.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
77 .Pp
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
78 Instead, always use a literal string using a replacement with the user input:
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
79 .Bd -literal -offset Ds
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
80 function onMessage(server, channel, origin, message)
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
81 {
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
82 // CORRECT.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
83 server.message(channel, Irccd.Util.format("@{red}#{message}@{}", {
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
84 message: message
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
85 });
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
86 }
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
87 .Ed
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
88 .Pp
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
89 .\" Irccd.Util.splithost
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
90 The
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
91 .Fn Irccd.Util.splithost
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
92 method returns the host component from the specified
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
93 .Fa user
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
94 string.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
95 .Pp
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
96 .\" Irccd.Util.splituser
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
97 The
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
98 .Fn Irccd.Util.splituser
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
99 method returns the user component from the specified
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
100 .Fa user
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
101 string.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
102 .\" EXCEPTIONS
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
103 .Sh EXCEPTIONS
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
104 .Bl -tag -width Er
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
105 .It Bq Er RangeError
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
106 If
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
107 .Fa maxl
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
108 or
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
109 .Fa maxc
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
110 are negative numbers.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
111 .It Bq Er RangeError
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
112 If one word length was bigger than
963
371e1cc2c697 tests: add 80% of the Javascript API
David Demelier <markand@malikania.fr>
parents: 932
diff changeset
113 .Fa maxc
371e1cc2c697 tests: add 80% of the Javascript API
David Demelier <markand@malikania.fr>
parents: 932
diff changeset
114 or the number of lines would exceed
371e1cc2c697 tests: add 80% of the Javascript API
David Demelier <markand@malikania.fr>
parents: 932
diff changeset
115 .Fa maxl
371e1cc2c697 tests: add 80% of the Javascript API
David Demelier <markand@malikania.fr>
parents: 932
diff changeset
116 argument.
932
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
117 .It Bq Er TypeError
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
118 If
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
119 .Fa data
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
120 is not a string or a list of strings.
0e11221c9bcc man: split irccd-api into individual ones
David Demelier <markand@malikania.fr>
parents:
diff changeset
121 .El