.TH LIBWEB_HTML 7 2024-08-22 0.4.0 "libweb Library Reference"
.SH NAME
libweb_html \- libweb HTML serializer
.SH SYNOPSIS
.LP
.nf
#include
.fi
.SH DESCRIPTION
This component allows library users to serialize HTML text from a tree
structure composed by one or more
.I struct html_node
objects.
.IR libweb_html (7)
provides the following functions:
.IP \(bu 2
.IR html_node_alloc (3)
allocates a
.I struct html_node
object, consumed by other functions from this component.
.IP \(bu 2
.IR html_node_free (3)
frees the memory from a
.I struct html_node
object previously allocated by a call to
.IR html_node_alloc (3),
plus all of the memory allocated by its children.
.IP \(bu 2
.IR html_node_set_value (3)
sets the HTML value for a
.I struct html_node
object, escaping characters that could cause syntax errors, such as
.B <
.BR "" ( "LESS-THAN SIGN" ).
.IP \(bu 2
.IR html_node_set_value_unescaped (3)
sets the HTML value for a
.I struct html_node
object. As opposed to
.IR html_node_set_value (3),
no escaping is performed.
.IP \(bu 2
.IR html_node_add_attr (3)
adds an attribute to a
.I struct html_node
object.
.IP \(bu 2
.IR html_node_add_child (3)
allocates a children
.I struct html_node
object to another
.I struct html_node
object.
.IP \(bu 2
.IR html_node_add_sibling (3)
adds a sibling
.I struct html_node
object to another
.I struct html_node
object.
.IP \(bu 2
.IR html_serialize (3)
serializes a
.I struct html_node
object and all of its children into a null-terminated string with
the HTML-serialized data.
Typically, a root
.I struct html_node
object is allocated via
.IR html_node_alloc (3),
and child nodes are appended to it via
.IR html_node_add_child (3).
Optionally, values and/or attributes can be added to nodes via
.IR html_node_set_value (3)
and
.IR html_node_add_attr (3),
respectively.
Finally,
.IR html_node_free (3)
shall free the memory used by the root node and all of its children.
.SH EXAMPLE
The example below is a minimal showcase of some of the features
provided by
.IR libweb_html (7),
which prints a minimal HTML file to standard output:
.PP
.in +4n
.EX
#include
#include
#include
#include
int main()
{
int ret = EXIT_FAILURE;
struct dynstr d;
struct html_node *const html = html_node_alloc("html"), *body;
static const char text[] = "testing libweb";
dynstr_init(&d);
if (!html)
{
fprintf(stderr, "html_node_alloc_failed\en");
goto end;
}
else if (!(body = html_node_add_child(html, "body")))
{
fprintf(stderr, "html_node_add_child failed\en");
goto end;
}
else if (html_node_set_value(body, text))
{
fprintf(stderr, "html_node_set_value failed\en");
goto end;
}
else if (html_serialize(html, &d))
{
fprintf(stderr, "html_serialize failed\en");
goto end;
}
printf("%s", d.str);
ret = EXIT_SUCCESS;
end:
dynstr_free(&d);
return ret;
}
.EE
.in
.PP
This program should write the following data over standard output:
.PP
.in +4n
.EX
testing libweb
.EE
.in
.PP
.SH SEE ALSO
.BR html_node_alloc (3),
.BR html_node_free (3),
.BR html_node_set_value (3),
.BR html_node_set_value_unescaped (3),
.BR html_node_add_attr (3),
.BR html_node_add_child (3),
.BR html_node_add_sibling (3),
.BR html_serialize (3),
.BR libweb_html (7).
.SH COPYRIGHT
Copyright (C) 2023-2024 libweb contributors
.P
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.