op public repos

Blob

Date:: Fri Jan 6 18:25:13 2023 UTC
Message:: template.7: fix double spaces diff from Josiah Frentsos and clue from tb@, thanks! (I can't read.)
Actions:: History | Blame | Raw File
1 .\" Copyright (c) 2022 Omar Polo <op@openbsd.org>
2 .\"
3 .\" Permission to use, copy, modify, and distribute this software for any
4 .\" purpose with or without fee is hereby granted, provided that the above
5 .\" copyright notice and this permission notice appear in all copies.
6 .\"
7 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
8 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
9 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
10 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
11 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
12 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
13 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
14 .\"
15 .Dd January 06, 2022
16 .Dt TEMPLATE 7
17 .Os
18 .Sh NAME
19 .Nm template
20 .Nd templating language
21 .Sh DESCRIPTION
22 .Nm
23 is a language used to define programs that output data in some way.
24 These programs are called
25 .Dq templates .
26 A
27 .Nm
28 file is assumed to be compiled using the
29 .Xr template 1
30 utility into C code, to be further compiled as part of a bigger
31 application.
32 The language itself is format-agnostic and can thus be used to produce
33 various type of outputs.
34 .Pp
35 There are two special sequences:
36 .Bl -tag -width 9m
37 .It Cm {{ Ar ... Cm }}
38 used for
39 .Nm
40 special syntax.
41 .It Cm {! Ar ... Cm !}
42 used to include literal C code.
43 This is the only special syntax permitted as top-level, except for block
44 definition and includes.
45 .El
46 .Pp
47 The basic unit of a
48 .Nm
49 file is the block.
50 Each block is turned into a C function that output its content via some
51 provided functions.
52 Here's an example of a block:
53 .Bd -literal -offset indent
54 {{ define tp_base(struct template *tp, const char *title) }}
55 <!doctype html>
56 <html>
57 	<head>
58 		<title>{{ title }}</title>
59 	</head>
60 	<body>
61 		{{ render tp->tp_body(tp) }}
62 	</body>
63 </html>
64 {{ end }}
65 .Ed
66 .Ss SPECIAL SYNTAX
67 This section is a reference for all the special syntaxes supported.
68 .Bl -tag -width Ds
69 .It Cm {{ Ic include Ar file Cm }}
70 Include additional template files.
71 .It Cm {{ Ic define Ar name Ns ( Ar arguments ... ) Cm }} Ar body Cm {{ Ic end Cm }}
72 Defines the block
73 .Ar name
74 with the given
75 .Ar arguments .
76 .Ar body
77 will be outputted as-is via the provided functions
78 .Pq i.e.\& is still escaped eventually
79 and can contain all the special syntaxes documented here except
80 .Ic include
81 and
82 .Ic define .
83 .It Cm {{ Ic render Ar expression() Cm }}
84 Executes
85 .Ar expression()
86 and terminate the template if it returns -1.
87 It's used to render (call) another template.
88 .It Cm {{ Ic printf Ar fmt , Ar arguments ... Cm }}
89 Outputs the string that would be produced by calling
90 .Xr printf 3
91 with the given
92 .Ar fmt
93 format string and the given
94 .Ar arguments .
95 .It Cm {{ Ic if Ar expr Cm }} Ar ... Cm {{ Ic elseif Ar expr Cm }} Ar ... Cm {{ Ic else Cm }} Ar ... Cm {{ Ic end Cm }}
96 Conditional evaluation.
97 .Ic elseif
98 can be provided zero or more times,
99 .Ic else
100 only zero or one time and always for last.
101 .It Cm {{ Ic for Ar ... ; Ar ... ; Ar ... Cm }} Ar ... Cm {{ Ic end Cm }}
102 Looping construct similar to the C for loop.
103 .It Cm {{ Ic tailq-foreach Ar var head fieldname Cm }} Ar .. Cm {{ Ic end Cm }}
104 Looping construct similar to the queue.h macro TAILQ_FOREACH.
105 .It Cm {{ Ic while Ar ... Cm }} Ar ... Cm {{ Ic end Cm }}
106 Looping construct similar to the C while loop.
107 .It Cm {{ Ar expression Cm \&| Ic unsafe Cm }}
108 Output
109 .Ar expression
110 as-is.
111 .It Cm {{ Ar expression Cm \&| Ic urlescape Cm }}
112 Output
113 .Ar expression
114 escaped in a way that can be made part of an URL.
115 .It Cm {{ Ar expression Cm }}
116 Output
117 .Ar expression
118 with the default escaping.
119 .El
120 .Sh SEE ALSO
121 .Xr template 1
122 .Sh AUTHORS
123 .An -nosplit
124 The
125 .Nm
126 reference was written by
127 .An Omar Polo Aq Mt op@openbsd.org .