commit e733e1f3e0661718f83f59220c017cc3578207b5 from: Omar Polo date: Sun Dec 04 16:37:08 2022 UTC template: update documentation commit - c11015c29edc292ed928a060d039ebaba908b720 commit + e733e1f3e0661718f83f59220c017cc3578207b5 blob - 5868d695a982885599bb34dc7d5ff261f9109f77 blob + 4c3a752a31718ca8ad29543f9f2f61b00c13cc4e --- template/template.1 +++ template/template.1 @@ -12,7 +12,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd September 27, 2022 +.Dd November 25, 2022 .Dt TEMPLATE 1 .Os .Sh NAME @@ -21,6 +21,7 @@ .Sh SYNOPSIS .Nm .Op Fl G +.Op Fl o Ar out .Op Ar .Sh DESCRIPTION .Nm @@ -39,18 +40,15 @@ Do not emit debug info in the generated source. It's disabled by default, unless .Nm is reading from standard input. +.It Fl o Ar out +Write output to file. +.Ar out +will be created or truncated if exists and will be removed if +.Nm +encounters any error. .El .Sh EXIT STATUS .Ex -.Sh EXAMPLES -The following example shows how to use -.Nm -in a Makefile: -.Bd -literal -offset indent -\&.SUFFIXES: .c .tmpl -\&.c.tmpl: - template $< > $@ || rm \-f $@ -.Ed .Sh SEE ALSO .Xr template 7 .Sh AUTHORS @@ -70,10 +68,11 @@ The generated code assumes that a variable called .Va tp of type .Vt struct template * -is in scope inside the template. +is in scope inside each block. .It Each block may have additional variables used for the template -generation: to avoid clashes, don't define variables with the +generation implicitly defined: to avoid clashes, don't name variables +or arguments with the .Sq tp_ prefix. .It blob - /dev/null blob + 31b32697b9affdd4231edc3b70f8abaf0bb8300c (mode 644) --- /dev/null +++ template/template.7 @@ -0,0 +1,125 @@ +.\" Copyright (c) 2022 Omar Polo +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd November 25, 2022 +.Dt TEMPLATE 7 +.Os +.Sh NAME +.Nm template +.Nd templating language +.Sh DESCRIPTION +.Nm +is a language used to define programs that output data in some way. +These programs are called +.Dq templates . +A +.Nm +file is assumed to be compiled using the +.Xr template 1 +utility into C code, to be further compiled as part of a bigger +application. +The language itself is format-agnostic and can thus be used to produce +various type of outputs. +.Pp +There are two special sequences: +.Bl -tag -width 9m +.It Cm {{ Ar ... Cm }} +used for +.Nm +special syntax. +.It Cm {! Ar ... Cm !} +used to include literal C code. +This is the only special syntax permitted as top-level, except for block +definition and includes. +.El +.Pp +The basic unit of a +.Nm +file is the block. +Each block is turned into a C function that output its content via some +provided functions. +Here's an example of a block: +.Bd -literal -offset indent +{{ define tp_base(struct template *tp, const char *title) }} + + + + {{ title }} + + + {{ render tp->tp_body(tp) }} + + +{{ end }} +.Ed +.Ss SPECIAL SYNTAX +This section is a reference for all the special syntaxes supported. +.Bl -tag -indent Ds +.It Cm {{ Ic include Ar file Cm }} +Include additional template files. +.It Cm {{ Ic define Ar name Ns ( Ar arguments ... ) Cm }} Ar body Cm {{ Ic end Cm }} +Defines the block +.Ar name +with the given +.Ar arguments . +.Ar body +will be outputted as-is via the provided functions +.Pq i.e.\& is still escaped eventually +and can contain all the special syntaxes documented here except +.Ic include +and +.Ic define . +.It Cm {{ Ic render Ar expression() Cm }} +Executes +.Ar expression() +and terminate the template if it returns -1. +It's used to render (call) another template. +.It Cm {{ Ic printf Ar fmt , Ar arguments ... Cm }} +Outputs the string that would be produced by calling +.Xr printf 3 +with the given +.Ar fmt +format string and the given +.Ar arguments . +.It Cm {{ Ic if Ar expr Cm }} Ar ... Cm {{ Ic elseif Ar expr Cm }} Ar ... Cm {{ Ic else Cm }} Ar ... Cm {{ Ic end Cm }} +Conditional evaluation. +.Ic elseif +can be provided zero or more times, +.Ic else +only zero or one time and always for last. +.It Cm {{ Ic for Ar ... ; Ar ... ; Ar ... Cm }} Ar ... Cm {{ Ic end Cm }} +Looping construct similar to the C loop. +.It Cm {{ Ic tailq-foreach Ar var head fieldname Cm }} Ar .. Cm {{ Ic end Cm }} +Looping construct similar to the queue.h macro TAILQ_FOREACH. +.It Cm {{ Ar expression Cm | Ic unsafe Cm }} +Output +.Ar expression +as-is. +.It Cm {{ Ar expression Cm | Ic urlescape Cm }} +Output +.Ar expression +escaped in a way that can be made part of an URL. +.It Cm {{ Ar expression Cm }} +Output +.Ar expression +with the default escaping. +.El +.Sh SEE ALSO +.Xr template 1 +.Sh AUTHORS +.An -nosplit +The +.Nm +reference was written by +.Ar Omar Polo Aq Mt op@openbsd.org .