Mercurial > irccd

comparison man/libirccd-subst.3 @ 1017:c30f0dc9d614

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
man: add libirccd-subst.3 manual page
author David Demelier <markand@malikania.fr>
date Wed, 17 Feb 2021 23:30:39 +0100
parents
children f06e9761cc90
comparison
equal deleted inserted replaced
1016:c02a5c9cdde4 1017:c30f0dc9d614
1 .\"
2 .\" Copyright (c) 2013-2021 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 LIBIRCCD-SUBST 3
18 .Os
19 .\" NAME
20 .Sh NAME
21 .Nm libirccd-subst
22 .Nd create templated string
23 .\" SYNOPSIS
24 .Sh SYNOPSIS
25 .In irccd/subst.h
26 .Ft ssize_t
27 .Fo irc_subst
28 .Fa "char *dst"
29 .Fa "size_t dstsz"
30 .Fa "const char *template"
31 .Fa "const struct irc_subst *subst"
32 .Fc
33 .\" DESCRIPTION
34 .Sh DESCRIPTION
35 This header provides functions to generate templated strings using a custom
36 format as defined in
37 .Xr irccd-templates 7 .
38 .Pp
39 The
40 .Vt "struct irc_subst_keyword"
41 and
42 .Vt "struct irc_subst"
43 are declared as:
44 .Bd -literal
45 struct irc_subst_keyword {
46 const char *key;
47 const char *value;
48 };
49 .Ed
50 .Bd -literal
51 struct irc_subst {
52 time_t time;
53 enum irc_subst_flags flags;
54 const struct irc_subst_keyword *keywords;
55 size_t keywordsz;
56 };
57 .Ed
58 .Pp
59 The fields of
60 .Vt "struct irc_subst_keyword"
61 are:
62 .Bl -tag -width 10n
63 .It Va key
64 The keyword name.
65 .It Va value
66 The keyword value.
67 .El
68 .Pp
69 The fields of
70 .Vt "struct irc_subst"
71 are:
72 .Bl -tag -width 10n
73 .It Va time
74 The timestamp if the template contains time formatting and
75 .Dv IRC_SUBST_DATE
76 is present in
77 .Va flags .
78 .It Va flags
79 The allowed formats in the source string as an OR'ed combination, see below.
80 .It Va keywords
81 An array of user keywords to replace in the source string.
82 .It Va keywordsz
83 The number of elements present in
84 .Va keywords
85 field.
86 .El
87 .Pp
88 The
89 .Vt "enum irc_subst_flags"
90 is declared as:
91 .Bd -literal
92 enum irc_subst_flags {
93 IRC_SUBST_DATE = (1 << 0),
94 IRC_SUBST_KEYWORDS = (1 << 1),
95 IRC_SUBST_ENV = (1 << 2),
96 IRC_SUBST_SHELL = (1 << 3),
97 IRC_SUBST_IRC_ATTRS = (1 << 4),
98 IRC_SUBST_SHELL_ATTRS = (1 << 5)
99 };
100 .Ed
101 .Pp
102 The following enumerators are available:
103 .Bl -tag -width IRC_SUBST_SHELL_ATTRS
104 .It Dv IRC_SUBST_DATE
105 Allows date formatting. In that case the
106 .Va time
107 field should not be 0.
108 .It Dv IRC_SUBST_KEYWORDS
109 Allows keywords substitutions, the fields
110 .Va keywords
111 and
112 .Va keywordsz
113 should be set but are still optional.
114 .It Dv IRC_SUBST_ENV
115 Allows environment variables substitution.
116 .It Dv IRC_SUBST_IRC_ATTRS
117 Allows IRC colors and attributes. This is mutually exclusive with
118 .Dv IRC_SUBST_SHELL_ATTRS .
119 .It Dv IRC_SUBST_SHELL_ATTRS
120 Allows shell escape sequences for color and attributes. This is mutually
121 exclusive with
122 .Dv IRC_SUBST_IRC_ATTRS .
123 .El
124 .Pp
125 The
126 .Fn irc_subst
127 functions convert the NUL terminated string
128 .Fa template
129 and store the result into the non-NULL
130 .Fa dst
131 buffer of
132 .Fa dstsz
133 max size. The function never writes more than
134 .Fa dstsz
135 bytes including the NUL terminator. The non-NULL
136 .Fa subst
137 argument controls the substitution parameters and allowed flags.
138 .\" RETURN VALUES
139 .Sh RETURN VALUES
140 The
141 .Fn irc_subst
142 function return the number of bytes written in
143 .Fa dst
144 not including the NUL terminator. If an error occurs, -1 is returned and
145 .Va errno
146 is set to indicate the error.
147 .\" ERRORS
148 .Sh ERRORS
149 The function
150 .Fn irc_subst
151 may set one of the following error:
152 .Bl -tag -width Er
153 .It Bq Er ENOMEM
154 Not enough space was available in
155 .Fa dst .
156 .It Bq Er EINVAL
157 The source string contain invalid escape sequences or syntax.
158 .El
159 .\" EXAMPLES
160 .Sh EXAMPLES
161 This call will replace the keywords
162 .Dq fruit
163 and
164 .Dq dessert
165 along with the time formatting.
166 .Bd -literal
167 struct irc_subst subst = {
168 .time = time(NULL),
169 .flags = IRC_SUBST_KEYWORDS | IRC_SUBST_DATE,
170 .keywordsz = 2,
171 .keywords = (const struct irc_subst_keyword[]) {
172 { "fruit", "orange" },
173 { "dessert", "tiramisu" }
174 }
175 };
176 char output[512];
177 const char *input = "You've eaten #{fruit} and #{dessert} on %H:%M";
178
179 irc_subst(output, sizeof (output), input, &subst);
180 /* output == You've eaten orange and tiramisu on 23:23 */
181 .Ed
182 .\" SEE ALSO
183 .Sh SEE ALSO
184 .Xr irccd-templates 7 ,
185 .Xr libirccd 3