templateutils

package
v0.0.0-...-476269e Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 31, 2017 License: Apache-2.0 Imports: 11 Imported by: 0

README

Package templateutils provides a set of functions that are designed to make it easier for developers to add template based scripting to their command line tools.

Command line tools written in Go often allow users to specify a template script to tailor the output of the tool to their specific needs. This can be useful both when visually inspecting the data and also when invoking command line tools in scripts. The best example of this is go list which allows users to pass a template script to extract interesting information about Go packages. For example,

go list -f '{{range .Imports}}{{println .}}{{end}}'

prints all the imports of the current package.

The aim of this package is to make it easier for developers to add template scripting support to their tools and easier for users of these tools to extract the information they need. It does this by augmenting the templating language provided by the standard library package text/template in two ways:

  1. It auto generates descriptions of the data structures passed as input to a template script for use in help messages. This ensures that help usage information is always up to date with the source code.

  2. It provides a suite of convenience functions to make it easy for script writers to extract the data they need. There are functions for sorting, selecting rows and columns and generating nicely formatted tables.

For example, if a program passed a slice of structs containing stock data to a template script, we could use the following script to extract the names of the 3 stocks with the highest trade volume.

{{table (cols (head (sort . "Volume" "dsc") 3) "Name" "Volume")}}

The output might look something like this:

Name              Volume
Happy Enterprises 6395624278
Big Company       7500000
Medium Company    300122

The functions head, sort, tables and col are provided by this package.

Documentation

Overview

Package templateutils provides a set of functions that are designed to make it easier for developers to add template based scripting to their command line tools.

Command line tools written in Go often allow users to specify a template script to tailor the output of the tool to their specific needs. This can be useful both when visually inspecting the data and also when invoking command line tools in scripts. The best example of this is go list which allows users to pass a template script to extract interesting information about Go packages. For example, 

go list -f '{{range .Imports}}{{println .}}{{end}}'

prints all the imports of the current package.

The aim of this package is to make it easier for developers to add template scripting support to their tools and easier for users of these tools to extract the information they need. It does this by augmenting the templating language provided by the standard library package text/template in two ways:

1. It auto generates descriptions of the data structures passed as input to a template script for use in help messages. This ensures that help usage information is always up to date with the source code.

2. It provides a suite of convenience functions to make it easy for script writers to extract the data they need. There are functions for sorting, selecting rows and columns and generating nicely formatted tables.

For example, if a program passed a slice of structs containing stock data to a template script, we could use the following script to extract the names of the 3 stocks with the highest trade volume. 

{{table (cols (head (sort . "Volume" "dsc") 3) "Name" "Volume")}}

The output might look something like this: 

Name              Volume
Happy Enterprises 6395624278
Big Company       7500000
Medium Company    300122

The functions head, sort, tables and col are provided by this package.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func CreateTemplate 

func CreateTemplate(name, tmplSrc string, cfg *Config) (*template.Template, error)

CreateTemplate creates a new template, whose source is contained within the tmplSrc parameter and whose name is given by the name parameter. The functions enabled in the cfg parameter will be made available to the template source code specified in tmplSrc. If cfg is nil, all the additional functions provided by templateutils will be enabled.

func GenerateUsageDecorated 

func GenerateUsageDecorated(flag string, i interface{}, cfg *Config) string

GenerateUsageDecorated is similar to GenerateUsageUndecorated with the exception that it outputs the usage information for all the new functions enabled in the Config object cfg. If cfg is nil, help information is printed for all new template functions defined by this package.

Example 
cfg := NewConfig(OptCols)
help := GenerateUsageDecorated("-f", []struct{ X, Y int }{}, cfg)
fmt.Println(help)

Output:

The template passed to the --f option operates on a

[]struct {
	X int
	Y int
}

Some new functions have been added to Go's template language

