`tplr` (templater)

A tool to create files rendered from go templates and json

Usage: tplr [-f] [-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)
  -t <template file> is a file using the go templating notation.
     If this is not specified, the template is taken from the remaining program args

Options:
  -f If the destination file already exits, overwrite it.  (default is to do nothing)

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 install github.com/mantidtech/tplr/cmd/tplr@latest

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 several collections of functions

strings - Operations on strings (and pipelines convertable to strings)
list - Operations to operate on lists (arrays) of values
logic - Logical operations
math - mathematical operators
time - time and date methods
encoding and decoding - For marshalling and unmarshalling data structures
templates - Meta-functions for template processing
console - Operations specific to processing templates to a terminal

String Operations

{{ toColumns NUMBER TEXT }}

ToColumns formats the given TEXT to not take more than NUMBER 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 BRACKETPAIR PIPELINE }}

Surrounds the pipeline with bracket pairs taken from the string BRACKETPAIR

BRACKETPAIR 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 PREFIX COUNT STRING }}

Prefixes all lines in the string STRING with COUNT times the prefix string PREFIX.

eg:

{{ prefix "> " 2 "Foo" }}

produces:

> > Foo

{{ suffix SUFFIX COUNT STRING }}

Appends all lines in the string STRING with COUNT times the suffix string SUFFIX.

{{ indent COUNT STRING }}

Indents all lines in the string STRING with COUNT spaces.

Equivalent to {{ prefix " " COUNT STRING }}.

eg

{{- indent 2 "Hello\nWorld" -}}

produces

  Hello
  World

{{ tabIndent COUNT STRING }}

Indents all lines in the string STRING with COUNT tabs.

Equivalent to {{ prefix "\t" COUNT STRING }}.

eg

{{- indent 2 "Hello\nWorld" -}}

produces

        Hello
        World

{{ splitOn GLUE CONTENT }}

Splits CONTENT into a list of strings on occurrences of the string GLUE.

{{ padLeft COUNT PIPELINE }}

Returns PIPELINE with a width of at least COUNT characters, adding spaces at the front to pad out the string.

{{ padRight COUNT PIPELINE }}

Returns PIPELINE with a width of at least COUNT 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 STRING }}

Returns STRING with the all characters converted to lowercase.

{{ toUpper STRING }}

Returns STRING with the all characters converted to uppercase.

{{ rep COUNT ARG }}

Returns the ARG printed COUNT number of times.

{{ space [COUNT] }} / {{ sp [COUNT] }}

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

{{ tab [COUNT] }}

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

{{ nl [COUNT] }}

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

{{ typeName PIPELINE }}

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

{{ camelCase STRING }}

Convert the given STRING to camelCase.

eg:

{{- camelCase "foo bar" -}}

produces:

fooBar

{{ dotCase STRING }}

Convert the given STRING to dotCase.

eg:

{{- dotCase "foo bar" -}}

produces:

foo.bar

{{ kebabCase STRING }}

Convert the given STRING to kebabCase.

eg:

{{- kebabCase "foo bar" -}}

produces:

foo-bar

{{ pascalCase STRING }}

Convert the given STRING to pascalCase.

eg:

{{- pascalCase "foo bar" -}}

produces:

FooBar

{{ screamingSnakeCase STRING }}

Convert the given STRING to screamingSnakeCase.

eg:

{{- screamingSnakeCase "foo bar" -}}

produces:

FOO_BAR

{{ snakeCase STRING }}

Convert the given STRING to snakeCase.

eg:

{{- snakeCase "foo bar" -}}

produces:

foo_bar

{{ titleCase STRING }}

Convert the given STRING to titleCase.

eg:

{{- titleCase "foo html" -}}

produces:

Foo Html

{{ titleCaseWithAbbr ABBREV STRING }}

Convert the given STRING to titleCase, additionally using the set of words in ABBREV to convert words in STRING to fully uppercase.

eg:

{{- titleCase (list "html") "foo html" -}}

produces:

Foo HTML

{{ toWords STRING }}

Convert the given STRING to toWords.

eg:

{{- toWords "foo_bar_baz" -}}

produces:

foo bar baz

{{ q STRING }}

Quotes the given STRING with single quotes.

eg:

{{- q "foo" -}}

produces:

'foo'

{{ qq STRING }}

Quotes the given STRING with double quotes.

eg:

{{- qq "foo" -}}

produces:

"foo"

{{ qb STRING }}

Quotes the given STRING with back-quotes.

eg:

{{- qb "foo" -}}

