# HG changeset patch # User David Demelier # Date 1613601039 -3600 # Node ID c30f0dc9d614d66507b6b2c8ea159ed946046b62 # Parent c02a5c9cdde4b8fa523d338d33a4872695adacbd man: add libirccd-subst.3 manual page diff -r c02a5c9cdde4 -r c30f0dc9d614 man/CMakeLists.txt --- a/man/CMakeLists.txt Wed Feb 17 22:56:50 2021 +0100 +++ b/man/CMakeLists.txt Wed Feb 17 23:30:39 2021 +0100 @@ -41,6 +41,7 @@ ${man_SOURCE_DIR}/libirccd-log.3 ${man_SOURCE_DIR}/libirccd-rule.3 ${man_SOURCE_DIR}/libirccd-util.3 + ${man_SOURCE_DIR}/libirccd-subst.3 ${man_SOURCE_DIR}/libirccd.3 ) diff -r c02a5c9cdde4 -r c30f0dc9d614 man/libirccd-subst.3 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/libirccd-subst.3 Wed Feb 17 23:30:39 2021 +0100 @@ -0,0 +1,185 @@ +.\" +.\" Copyright (c) 2013-2021 David Demelier +.\" +.\" 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