ksgi

1
.\"	$Id$
2
.\"
3
.\" Copyright (c) 2020 Kristaps Dzonsons <kristaps@bsd.lv>
4
.\"
5
.\" Permission to use, copy, modify, and distribute this software for any
6
.\" purpose with or without fee is hereby granted, provided that the above
7
.\" copyright notice and this permission notice appear in all copies.
8
.\"
9
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16
.\"
17
.Dd $Mdocdate$
18
.Dt KHTML_ELEMAT 3
19
.Os
20
.Sh NAME
21
.Nm khtml_elemat
22
.Nd get element stack depth of kcgihtml
23
.Sh LIBRARY
24
.Lb libkcgihtml
25
.Sh SYNOPSIS
26
.In sys/types.h
27
.In stdarg.h
28
.In stdint.h
29
.In kcgi.h
30
.In kcgihtml.h
31
.Ft size_t
32
.Fo khtml_elemat
33
.Fa "const struct khtmlreq *req"
34
.Fc
35
.Sh DESCRIPTION
36
Gets the current depth of the element stack of
37
.Fa req ,
38
initialised with
39
.Xr khtml_open 3 .
40
This is usually used with
41
.Xr khtml_closeto 3 .
42
.Pp
43
If called before opening any element contexts (i.e., a depth
44
of zero), a subsequent
45
.Xr khtml_closeto 3
46
will close all open scopes.
47
.Sh EXAMPLES
48
The following outputs a simple HTML page.
49
It assumes
50
.Va r
51
is a
52
.Vt struct kreq
53
pointer.
54
For brevity, it does not do any error checking.
55
.Bd -literal -offset indent
56
khttp_head(r, kresps[KRESP_STATUS],
57
  "%s", khttps[KHTTP_200]);
58
khttp_head(r, kresps[KRESP_CONTENT_TYPE],
59
  "%s", kmimetypes[KMIME_TEXT_HTML]);
60
khttp_body(r);
61
khtml_open(&req, r, 0);
62
khtml_elem(&req, KELEM_DOCTYPE);
63
khtml_elem(&req, KELEM_HTML);
64
pos = khtml_elemat(&req); /* save at html */
65
khtml_elem(&req, KELEM_HEAD);
66
khtml_elem(&req, KELEM_TITLE);
67
khtml_puts(&req, "Hello, world.");
68
khtml_closeto(&req, pos); /* to html */
69
khtml_closeelem(&req, 1); /* head */
70
khtml_elem(&req, KELEM_BODY);
71
khtml_puts(&req, "Hello, world");
72
khtml_close(&req);
73
.Ed
74
.Sh SEE ALSO
75
.Xr kcgihtml 3
76
.Sh STANDARDS
77
The referenced HTML5 standard is
78
.Lk https://www.w3.org/TR/html52 HTML5.2 .
79
.Sh AUTHORS
80
Written by
81
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
82
.Sh CAVEATS
83
If called in a scope that's subsequently closed, then a new scope
84
reopened and filled in, a corresponding
85
.Xr khtml_closeto 3
86
will unwind the stack to the new scope.
87
In other words this does not identify a savepoint: it's merely the scope
88
depth.
89