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