template/template.7

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