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