produces:

`foo`

{{ trim STRING }}

Trims whitespace from the start and end of STRING.

eg:

X{{- trim "   foo   " -}}X

produces:

XfooX

{{ typeKind PIPELINE }}

Returns the 'kind' of the PIPELINE.

eg:

{{ typeKind 6 }}
{{ typeKind "foo" }}
{{ list "A" "B" "C" | typeKind }}

produces:

int
string
slice

{{ unindent COUNT STRING }}

Removes up to COUNT spaces from the start of every line in STRING.

{{ now [FORMAT] }}

Returns the current time as a string in the given FORMAT or time.RFC3339 if none is specified.

Time formats are specified using standard go formatting as defined at https://pkg.go.dev/time#pkg-constants

eg:

{{ now }}
{{ now "Mon Jan _2" }}
{{ now "15:04:05 MST" }}

produces:

2021-09-16T21:41:58Z10:00
Thu Sep 16
21:41:58 AEST

List Functions

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 }} / {{ shift LIST }}

Returns the first item in the list.

{{ last LIST }} / {{ pop LIST }}

Returns the last item of a list.

{{ rest LIST }}

Returns a list of everything except for the first item.

{{ push LIST ITEM }}

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

{{ unshift LIST ITEM }}

Adds an item to the start of a list, returning the list.

