Skip to content

Latest commit

 

History

History
264 lines (184 loc) · 4.65 KB

README.md

File metadata and controls

264 lines (184 loc) · 4.65 KB
Raw

Gucci

A simple CLI templating tool written in golang.

GitHub version

Installation

If you have go installed:

$ go get github.com/noqcks/gucci

Or you can just download the binary and move it into your PATH:

VERSION=1.6.13
wget -q "https://github.com/noqcks/gucci/releases/download/v${VERSION}/gucci-v${VERSION}-darwin-amd64"
chmod +x gucci-v${VERSION}-darwin-amd64
mv gucci-v${VERSION}-darwin-amd64 /usr/local/bin/gucci

Use

Locating Templates

gucci can locate a template in multiple ways.

File

Pass the template file path as the first argument:

$ gucci template.tpl > template.out

Stdin

Supply the template through standard input:

$ gucci
Start typing stuff {{ print "here" }}
^d
Start typing stuff here

Via piping:

$ echo '{{ html "<escape-me/>" }}' | gucci

Supplying Variable Inputs

gucci can receive variables for use in templates in the following ways (in order of lowest to highest precedence):

  • A JSON or YAML file
  • Environment variables
  • Variable command options

Variables File

Given an example variables file:

# vars.yaml
hosts:
  - name: bastion
  - name: app

Pass it into gucci with -f or --vars-file:

$ gucci -f vars.yaml template.tpl

Environment Variables

Here, MY_HOST is available to the template:

$ export MY_HOST=localhost
$ gucci template.tpl

Variable Options

Pass variable options into gucci with -s or --set-var, which can be repeated:

$ gucci -s foo.bar=baz template.tpl

Variable option keys are split on the . character, and nested such that the above example would equate to the following yaml variable input:

foo:
  bar: baz

Templating

Options

Existing golang templating options can be used for templating.

If no option is specified, the missingkey=error option will be used (execution stops immediately with an error if a key used in the template is not present in the supplied values).

One might want a different value for missingkey when using conditionals and having keys that won't be used at all.

For instance, given the following template, containing two docker-compose services service1 and service2:

# template.tpl
version: "3.8"

services:
{{- if .service1 }}
  service1:
    image: {{ .service1.image }}
    restart: "always"
    ports: {{ toYaml .service1.ports | nindent 6}}
{{- end }}
{{- if .service2 }}
  service2:
    image: {{ .service2.image }}
    restart: "unless-stopped"
    ports: {{ toYaml .service2.ports | nindent 6}}
{{- end }}

And imagine a scenario where whe only need service2. By using the following values file:

# values.yaml
service2:
  image: "myservice:latest"
  ports:
    - "80"
    - "443"

And using a different missingkey=error, we can actually get the desired result without having to define the values for service1:

$ gucci -o missingkey=zero -f values.yaml  template.tpl
version: "3.8"

services:
  service2:
    image: myservice:latest
    restart: "unless-stopped"
    ports:
      - "80"
      - "443"

GoLang Functions

All of the existing golang templating functions are available for use.

Sprig Functions

gucci ships with the sprig templating functions library offering a wide variety of template helpers.

Built In Functions

Furthermore, this tool also includes custom functions:

  • shell: For arbitrary shell commands

    {{ shell "echo hello world" }}

    and

    # guest: world
{{ shell "echo hello " .guest }}

    Both produce:

    hello world

  • toYaml: Print items in YAML format

    {{ $myList := list "a" "b" "c" }}
{{ toYaml $myList }}

    Produces:

    - a
- b
- c

Example

NOTE: gucci reads and makes available all environment variables.

For example a var $LOCALHOST = 127.0.0.1

gucci template.tpl > template.conf

# template.tpl
{{ .LOCALHOST }}

gucci template.tpl > template.conf -->

# template.conf
127.0.0.1

simple enough!

For an iteration example, you have $BACKENDS=server1.com,server2.com

# template.tpl
{{ range split .BACKENDS "," }}
server {{ . }}
{{ end }}

gucci template.tpl > template.conf -->

# template.conf
server server1.com
server server2.com

Testing

Setup:

go get github.com/noqcks/gucci
go get github.com/onsi/ginkgo/ginkgo
go get github.com/onsi/gomega

Run tests:

ginkgo ./...