tplr

package module

v0.9.2 Latest Latest Go to latest Published: Apr 6, 2021 License: MIT Imports: 9 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/mantidtech/tplr

Links

Open Source Insights

README ¶

License

`tplr` (templater)

A tool to create files rendered from go templates and json

Usage: tplr [-o <output file>] [-d <data file>] [-t <template file>] [inline template]
Usage: tplr [-h|-v]

Where:
  -o <output file>   is a file to write to (default: stdout)
  -d <data file>     is a json file containing the templated variables (default: stdin)
  -f <template file> is a file using the go templating notation.
     If this is not specified, the template is taken from the remaining program args

Information:
  -h Prints this messge
  -v Prints the program version number and exits

The templating markup language used is defined by the go text/template package

Install

Using go

go get -u github.com/mantidtech/tplr/cmd/tplr

Examples

    echo '{"to":"World"}' | tplr 'Hello {{.to}}!'
    # displays:
    Hello World!

    cat << EOF > sample.tpl
    <html>
        <head>
            <title>{{ .title }}</title>
        <head>
        <body>
            <ul>
            {{- range .items -}}
                {{- include "listItem" . | indent 3 -}}
            {{- end }}
            </ul>
        </body>
    </html>
    
    {{- define "listItem" }}
    <li>
        {{.}}
    </li>
    {{- end -}}
    EOF

    cat << EOF > sample.json
    {
        "title": "My List Of Doom",
        "items": [
            "Acquire lair",
            "Acquire henchmen",
            "Acquire doomsday weapon"
        ]
    }
    EOF

    tplr -d sample.json -t sample.tpl -o sample.html

    cat sample.html
    # displays:
    <html>
        <head>
            <title>My List Of Doom</title>
        <head>
        <body>
            <ul>
                <li>
                    Acquire lair
                </li>
                <li>
                    Acquire henchmen
                </li>
                <li>
                    Acquire doomsday weapon
                </li>
            </ul>
        </body>
    </html>

NOTE: tplr uses the text/template and not the html/template package.
This means there's no special translation of html elements, and therefore output isn't protected against code injection -- so trust your data source if you intend to use tplr in any sort of public facing html generation process.

Template Functions

In addition to the standard template functions, tplr introduces:

Composition Actions

`{{ include "name" pipeline }}`

Works like template, but allows usage within pipelines eg

{{- include "foo" . | indent 6 -}}

Logical Operators

`{{ isZero pipeline }}`

Returns true if the pipeline is empty (ie the zero value of its type) OR if it's a pointer and the dereferenced value is zero, OR if the type of the pipeline has a length (eg array, slice, map, string), and the length is zero

`{{ whenEmpty pipeline1 pipeline0 }}`

If pipeline0 is empty (ie the zero value of its type), returns pipeline1 otherwise pipeline0

eg

{{ .SomeValue | whenEmpty "something else" }}

Formatting

`{{ toColumns N S }}`

ToColumns formats the given text to not take more than N characters per line, splitting on the space before the word that would take the line over

Note: Embedded newlines have no special treatment, so text containing them could look wonky. Either strip them first, or break the input into multiple strings and process individually

eg

{{ toColumns 5 "a b c d e f g" }}

produces

a b c
d e f
g

`{{ bracketWith S pipeline }}`

Surrounds the pipeline with bracket pairs taken from S

S must be an even-length string. The first half is used as the opening bracket, and the second as closing.

eg

{{ bracketWith "<>" "html" }}

produces

<html>

`{{ bracket pipeline }}`

Surrounds the pipeline with ( & )

Equivalent to {{ bracketWith "()" pipeline }}.

`{{ prefix X N S }}`

Prefixes all lines in the string S with N times the prefix string X

`{{ suffix X N S }}`

Appends all lines in the string S with N times the suffix string X

`{{ indent N S }}`

Indents all lines in the string S with N tabs.

Equivalent to {{ prefix "\t" N S }}.

eg

{{- indent 2 "Hello\n\tWorld" -}}

produces

        Hello
            World

`{{ joinWith S ARG_1..ARG_N }}`

Concatenates the args into string joined by the string S

`{{ join ARG_1..ARG_N }}`

Concatenates the args into a single string

Equivalent to {{ joinWith "" ARG }}.

