Blame


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