Mercurial > irccd
view man/libirccd-subst.3 @ 1091:52be05336310
irccdctl: misc cleanups
author | David Demelier <markand@malikania.fr> |
---|---|
date | Wed, 21 Jul 2021 16:06:36 +0200 |
parents | c30f0dc9d614 |
children | f06e9761cc90 |
line wrap: on
line source
.\" .\" 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 LIBIRCCD-SUBST 3 .Os .\" NAME .Sh NAME .Nm libirccd-subst .Nd create templated string .\" SYNOPSIS .Sh SYNOPSIS .In irccd/subst.h .Ft ssize_t .Fo irc_subst .Fa "char *dst" .Fa "size_t dstsz" .Fa "const char *template" .Fa "const struct irc_subst *subst" .Fc .\" DESCRIPTION .Sh DESCRIPTION This header provides functions to generate templated strings using a custom format as defined in .Xr irccd-templates 7 . .Pp The .Vt "struct irc_subst_keyword" and .Vt "struct irc_subst" are declared as: .Bd -literal struct irc_subst_keyword { const char *key; const char *value; }; .Ed .Bd -literal struct irc_subst { time_t time; enum irc_subst_flags flags; const struct irc_subst_keyword *keywords; size_t keywordsz; }; .Ed .Pp The fields of .Vt "struct irc_subst_keyword" are: .Bl -tag -width 10n .It Va key The keyword name. .It Va value The keyword value. .El .Pp The fields of .Vt "struct irc_subst" are: .Bl -tag -width 10n .It Va time The timestamp if the template contains time formatting and .Dv IRC_SUBST_DATE is present in .Va flags . .It Va flags The allowed formats in the source string as an OR'ed combination, see below. .It Va keywords An array of user keywords to replace in the source string. .It Va keywordsz The number of elements present in .Va keywords field. .El .Pp The .Vt "enum irc_subst_flags" is declared as: .Bd -literal enum irc_subst_flags { IRC_SUBST_DATE = (1 << 0), IRC_SUBST_KEYWORDS = (1 << 1), IRC_SUBST_ENV = (1 << 2), IRC_SUBST_SHELL = (1 << 3), IRC_SUBST_IRC_ATTRS = (1 << 4), IRC_SUBST_SHELL_ATTRS = (1 << 5) }; .Ed .Pp The following enumerators are available: .Bl -tag -width IRC_SUBST_SHELL_ATTRS .It Dv IRC_SUBST_DATE Allows date formatting. In that case the .Va time field should not be 0. .It Dv IRC_SUBST_KEYWORDS Allows keywords substitutions, the fields .Va keywords and .Va keywordsz should be set but are still optional. .It Dv IRC_SUBST_ENV Allows environment variables substitution. .It Dv IRC_SUBST_IRC_ATTRS Allows IRC colors and attributes. This is mutually exclusive with .Dv IRC_SUBST_SHELL_ATTRS . .It Dv IRC_SUBST_SHELL_ATTRS Allows shell escape sequences for color and attributes. This is mutually exclusive with .Dv IRC_SUBST_IRC_ATTRS . .El .Pp The .Fn irc_subst functions convert the NUL terminated string .Fa template and store the result into the non-NULL .Fa dst buffer of .Fa dstsz max size. The function never writes more than .Fa dstsz bytes including the NUL terminator. The non-NULL .Fa subst argument controls the substitution parameters and allowed flags. .\" RETURN VALUES .Sh RETURN VALUES The .Fn irc_subst function return the number of bytes written in .Fa dst not including the NUL terminator. If an error occurs, -1 is returned and .Va errno is set to indicate the error. .\" ERRORS .Sh ERRORS The function .Fn irc_subst may set one of the following error: .Bl -tag -width Er .It Bq Er ENOMEM Not enough space was available in .Fa dst . .It Bq Er EINVAL The source string contain invalid escape sequences or syntax. .El .\" EXAMPLES .Sh EXAMPLES This call will replace the keywords .Dq fruit and .Dq dessert along with the time formatting. .Bd -literal struct irc_subst subst = { .time = time(NULL), .flags = IRC_SUBST_KEYWORDS | IRC_SUBST_DATE, .keywordsz = 2, .keywords = (const struct irc_subst_keyword[]) { { "fruit", "orange" }, { "dessert", "tiramisu" } } }; char output[512]; const char *input = "You've eaten #{fruit} and #{dessert} on %H:%M"; irc_subst(output, sizeof (output), input, &subst); /* output == You've eaten orange and tiramisu on 23:23 */ .Ed .\" SEE ALSO .Sh SEE ALSO .Xr irccd-templates 7 , .Xr libirccd 3