Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jimmysawczuk/tmpl
Lightweight Go template executor
https://github.com/jimmysawczuk/tmpl
go templates tool
Last synced: 15 days ago
JSON representation
Lightweight Go template executor
- Host: GitHub
- URL: https://github.com/jimmysawczuk/tmpl
- Owner: jimmysawczuk
- License: mit
- Created: 2018-01-27T03:03:24.000Z (almost 7 years ago)
- Default Branch: main
- Last Pushed: 2022-12-24T02:46:55.000Z (about 2 years ago)
- Last Synced: 2025-01-04T03:00:21.226Z (20 days ago)
- Topics: go, templates, tool
- Language: Go
- Homepage:
- Size: 1.42 MB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# tmpl
[](https://goreportcard.com/report/github.com/jimmysawczuk/tmpl)
**tmpl** is a small command-line utility to execute Go templates (defined in [`text/template`](https://golang.org/pkg/text/template) and [`html/template`](https://golang.org/pkg/html/template)) on files.
## Features
By default, tmpl processes configuration from a file named `tmpl.config.json` in the working directory. You can override this file path with the `-f` flag.
Here's a sample configuration file:
```jsonc
[
{
"in": "index.tmpl",
"out": "out/index.html",
"format": "html", // Can be "html", "json", or "".
"options": {
// Whether or not to minify the output (default: false; has no effect
// when the format is "")
"minify": true,
// Environment variables to pass in for use in the template. You can
// also set environment variables normally; variables set in the config
// file take precedence.
"env": {
"FOO": "BAR"
}
}
}
]
```
## Functions
In addition to the [built-in functions](https://pkg.go.dev/text/template#hdr-Functions) provided by the `text/template` package, these functions are available in every template:
- [`add`](#add)
- [`asset`](#asset)
- [`autoreload`](#autoreload)
- [`env`](#env)
- [`file`](#file)
- [`formatTime`](#formatTime)
- [`getJSON`](#getJSON)
- [`inline`](#inline)
- [`jsonify`](#jsonify)
- [`markdown`](#markdown)
- [`now`](#now)
- [`parseTime`](#parseTime)
- [`ref`](#ref)
- [`safeCSS`](#safeCSS)
- [`safeHTML`](#safeHTML)
- [`safeHTMLAttr`](#safeHTMLAttr)
- [`safeJS`](#safeJS)
- [`seq`](#seq)
- [`sub`](#sub)
- [`svg`](#svg)
- [`timeIn`](#timeIn)
### `add`
> add returns the sum of the two arguments.
```
{{ add 2 2 }}
```
returns
```
4
```
### `asset`
> asset returns the path provided. In the future, asset may gain the ability to clean or validate the path.
```
{{ asset "/css/style.css" }}
```
returns
```
/css/style.css
```
### `autoreload`
> autoreload returns an HTML snippet that you can embed in your templates to automatically reload the page when a change is detected.
```
{{ autoreload }}
```
returns
```
...
```
### `env`
> env returns the environment variable defined at the provided key. Variables set in `tmpl.config.json` take precedence.
```
{{ env "NODE_ENV" }}
```
returns
```
production
```
### `file`
> file loads the file at the path provided and returns its contents. It _does not_ create a ref; updating this file's contents won't trigger an update in watch mode.
```
{{ file "some-letter.txt" }}
```
returns
```
...data...
```
### `formatTime`
> formatTime formats the provided time with the provided format. You can either specify both arguments at once or pipe a `time.Time` into this function to format it.
```
{{ now | formatTime "Jan 2, 2006 3:04 PM" }}
{{ formatTime now "Jan 2, 2006 3:04 PM" }}
```
returns
```
Nov 28, 2021 10:09 AM
Nov 28, 2021 10:09 AM
```
### `getJSON`
> getJSON loads the file at the provided path and unmarshals it into a `map[string]interface{}`. It _does not_ create a ref; updating this file's contents won't trigger an update in watch mode.
```
{{ getJSON "REVISION.json" }}
```
returns
```
map[string]interface{}{
...
}
```
### `inline`
> inline loads the file at the path provided and returns its contents. It creates a ref so that updates to the file trigger an update in watch mode.
```
{{ file "some-letter.txt" }}
```
returns
```
...data...
```
### `jsonify`
> jsonify marshals the provided input as a JSON string.
```
{{ now | jsonify }}
```
returns
```
"2021-11-28T10:09:00Z"
```
### `markdown`
> markdown reads the file at the provided path, parses its contents as Markdown and returns the HTML. It creates a ref so that updates to the file trigger an update in watch mode.
```
{{ markdown "path-to-markdown.md" }}
```
returns
```
...
...
```
### `now`
> now returns the time of the template's execution in the local timezone.
```
{{ now | jsonify }}
```
returns
```
"2021-11-28T10:09:00Z"
```
### `parseTime`
> parseTime returns a `time.Time` from the provided string in RFC3339 format.
```
{{ parseTime "2021-11-28T10:09:00Z" }}
```
returns
```
a time.Time
```
### `ref`
> ref creates a ref to the provided path so that an automatic update is triggered when the file at that path is changed. ref produces no output.
```
{{ ref "public/style.css" }}
```
returns
```
```
### `safeCSS`
### `safeHTML`
### `safeHTMLAttr`
### `safeJS`
> The `safe*` functions mark their inputs as "safe" so they're not further escaped. See the documentation for [CSS](https://pkg.go.dev/html/template#CSS), [HTML](https://pkg.go.dev/html/template#HTML), [HTMLAttr](https://pkg.go.dev/html/template#HTMLAttr), and [JS](https://pkg.go.dev/html/template#JS) in `html/template`.
### `seq`
> seq returns a slice of `n` elements. Useful for `range`.
```
{{ seq 5 }}
{{ range seq 3 }}
Hello!
{{ end }}
```
returns
```
[0, 1, 2, 3, 4]
Hello!
Hello!
Hello!
```
### `sub`
> sub returns the difference between the two arguments.
```
{{ sub 3 2 }}
```
returns
```
1
```
### `svg`
> svg reads the file at the provided path and returns its contents. It creates a ref so that updates to the file trigger an update in watch mode.
```
{{ svg "path-to-svg.svg" }}
```
returns
```
...
```
### `timeIn`
> timeIn returns the provided time in the provided timezone.
```
{{ now | timeIn "America/Los_Angeles" | jsonify }}
```
returns
```
"2021-11-28T02:09:00-0800"
```
---
## Watch mode
Watch mode (`-w`) watches all of the templates in your config for changes and rebuilds them when they're changed. Additionally, any files referenced in your templates via `ref` or similar template functions will trigger a rebuild of the template.
## Server mode
Server mode (`-s`) is the same as watch mode except it also spins up a webserver that will serve the base directory.
Additionally, this webserver has an endpoint (`/__tmpl`) which will resolve when a change is made. You can use the `autoreload` function in your template to automatically reload the page when this endpoint resolves.
## Subcommand
You can pass in a subcommand to be run by providing the `--` flag and then your command. You might want to use this if you need to run a second development process, like webpack, alongside your templates.
Here's an example:
```sh
$ tmpl -w -- webpack -w --mode=development
```
## License
[MIT](/LICENSE)