gemplate

README

Command gemplate

Command gemplate compiles data-driven templates for generating textual output into Go. This template language closely matches the standard library, except that it is meant to be compiled ahead of time and that the templates are statically typed.

With one exception, the template language understood by gemplate exactly matches syntatically the text/template package in the standard library. That one exception is that {{define ...}} blocks require two parameters instead of one. The additional parameter specifies a static type for the template.

Install

The package can be installed from the command line using the go tool. Any version of Go should work.

go install git.sr.ht/~rj/gemplate@latest

Basic usage information can be obtained by asking for help from the command line.

gemplate --help

Getting Started

To start, you will need a template. One can begin with the an example from the standard library. Copy the following into a file called letter.tmpl.

Dear {{.Name}},
{{if .Attended}}
It was a pleasure to see you at the wedding.
{{- else}}
It is a shame you couldn't make it to the wedding.
{{- end}}
{{with .Gift -}}
Thank you for the lovely {{.}}.
{{end}}
Best wishes,
Josie

Unlike when executing the template at runtime, the compiler needs to know the static types for the templates. For example, to check that the field .Attended is a boolean, and .Gift is a string. This is accomplished by parsing the existing Go source. In the same directory, create a driver for the template, which will also describe the necessary types.

package main

import (
	"log"
 	"os"
)

// Prepare some data to insert into the template.
type Recipient struct {
	Name, Gift string
	Attended   bool
}

// Contents to be printed.  Details are ellided for brevity.
// See testdata/example1.
var recipients = []Recipient{}

func main() {
 	for _, r := range recipients {
  		err := letter(os.Stdout, &r)
  		if err != nil {
 			  log.Println("executing template:", err)
  		}
 	}
}

Note that the function main calls out to letter, but that function has not yet been defined. Before the package can be run or built, the template needs to be compiled:

gemplate --output=letter.go --dot="*Recipient" letter.tmpl

And then the driver can be run:

go run main.go letter.go

Differences from the Standard Library

All of the documentation from the standard library basically holds. The key exception is that the syntax of nested template definitions takes an additional parameter. The second parameter is defines the static type for the cursor (often called dot). For example, the following two template definitions:

{{define "T1" "string"}}ONE{{end}}
{{define "T2" "*T"}}TWO{{end}}

The above will, after being compiled to Go source code, create the following two functions:

func T1(io.Writer, string) error
func T2(io.Writer, *T) error

Contribute

To submit bug reports and suggestions, please use the issue tracker.

Discussions occur using the mailing list. The mailing list can also be used to submit patches.

Scope

This package aims to provide a template syntax that matches the package text/template from the standard library, with limited changes to support static typing of the template.

Related Projects

• text/template: Package template implements data-driven templates for generating textual output.
• templ: Build HTML with Go.

License

BSD (c) Robert Johnstone

Documentation

Overview

gemplate compiles templates into Go source

The standard library includes a template processor, but this processor uses dynamic types and reflection. Instead, the template can be compiled ahead of time to get improved performance, as well as static type safety.

Usage:

gemplate [options]...
gemplate (--help | -h)
gemplate (--version | -v)

Required Arguments:

<in>
    Input filename.

Optional Arguments:

-o=<string>, --output=<string>
	Output filename. (default "-")
-p=<string>, --package=<string>
	Package name.