- 'cols' can be used to extract certain columns from a table consisting of a
  slice or array of structs.  It returns a new slice of structs which contain
  only the fields requested by the caller.   For example, given a slice of structs

  {{cols . "Name" "Address"}}

  returns a new slice of structs, each element of which is a structure with only
  two fields, 'Name' and 'Address'.

func GenerateUsageUndecorated 

func GenerateUsageUndecorated(i interface{}) string

GenerateUsageUndecorated returns a formatted string identifying the elements of the type of object i that can be accessed from inside a template. Unexported struct values and channels are not output as they cannot be usefully accessed inside a template.

Example 
i := struct {
	X       int
	Y       string
	hidden  float64
	Invalid chan int
}{}
help := GenerateUsageUndecorated(i)
fmt.Println(help)

Output:

struct {
	X int
	Y string
}

func OptAllFilters 

func OptAllFilters(c *Config)

OptAllFilters is a convenience function that enables the following functions; 'filter', 'filterContains', 'filterHasPrefix', 'filterHasSuffix', 'filterFolded', and 'filterRegexp'

func OptAllFns 

func OptAllFns(c *Config)

OptAllFns enables all template extension functions provided by this package

func OptCols 

func OptCols(c *Config)

OptCols indicates that the 'cols' function should be enabled. 'cols' can be used to extract certain columns from a table consisting of a slice or array of structs. It returns a new slice of structs which contain only the fields requested by the caller. For example, given a slice of structs 

{{cols . "Name" "Address"}}

returns a new slice of structs, each element of which is a structure with only two fields, 'Name' and 'Address'.

Example 
data := []struct{ FirstName, MiddleName, Surname string }{
	{"Marcus", "Tullius", "Cicero"},
	{"Gaius", "Julius", "Caesar"},
	{"Marcus", "Licinius", "Crassus"},
}

// Output the first and last names of people in a nicely formatted table
script := `{{tablex (cols . "FirstName" "Surname") 12 8 0}}`
var b bytes.Buffer
if err := OutputToTemplate(&b, "names", script, data, nil); err != nil {
	panic(err)
}

// Normally you would pass os.Stdout directly into OutputToTemplate.  Here
// we're outputting the result of the running the script to a buffer.  We need
// to do this so we can remove the whitespace at the end of each line of the
// table.  The test fails with the newline present as go tests implementation
// of output: for examples, trims spaces.

scanner := bufio.NewScanner(&b)
for scanner.Scan() {
	fmt.Println(strings.TrimSpace(scanner.Text()))
}

Output:

FirstName   Surname
Marcus      Cicero
Gaius       Caesar
Marcus      Crassus

func OptDescribe 

func OptDescribe(c *Config)

OptDescribe indicates that the 'describe' function should be enabled. 'describe' takes a single argument and outputs a description of the type of that argument. It can be useful if the type of the object operated on by a template program is not described in the help of the tool that executes the template. 

{{describe . }}

outputs a description of the type of '.'.

Example 
data := []struct{ FirstName, MiddleName, Surname string }{}

// Describe the type of data
script := `{{describe .}}`
if err := OutputToTemplate(os.Stdout, "names", script, data, nil); err != nil {
	panic(err)
}

Output:

[]struct {
	FirstName  string
	MiddleName string
	Surname    string
}

func OptFilter 

func OptFilter(c *Config)

OptFilter indicates that the filter function should be enabled. 'filter' operates on an slice or array of structures. It allows the caller to filter the input array based on the value of a single field. The function returns a slice containing only the objects that satisfy the filter, e.g. 

{{len (filter . "Protected" "true")}}

outputs the number of elements whose "Protected" field is equal to "true".

Example 
data := []struct{ FirstName, MiddleName, Surname string }{
	{"Marcus", "Tullius", "Cicero"},
	{"Gaius", "Julius", "Caesar"},
	{"Marcus", "Licinius", "Crassus"},
}