`{{ splitOn S ARG }}`

Splits the arg into a list of strings on occurrences of the string S

`{{ padLeft N ARG }}`

Returns the arg with a width of at least N characters, adding spaces at the front to pad out the string

`{{ padRight N ARG }}`

Returns the arg with a width of at least N characters, adding spaces at the end to pad out the string

`{{ uppercaseFirst ARG }}`

Returns the arg with the first character capitalised. There is no effect to other characters.

`{{ toLower ARG }}`

Returns the arg with the all characters converted to lowercase.

`{{ toUpper ARG }}`

Returns the arg with the all characters converted to uppercase.

`{{ rep N ARG }}`

Returns the arg printed N number of times.

`{{ space [N] }}`

Returns a space character.
If N is supplied, returns the given number of spaces. Equivalent to {{ rep N " " }}.

`{{ tab [N] }}`

Returns a tab character.
If N is supplied, return the given number of tabs. Equivalent to {{ rep N "\t" }}.

`{{ nl [N] }}`

Returns a newline character.
If N is supplied, return the given number of newlines. Equivalent to {{ rep N "\n" }}.

`{{ typeName ARG }}`

Returns the name of the Go type for the underlying variable of the argument

Encoding

`{{ toJSON ARG }}`

Converts the given arg to a JSON string

`{{ formatJSON S ARG }}`

Pretty-prints the pipeline. Returns an error if the arg isn't valid JSON. Each element in the JSON object or array begins on a new line, indented by one or more copies of S according to the nesting depth of the object.

`{{ toYAML ARG }}`

Converts the given arg to a YAML string

`{{ toBase64 ARG }}`

Converts the given arg to base64 encoding

`{{ fromBase64 ARG }}`

Decode the given base64 ARG

Lists

These methods work when the value of the pipeline is an array or slice (and return an error otherwise)

`{{ list ITEM_1.ITEM_N }}`

Creates a new list with the given set of items

`{{ first LIST }}`

Returns the first item in the list

`{{ last LIST }}`

Returns the last item of a list

`{{ rest LIST }}` / `{{ pop LIST }}`

Returns a list of everything except for the first item (aliased as pop)

`{{ push LIST ITEM }}`

Adds an item to the end of a list, returning the new list

`{{ unshift LIST ITEM }}`

Adds an item to the beginning of a list, returning the new list

`{{ slice I J LIST }}`

Returns a slice of the list, ie all items between indexes I (inclusive) and J (exclusive)

`{{ contains LIST ITEM }}`

Returns true if the item are present in the list

`{{ filter LIST ITEM }}`

Returns a list with all instances of all item removed from it

Functions as a Library

You can also import the template functions to use with your own templating code.

go get github.com/mantidtech/tplr/functions

and use:

import github.com/mantidtech/tplr/functions

A convenience function, functions.All(t *template.Template), is provided to return all the functions as a template.FuncMap

docs are at https://pkg.go.dev/github.com/mantidtech/tplr/functions

To Do

Process multiple templates and/or datasets at once
Greatly expand functions, including for
- Time
- Anything else people might find useful
Less basic error messages/presentation

Documentation ¶

Index ¶

func FileExists(filename string) bool
func GenerateFromTemplate(w io.Writer, t *template.Template, vars map[string]interface{}) error
func GetFileReader(filename string) (io.Reader, error)
func GetFileWriter(filename string, force bool) (io.Writer, error)
func Load(r io.Reader) (*template.Template, error)
func ReadDataFile(filename string) (map[string]interface{}, error)
func ReadStringsAsFile(s ...string) (res io.Reader, err error)
func Version() string

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

func FileExists ¶

func FileExists(filename string) bool

FileExists checks that a file exists and is a regular file

func GenerateFromTemplate ¶

func GenerateFromTemplate(w io.Writer, t *template.Template, vars map[string]interface{}) error

GenerateFromTemplate generates text from the template and data supplied and writes it to the given Writer

func GetFileReader ¶

func GetFileReader(filename string) (io.Reader, error)

GetFileReader returns a Reader for the given filename, or '-' for stdin

func GetFileWriter ¶

func GetFileWriter(filename string, force bool) (io.Writer, error)

GetFileWriter returns a Writer for the given filename, or '-' for stdout

func Load ¶

