Mercurial > irccd

comparison man/irccd-api-util.3 @ 932:0e11221c9bcc

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