// Print the surname of all people whose first name is Marcus
script := `{{range (filter . "FirstName" "Marcus")}}{{println .Surname}}{{end}}`
if err := OutputToTemplate(os.Stdout, "names", script, data, nil); err != nil {
	panic(err)
}

Output:

Cicero
Crassus

func OptFilterContains 

func OptFilterContains(c *Config)

OptFilterContains indicates that the filterContains function should be enabled. 'filterContains' operates along the same lines as filter, but returns substring matches 

{{len(filterContains . "Name" "Cloud"}})

outputs the number of elements whose "Name" field contains the word "Cloud".

Example 
data := []struct{ FirstName, MiddleName, Surname string }{
	{"Marcus", "Tullius", "Cicero"},
	{"Gaius", "Julius", "Caesar"},
	{"Marcus", "Licinius", "Crassus"},
}

// Count the number of people whose middle name contains a 'ul'
script := `{{len (filterContains . "MiddleName" "ul")}}`
if err := OutputToTemplate(os.Stdout, "names", script, data, nil); err != nil {
	panic(err)
}

Output:

2

func OptFilterFolded 

func OptFilterFolded(c *Config)

OptFilterFolded indicates that the filterFolded function should be enabled. 'filterFolded' is similar to filter, but returns matches based on equality under Unicode case-folding.

Example 
data := []struct{ FirstName, MiddleName, Surname string }{
	{"Marcus", "Tullius", "Cicero"},
	{"Gaius", "Julius", "Caesar"},
	{"Marcus", "Licinius", "Crassus"},
}

// Output the first and surnames of all people whose first name is marcus
script := `{{range (filterFolded . "FirstName" "marcus")}}{{println .FirstName .Surname}}{{end}}`
if err := OutputToTemplate(os.Stdout, "names", script, data, nil); err != nil {
	panic(err)
}

Output:

Marcus Cicero
Marcus Crassus

func OptFilterHasPrefix 

func OptFilterHasPrefix(c *Config)

OptFilterHasPrefix indicates that the filterHasPrefix function should be enabled. 'filterHasPrefix' is similar to filter, but returns prefix matches.

Example 
data := []struct{ FirstName, MiddleName, Surname string }{
	{"Marcus", "Tullius", "Cicero"},
	{"Gaius", "Julius", "Caesar"},
	{"Marcus", "Licinius", "Crassus"},
}

// Print all the surnames that start with 'Ci'
script := `{{select (filterHasPrefix . "Surname" "Ci") "Surname"}}`
if err := OutputToTemplate(os.Stdout, "names", script, data, nil); err != nil {
	panic(err)
}

Output:

Cicero

func OptFilterHasSuffix 

func OptFilterHasSuffix(c *Config)

OptFilterHasSuffix indicates that the filterHasSuffix function should be enabled. 'filterHasSuffix' is similar to filter, but returns suffix matches.

Example 
data := []struct{ FirstName, MiddleName, Surname string }{
	{"Marcus", "Tullius", "Cicero"},
	{"Gaius", "Julius", "Caesar"},
	{"Marcus", "Licinius", "Crassus"},
}

// Print all the surnames that end with 'us'
script := `{{select (filterHasSuffix . "Surname" "us") "Surname"}}`
if err := OutputToTemplate(os.Stdout, "names", script, data, nil); err != nil {
	panic(err)
}

Output:

Crassus

func OptFilterRegexp 

func OptFilterRegexp(c *Config)

OptFilterRegexp indicates that the filterRegexp function should be enabled. 'filterRegexp' is similar to filter, but returns matches based on regular expression matching 

{{len (filterRegexp . "Name" "^Docker[ a-zA-z]*latest$"}})

outputs the number of elements whose "Name" field have 'Docker' as a prefix and 'latest' as a suffix in their name.

Example 
data := []struct{ FirstName, MiddleName, Surname string }{
	{"Marcus", "Tullius", "Cicero"},
	{"Gaius", "Julius", "Caesar"},
	{"Marcus", "Licinius", "Crassus"},
}

