gotemplate

gotemplate provides a small Go command-line program that executes templates, using the text/template package from the Go standard library.

It is also a library that can be extended in order to add custom functions to the templates.

Goals

gotemplate is designed to facilitate producing markdown documentation for code. I created it so that I can include working code samples that can be easily tested, instead of copying them by hand to a README file.

It is not suitable for producing HTML. An HTML generator should use html/template instead of text/template, and also have more features, such as layouts (themes).

Design

Executing Go templates requires three main inputs:

A Function Map

A Function map (template.FuncMap) provides custom functions.

The gotemplate module defines the file function that reads a file. The library does not add it automatically to the templates, but the main executable does. This is provided as an example, but it is also useful for including code samples in documentation. If you want more functions, write your own.

The templates

These are the files parsed into text/template.Template. The function map should be defined before parsing the templates, because it is used during parsing.

The data model

This is the data passed to the Template.Execute(). Gotemplate uses a map[any]any data structure. The map is built by parsing yaml or json files, and by command-line arguments.

Example

This README.md file was generated by running the script:

readme.sh

#!/bin/sh

# generates README.md

gotemplate exec -o README.md -t README.tpl doc/common/*.tpl doc/*.tpl 

Using the templates:

• doc/common/file.tpl
• doc/README.tpl

It can also be generated by running the alternate script:

build.sh

#!/bin/sh

# generates README.md

gotemplate build -c doc/build.yaml -o .

which uses the configuration file:

doc/build.yaml

input_dir: ./
input_ext: .tpl
output_ext: .md 
templates:
- dir: common
  patterns:
  - "*.tpl"

This script could generate multiple output files, but we use just one.

main

The main executable also serves as an example about how to add custom functions to the templates:

main/gotemplate.go

package main

import (
	"fmt"

	"melato.org/command"
	"melato.org/gotemplate"
	"melato.org/gotemplate/cli"
	"melato.org/gotemplate/funcs"
)

var version string

func main() {
	var config gotemplate.Config
	funcs.AddFuncs(&config)
	cmd := cli.Command(&config)
	cmd.Command("version").NoConfig().RunFunc(func() {
		fmt.Printf("%s\n", version)
	}).Short("print version")
	command.Main(cmd)
}

commands

exec

The exec command uses command line arguments to specify everything. It:

• parses a set of associated templates
• builds a data model
• executes one template and produces one output file

build

The build command uses a yaml configuration file to specify most parameters. The configuration file specifies:

• a set of common templates
• a map to uses as the data model
• an input directory of templates.

Each input template is parsed after cloning the common templates. Therefore it has access to the common templates, but not to other input templates.

help

The help subcommands are meant to provide documentation for the template functions.