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