// Output the first and last names of all people whose middle name ends in 'ius' and whose
// second letter is 'u'
script := `{{range (filterRegexp . "MiddleName" "^.u.*ius$")}}{{println .FirstName .Surname}}{{end}}`
if err := OutputToTemplate(os.Stdout, "names", script, data, nil); err != nil {
	panic(err)
}

Output:

Marcus Cicero
Gaius Caesar

func OptHead 

func OptHead(c *Config)

OptHead indicates that the 'head' function should be enabled. 'head' operates on a slice or an array, returning the first n elements of that array as a new slice. If n is not provided, a slice containing the first element of the input slice is returned. For example, 

{{ head .}}

returns a single element slice containing the first element of '.' and 

{{ head . 3}}

returns a slice containing the first three elements of '.'. If '.' contains only 2 elements the slice returned by 

{{ head . 3}}

would be identical to the input slice.

Example 
data := []struct{ FirstName, MiddleName, Surname string }{
	{"Marcus", "Tullius", "Cicero"},
	{"Gaius", "Julius", "Caesar"},
	{"Marcus", "Licinius", "Crassus"},
}

// Print the surname of the first person in the database
script := `{{range (head .)}}{{println .Surname}}{{end}}`
if err := OutputToTemplate(os.Stdout, "names", script, data, nil); err != nil {
	panic(err)
}

Output:

Cicero

func OptRows 

func OptRows(c *Config)

OptRows indicates that the 'rows' function should be enabled. 'rows' is used to extract a set of given rows from a slice or an array. It takes at least two parameters. The first is the slice on which to operate. All subsequent parameters must be integers that correspond to a row in the input slice. Indicies that refer to non-existent rows are ignored. For example: 

{{rows . 1 2}}

extracts the 2nd and 3rd rows from the slice represented by '.'.

Example 
data := []struct{ FirstName, MiddleName, Surname string }{
	{"Marcus", "Tullius", "Cicero"},
	{"Gaius", "Julius", "Caesar"},
	{"Marcus", "Licinius", "Crassus"},
}

// Print the surname of the first and third people in the database
script := `{{range (rows . 0 2)}}{{println .Surname}}{{end}}`
if err := OutputToTemplate(os.Stdout, "names", script, data, nil); err != nil {
	panic(err)
}

Output:

Cicero
Crassus

func OptSelect 

func OptSelect(c *Config)

OptSelect indicates that the 'select' function should be enabled. 'select' operates on a slice of structs. It outputs the value of a specified field for each struct on a new line , e.g., 

{{select . "Name"}}

prints the 'Name' field of each structure in the slice.

func OptSort 

func OptSort(c *Config)

OptSort indicates that the 'sort' function should be enabled. 'sort' sorts a slice or an array of structs. It takes three parameters. The first is the slice; the second is the name of the structure field by which to 'sort'; the third provides the direction of the 'sort'. The third parameter is optional. If provided, it must be either "asc" or "dsc". If omitted the elements of the slice are sorted in ascending order. The type of the second field can be a number or a string. When presented with another type, 'sort' will try to sort the elements by the string representation of the chosen field. The following example sorts a slice in ascending order by the Name field. 

{{sort . "Name"}}
Example 
data := []struct{ FirstName, MiddleName, Surname string }{
	{"Marcus", "Tullius", "Cicero"},
	{"Gaius", "Julius", "Caesar"},
	{"Marcus", "Licinius", "Crassus"},
}

// Output the names of people sorted by their Surnames
script := `{{tablex (sort . "Surname") 12 8 0}}`
var b bytes.Buffer
if err := OutputToTemplate(&b, "names", script, data, nil); err != nil {
	panic(err)
}

// Normally you would pass os.Stdout directly into OutputToTemplate.  Here
// we're outputting the result of the running the script to a buffer.  We need
// to do this so we can remove the whitespace at the end of each line of the
// table.  The test fails with the newline present as go tests implementation
// of output: for examples, trims spaces.