func Load(r io.Reader) (*template.Template, error)

Load a template from the supplied Reader and create a new Template object

func ReadDataFile ¶ added in v0.8.2

func ReadDataFile(filename string) (map[string]interface{}, error)

ReadDataFile reads the given file into a map of interfaces

func ReadStringsAsFile ¶ added in v0.8.2

func ReadStringsAsFile(s ...string) (res io.Reader, err error)

ReadStringsAsFile returns the given set of strings as an io.Reader

func Version ¶

func Version() string

Version returns the version number of this app

Types ¶

This section is empty.

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
cmd
tplr tplr is a tool to create files rendered from go templates and json data install with: go install github.com/mantidtech/tplr/cmd/tplr@latest see github.com/mantidtech/tplr for documentation	tplr is a tool to create files rendered from go templates and json data install with: go install github.com/mantidtech/tplr/cmd/tplr@latest see github.com/mantidtech/tplr for documentation
functions

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

README ¶

tplr (templater)

Install

Examples

Template Functions

Composition Actions

{{ include "name" pipeline }}

Logical Operators

{{ isZero pipeline }}

{{ whenEmpty pipeline1 pipeline0 }}

Formatting

{{ toColumns N S }}

{{ bracketWith S pipeline }}

{{ bracket pipeline }}

{{ prefix X N S }}

{{ suffix X N S }}

{{ indent N S }}

{{ joinWith S ARG_1..ARG_N }}

{{ join ARG_1..ARG_N }}

{{ splitOn S ARG }}

{{ padLeft N ARG }}

{{ padRight N ARG }}

{{ uppercaseFirst ARG }}

{{ toLower ARG }}

{{ toUpper ARG }}

{{ rep N ARG }}

{{ space [N] }}

{{ tab [N] }}

{{ nl [N] }}

{{ typeName ARG }}

Encoding

{{ toJSON ARG }}

{{ formatJSON S ARG }}

{{ toYAML ARG }}

{{ toBase64 ARG }}

{{ fromBase64 ARG }}

Lists

{{ list ITEM_1.ITEM_N }}

{{ first LIST }}

{{ last LIST }}

{{ rest LIST }} / {{ pop LIST }}

{{ push LIST ITEM }}

{{ unshift LIST ITEM }}

{{ slice I J LIST }}

{{ contains LIST ITEM }}

{{ filter LIST ITEM }}

Functions as a Library

To Do

Documentation ¶

Index ¶

Constants ¶

Variables ¶

Functions ¶

func FileExists ¶

func GenerateFromTemplate ¶

func GetFileReader ¶

func GetFileWriter ¶

func Load ¶

func ReadDataFile ¶ added in v0.8.2

func ReadStringsAsFile ¶ added in v0.8.2

func Version ¶

Types ¶

Source Files ¶

Directories ¶

`tplr` (templater)

`{{ include "name" pipeline }}`

`{{ isZero pipeline }}`

`{{ whenEmpty pipeline1 pipeline0 }}`

`{{ toColumns N S }}`

`{{ bracketWith S pipeline }}`

`{{ bracket pipeline }}`

`{{ prefix X N S }}`

`{{ suffix X N S }}`

`{{ indent N S }}`

`{{ joinWith S ARG_1..ARG_N }}`

`{{ join ARG_1..ARG_N }}`

`{{ splitOn S ARG }}`

`{{ padLeft N ARG }}`

`{{ padRight N ARG }}`

`{{ uppercaseFirst ARG }}`

`{{ toLower ARG }}`

`{{ toUpper ARG }}`

`{{ rep N ARG }}`

`{{ space [N] }}`

`{{ tab [N] }}`

`{{ nl [N] }}`

`{{ typeName ARG }}`

`{{ toJSON ARG }}`

`{{ formatJSON S ARG }}`

`{{ toYAML ARG }}`

`{{ toBase64 ARG }}`

`{{ fromBase64 ARG }}`

`{{ list ITEM_1.ITEM_N }}`

`{{ first LIST }}`

`{{ last LIST }}`

`{{ rest LIST }}` / `{{ pop LIST }}`

`{{ push LIST ITEM }}`

`{{ unshift LIST ITEM }}`

`{{ slice I J LIST }}`

`{{ contains LIST ITEM }}`

`{{ filter LIST ITEM }}`