.\"
.\" 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