1 6509b181 2022-12-30 thomas .\" Copyright (c) 2022 Omar Polo <op@openbsd.org>
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.
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.
15 ff945768 2023-01-07 thomas .Dd January 06, 2022
16 6509b181 2022-12-30 thomas .Dt TEMPLATE 7
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
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 .
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.
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 }}
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.
47 6509b181 2022-12-30 thomas The basic unit of a
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>
58 6509b181 2022-12-30 thomas <title>{{ title }}</title>
61 6509b181 2022-12-30 thomas {{ render tp->tp_body(tp) }}
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
74 6509b181 2022-12-30 thomas with the given
75 6509b181 2022-12-30 thomas .Ar arguments .
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
82 6509b181 2022-12-30 thomas .Ic define .
83 6509b181 2022-12-30 thomas .It Cm {{ Ic render Ar expression() Cm }}
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
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,
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 }}
109 6509b181 2022-12-30 thomas .Ar expression
111 e9c42ba8 2023-01-07 thomas .It Cm {{ Ar expression Cm \&| Ic urlescape Cm }}
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 }}
117 6509b181 2022-12-30 thomas .Ar expression
118 6509b181 2022-12-30 thomas with the default escaping.
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
126 6509b181 2022-12-30 thomas reference was written by
127 d0b178c5 2023-01-07 thomas .An Omar Polo Aq Mt op@openbsd.org .