{{ 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.

{{ joinWith GLUE ARG_1..ARG_N }}

Concatenates the args into string joined by the string GLUE.

{{ join ARG_1..ARG_N }}

Concatenates the args into a single string.

Equivalent to {{ joinWith "" ARG }}.

Logical Functions

{{ 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 (e.g. array, slice, map, string), and the length is zero

{{ and ARG_1...ARG_n }}

Returns ARG_n if all the arguments evaluate to non-zero or "" otherwise.

{{ or ARG_1...ARG_n }}

Returns the first argument that evaluates to non-zero (from left to right) or "" if none do.

{{ whenEmpty VALUE COND }}

Returns VALUE if COND is a zero value, otherwise it returns COND.

eg:

{{ "thing" | whenEmpty "something else" }}
{{ "" | whenEmpty "something else" }}

Produces:

thing
something else

{{ when VALUE COND }}

Returns VALUE if COND is not zero, otherwise it returns an empty string.

eg:

X{{ "thing" | when "something else" }}X
X{{ "" | when "something else" }}X

Produces:

Xsomething elseX
XX

Encoding and Decoding

{{ toBase64 ARG }}

Converts the given arg to base64 encoding

{{ fromBase64 ARG }}

Decode the given base64 ARG

{{ toJSON ARG }}

Converts the given arg to a JSON string

{{ formatJSON INDENT 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 INDENT according to the nesting depth of the object.

{{ toYAML PIPELINE }}

Converts the given PIPELINE to a YAML string

Operations with Templates

{{ include "NAME" PIPELINE }}

Works like template, but allows usage within pipelines. eg:

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

Console (Terminal) Functions

{{ terminalWidth }}

Returns the width of the terminal if available or zero otherwise.

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
- Numbers
- Anything else people might find useful
Less basic error messages/presentation

Name		Name	Last commit message	Last commit date
Latest commit History 66 Commits
.circleci		.circleci
.github/workflows		.github/workflows
cmd		cmd
examples		examples
functions		functions
testdata		testdata
vendor		vendor
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE.md		LICENSE.md
README.md		README.md
build.sh		build.sh
check.sh		check.sh
check_overrides.sh		check_overrides.sh
doc.go		doc.go
file.go		file.go
file_test.go		file_test.go
go.mod		go.mod
go.sum		go.sum
tplr.go		tplr.go
tplr_test.go		tplr_test.go
version.go		version.go
version_test.go		version_test.go

License

mantidtech/tplr

Folders and files

Latest commit

History

Repository files navigation

tplr (templater)

Install

Examples

Template Functions

String Operations

{{ toColumns NUMBER TEXT }}

{{ bracketWith BRACKETPAIR PIPELINE }}

{{ bracket PIPELINE }}

{{ prefix PREFIX COUNT STRING }}

{{ suffix SUFFIX COUNT STRING }}

{{ indent COUNT STRING }}

{{ tabIndent COUNT STRING }}

{{ splitOn GLUE CONTENT }}

{{ padLeft COUNT PIPELINE }}

{{ padRight COUNT PIPELINE }}

{{ uppercaseFirst ARG }}

{{ toLower STRING }}

{{ toUpper STRING }}

{{ rep COUNT ARG }}

{{ space [COUNT] }} / {{ sp [COUNT] }}

{{ tab [COUNT] }}

{{ nl [COUNT] }}

{{ typeName PIPELINE }}

{{ camelCase STRING }}

{{ dotCase STRING }}

{{ kebabCase STRING }}

{{ pascalCase STRING }}

{{ screamingSnakeCase STRING }}

{{ snakeCase STRING }}

{{ titleCase STRING }}

{{ titleCaseWithAbbr ABBREV STRING }}

{{ toWords STRING }}

{{ q STRING }}

{{ qq STRING }}

{{ qb STRING }}

{{ trim STRING }}

{{ typeKind PIPELINE }}

{{ unindent COUNT STRING }}

{{ now [FORMAT] }}

List Functions

{{ list ITEM_1..ITEM_N }}

{{ first LIST }} / {{ shift LIST }}

{{ last LIST }} / {{ pop LIST }}

{{ rest LIST }}

{{ push LIST ITEM }}

{{ unshift LIST ITEM }}

{{ contains LIST ITEM }}

{{ filter LIST ITEM }}

{{ joinWith GLUE ARG_1..ARG_N }}

{{ join ARG_1..ARG_N }}

Logical Functions

{{ isZero PIPELINE }}

{{ and ARG_1...ARG_n }}

{{ or ARG_1...ARG_n }}

{{ whenEmpty VALUE COND }}

{{ when VALUE COND }}

Encoding and Decoding

{{ toBase64 ARG }}

{{ fromBase64 ARG }}

{{ toJSON ARG }}

{{ formatJSON INDENT ARG }}

{{ toYAML PIPELINE }}

Operations with Templates

{{ include "NAME" PIPELINE }}

Console (Terminal) Functions

{{ terminalWidth }}

Functions as a Library

To Do

About

Topics

Resources

License

Stars

Watchers

`tplr` (templater)

`{{ toColumns NUMBER TEXT }}`

`{{ bracketWith BRACKETPAIR PIPELINE }}`

`{{ bracket PIPELINE }}`

`{{ prefix PREFIX COUNT STRING }}`

`{{ suffix SUFFIX COUNT STRING }}`

`{{ indent COUNT STRING }}`

`{{ tabIndent COUNT STRING }}`

`{{ splitOn GLUE CONTENT }}`

`{{ padLeft COUNT PIPELINE }}`

`{{ padRight COUNT PIPELINE }}`

`{{ uppercaseFirst ARG }}`

`{{ toLower STRING }}`

`{{ toUpper STRING }}`

`{{ rep COUNT ARG }}`

`{{ space [COUNT] }}` / `{{ sp [COUNT] }}`

`{{ tab [COUNT] }}`

`{{ nl [COUNT] }}`

`{{ typeName PIPELINE }}`

`{{ camelCase STRING }}`

`{{ dotCase STRING }}`

`{{ kebabCase STRING }}`

`{{ pascalCase STRING }}`

`{{ screamingSnakeCase STRING }}`

`{{ snakeCase STRING }}`

`{{ titleCase STRING }}`

`{{ titleCaseWithAbbr ABBREV STRING }}`

`{{ toWords STRING }}`

`{{ q STRING }}`

`{{ qq STRING }}`

`{{ qb STRING }}`

`{{ trim STRING }}`

`{{ typeKind PIPELINE }}`

`{{ unindent COUNT STRING }}`

`{{ now [FORMAT] }}`

`{{ list ITEM_1..ITEM_N }}`

`{{ first LIST }}` / `{{ shift LIST }}`

`{{ last LIST }}` / `{{ pop LIST }}`

`{{ rest LIST }}`

`{{ push LIST ITEM }}`

`{{ unshift LIST ITEM }}`

`{{ contains LIST ITEM }}`

`{{ filter LIST ITEM }}`

`{{ joinWith GLUE ARG_1..ARG_N }}`

`{{ join ARG_1..ARG_N }}`

`{{ isZero PIPELINE }}`

`{{ and ARG_1...ARG_n }}`

`{{ or ARG_1...ARG_n }}`

`{{ whenEmpty VALUE COND }}`

`{{ when VALUE COND }}`

`{{ toBase64 ARG }}`

`{{ fromBase64 ARG }}`

`{{ toJSON ARG }}`

`{{ formatJSON INDENT ARG }}`

`{{ toYAML PIPELINE }}`

`{{ include "NAME" PIPELINE }}`

`{{ terminalWidth }}`

Packages