scanner := bufio.NewScanner(&b)
for scanner.Scan() {
	fmt.Println(strings.TrimSpace(scanner.Text()))
}

Output:

FirstName   MiddleName  Surname
Gaius       Julius      Caesar
Marcus      Tullius     Cicero
Marcus      Licinius    Crassus

func OptTable 

func OptTable(c *Config)

OptTable indicates that the 'table' function should be enabled. 'table' outputs a table given an array or a slice of structs. The table headings are taken from the names of the structs fields. Hidden fields and fields of type channel are ignored. The tabwidth and minimum column width are hardcoded to 8. An example of table's usage is 

{{table .}}

func OptTableX 

func OptTableX(c *Config)

OptTableX indicates that the 'tablex' function should be enabled. 'tablex' is similar to table but it allows the caller more control over the table's appearance. Users can control the names of the headings and also set the tab and column width. 'tablex' takes 4 or more parameters. The first parameter is the slice of structs to output, the second is the minimum column width, the third the tab width and the fourth is the padding. The fift and subsequent parameters are the names of the column headings. The column headings are optional and the field names of the structure will be used if they are absent. Example of its usage are: 

{{tablex . 12 8 1 "Column 1" "Column 2"}}
{{tablex . 8 8 1}}
Example 
data := []struct{ FirstName, MiddleName, Surname string }{
	{"Marcus", "Tullius", "Cicero"},
	{"Gaius", "Julius", "Caesar"},
	{"Marcus", "Licinius", "Crassus"},
}

// Output the names of people in a nicely formatted table
script := `{{tablex . 12 8 0}}`
var b bytes.Buffer
if err := OutputToTemplate(&b, "names", script, data, nil); err != nil {
	panic(err)
}

// Normally you would pass os.Stdout directly into OutputToTemplate.  Here
// we're outputting the result of the running the script to a buffer.  We need
// to do this so we can remove the whitespace at the end of each line of the
// table.  The test fails with the newline present as go tests implementation
// of output: for examples, trims spaces.

scanner := bufio.NewScanner(&b)
for scanner.Scan() {
	fmt.Println(strings.TrimSpace(scanner.Text()))
}

Output:

FirstName   MiddleName  Surname
Marcus      Tullius     Cicero
Gaius       Julius      Caesar
Marcus      Licinius    Crassus

func OptTail 

func OptTail(c *Config)

OptTail indicates that the 'tail' function should be enabled. 'tail' is similar to head except that it returns a slice containing the last n elements of the input slice. For example, 

{{tail . 2}}

returns a new slice containing the last two elements of '.'.

Example 
data := []struct{ FirstName, MiddleName, Surname string }{
	{"Marcus", "Tullius", "Cicero"},
	{"Gaius", "Julius", "Caesar"},
	{"Marcus", "Licinius", "Crassus"},
}

// Print the surname of the first person in the database
script := `{{range (tail .)}}{{println .Surname}}{{end}}`
if err := OutputToTemplate(os.Stdout, "names", script, data, nil); err != nil {
	panic(err)
}

Output:

Crassus

func OptToJSON 

func OptToJSON(c *Config)

OptToJSON indicates that the 'tosjon' function should be enabled. 'tojson' outputs the target object in json format, e.g., {{tojson .}}

Example 
data := []struct {
	Name       string
	AgeAtDeath int
	Battles    []string
}{
	{"Caesar", 55, []string{"Battle of Alesia", "Battle of Dyrrhachium", "Battle of the Nile"}},
	{"Alexander", 32, []string{"Battle of Issus", "Battle of Gaugamela", "Battle of the Hydaspes"}},
}

script := `{{tojson .}}`
if err := OutputToTemplate(os.Stdout, "names", script, data, nil); err != nil {
	panic(err)
}

Output:

[
	{
		"Name": "Caesar",
		"AgeAtDeath": 55,
		"Battles": [
			"Battle of Alesia",
			"Battle of Dyrrhachium",
			"Battle of the Nile"
		]
	},
	{
		"Name": "Alexander",
		"AgeAtDeath": 32,
		"Battles": [
			"Battle of Issus",
			"Battle of Gaugamela",
			"Battle of the Hydaspes"
		]
	}
]

func OutputToTemplate 

func OutputToTemplate(w io.Writer, name, tmplSrc string, obj interface{}, cfg *Config) (err error)

OutputToTemplate executes the template, whose source is contained within the tmplSrc parameter, on the object obj. The name of the template is given by the name parameter. The results of the execution are output to w. The functions enabled in the cfg parameter will be made available to the template source code specified in tmplSrc. If cfg is nil, all the additional functions provided by templateutils will be enabled.

Example 
data := []struct{ FirstName, MiddleName, Surname string }{
	{"Marcus", "Tullius", "Cicero"},
	{"Gaius", "Julius", "Caesar"},
	{"Marcus", "Licinius", "Crassus"},
}

// print the surname of the person whose middlename is lexographically smallest.
script := `{{select (head (sort . "MiddleName")) "Surname"}}`
if err := OutputToTemplate(os.Stdout, "names", script, data, nil); err != nil {
	panic(err)
}

Output:

Caesar

func TemplateFunctionHelp 

func TemplateFunctionHelp(c *Config) string

TemplateFunctionHelp generates formatted documentation that describes the additional functions that the Config object c adds to Go's templating language. If c is nil, documentation is generated for all functions provided by templateutils.

Types

type Config 

type Config struct {
	// contains filtered or unexported fields
}

Config is used to specify which functions should be added Go's template language. It's not necessary to create a Config option. Nil can be passed to all templateutils functions that take a Context object indicating the default behaviour is desired. However, if you wish to restrict the number of functions added to Go's template language or you want to add your own functions, you'll need to create a Config object. This can be done using the NewConfig function.

All members of Config are private.

func NewConfig 

func NewConfig(options ...func(*Config)) *Config

NewConfig creates a new Config object that can be passed to other functions in this package. The Config option keeps track of which new functions are added to Go's template libray. If this function is called without arguments, none of the functions defined in this package are enabled in the resulting Config object. To control which functions get added specify some options, e.g., 

ctx := templateutils.NewConfig(templateutils.OptHead, templateutils.OptTail)

creates a new Config object that enables the 'head' and 'tail' functions only.

To add all the functions, use the OptAllFNs options, e.g., 

ctx := templateutils.NewConfig(templateutils.OptAllFNs)

func (*Config) AddCustomFn 

func (c *Config) AddCustomFn(fn interface{}, name, helpText string) error

AddCustomFn adds a custom function to the template language understood by templateutils.CreateTemplate and templateutils.OutputToTemplate. The function implementation is provided by fn, its name, i.e., the name used to invoke the function in a program, is provided by name and the help for the function is provided by helpText. An error will be returned if a function with the same name is already associated with this Config object.

Example 
nums := []int{1, 2, 3, 4, 5, 6, 7, 8, 9, 10}
cfg := NewConfig(OptAllFns)
cfg.AddCustomFn(func(n []int) int {
	sum := 0
	for _, num := range n {
		sum += num
	}
	return sum
}, "sum", "- sum \"Returns\" the sum of a slice of integers")

// Print the sum of a slice of numbers
script := `{{println (sum .)}}`
if err := OutputToTemplate(os.Stdout, "sums", script, nums, cfg); err != nil {
	panic(err)
}

Output:

55

func (*Config) Len 

func (c *Config) Len() int

func (*Config) Less 

func (c *Config) Less(i, j int) bool

func (*Config) Swap 

func (c *Config) Swap(i, j int)

Notes

Bugs

  • Map to slice

Source Files

View all Source files

Directories

Path Synopsis
examples
tmplex

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.