Infuse - the global template parser

Infuse is a CLI tool and a go library that can be imported in other Go projects. Its main purpose is to handle template parsing for different template formats in a generic way.

Getting started

If interested in downloading the code and using it as a dependency in another Go project, simply do

go get github.com/jucardi/infuse

The command line tool

The command line tool is a convenient terminal command that allows to parse a template, passing the a JSON or YAML representation to be used as values within the template.

How to install it

There are a few options to install the CLI tool.

Download the release file

For UNIX (Mac and Linux)

1. Download the binary

   sudo curl -L https://github.com/jucardi/infuse/releases/download/v1.0.13/infuse-$(uname -s)-$(uname -m) -o /usr/local/bin/infuse

2. Apply executable permissions

   sudo chmod +x /usr/local/bin/infuse

3. Test the installation

   infuse --help

Install using Go

go get -u github.com/jucardi/infuse/cmd/infuse

Installing the CLI from the source code directory

Using make run

make install

This make recipe will compile the binary for your local architecture and place it under $GOPATH/bin via go install

Building the CLI binaries from code

Using make run

make compile-all

This make recipe will build the binaries for Linux, Mac and Windows under the build directory.

Uninstallation

If installed using the first method (downloading the release)

sudo rm /usr/local/bin/infuse

If installed using Go

rm $GOPATH/bin/infuse

Usage

infuse [flags] [template file|directory]

Flags

All the flags are optional, including the data input. Infuse supports using a template to parse declared environment variables, so they can also be used as data to be parsed in.

Data Input flags

The input flags indicate how the data to be parsed into templates is read.

• -f or --file: A JSON or YAML file to use as an input for the data to be parsed. This flag can be used multiple times and all files will be merged into a single data object.
• -u or --url: A URL for HTTP GET to a JSON or YAML payload. Useful to parse data from config servers.
• -s or --string: A JSON or YAML string representation.

Target flags

The target flags indicate where the parsed template will be output

• -o or --output: Indicate an output file. If not specified, the resulting template will be printed to StdOut. If the input path is a directory, output must also be a directory.

Template definitions flags

The template definition flags allow auxiliary template files to be loaded so they can be used in the primary template.

• -d or --definition: File path of another template to be imported and used by the primary template to be parsed. This flag can be used multiple times to load multiple template definitions
• -p or --pattern: Search pattern to load multiple template definitions, for example -p ./templates/*

Utility flags

• -l or --listHelpers: Prints all registered helpers grouped by category.
• --ignoreErrors: When input path is a directory, continue parsing other files even if one fails.

Examples

infuse -f service-config.yml -o docker-compose.yml -d global/mongo.tmpl -d global/redis.tmpl docker-compose.tmpl

infuse -u http://config-server.local/something/service-config.json -o docker-compose.yml -p global/* docker-compose.tmpl

infuse -o something.config something.tmpl

infuse -l

When are template definitions useful?

When defining certain global templates that can be reused in other primary templates.

For example, a docker-compose.yml that defines a service stack where one of the containers is a database definition. The database definition can be a separate template and be imported in the docker-compose.yml file when generating the service stack definition.

Given the following files:

service-config.yml - The configuration for a specific service

name: some-service
version: RC-1.0.0
port: 1234
develop_mode: true
resources:
  replicas: 3
  cpus: '0.5'
  memory: 512M
db:
  port: 4321

service.tmpl - Primary template that defines a service stack. Generic and can be used for multiple microservices, provided the right configuration

version: "3.3"
services:
  api:
    image: registry.local/services/{{ .name }}:{{ .version }}
    ports:
      - '{{ .port }}:{{ .port }}'
    healthcheck:
      test: curl -f http://localhost:{{ .port }}{{ .health_uri | default "/health" }} || echo 1
      interval: 5s
      timeout: 20s
      retries: 3
    networks:
      - {{ .name }}-net
    deploy:
      replicas: {{ .resources.replicas | default 2 }}
      placement:
        constraints:
          - node.role == worker
          - node.labels.workertype == services
      resources:
        limits:
          cpus: {{ .resources.cpus }}
          memory: {{ .resources.memory }}
      restart_policy:
        condition: any
{{ if .db }}
{{ template "mongo.tmpl" . }}
{{ end }}

networks:
  {{ .name }}-net:

mongo.tmpl - Template used as definition to be imported. It defines a generic mongo database config which can be reused in other templates

  mongo:
    image: mongo:latest
{{ if .develop_mode }}
    ports:
      - {{ .db.port }}:27017
{{ end }}
    volumes:
      - {{ .name }}-mongodb:/data/db
    networks:
      - {{ .name }}-net
    deploy:
      replicas: 1
      placement:
        constraints:
          - node.role == worker
          - node.labels.workertype == dbe
      restart_policy:
        condition: any

volumes:
  {{ .name }}-mongodb:
    driver: local-persist
    driver_opts:
      mountpoint: /mnt/db-data/{{ .name }}-mongodb

Template engines

The project contains two template engine implementations:

• Go templates (go) - default engine used by the CLI.
• Handlebars (handlebars) - available in the library package.

The template library

Helper discovery

You can always print the currently registered helpers from the CLI:

infuse -l

Go template built-ins

When using Go templates, all standard Go template built-ins are available (for example and, or, not, eq, ne, lt, le, gt, ge, len, index, print, printf, println, urlquery).

Registered extension helpers

The following extension helpers are registered by the code.

Generic/common helpers

• string
• format
• uppercase
• upper
• lowercase
• lower
• title
• stringsReplace
• stringsJoin
• stringsSplit
• stringsTrim
• stringsTrimLeft
• stringsTrimRight
• stringsTrimSpace
• stringsContains
• stringsCompare
• stringsSub
• startsWith
• endsWith
• br
• yaml
• json
• rem
• env
• stringArray
• mathAdd
• mathMult
• indent
• stringxCamelToDash
• stringxCamelToSnake
• stringxDashToCamel
• stringxSnakeToCamel
• stringxPascalToDash
• stringxPascalToSnake
• stringxDashToPascal
• stringxSnakeToPascal

Go-template specific helpers

• default
• map
• dict (alias of map)
• include
• includeAsString
• set
• append
• iterate
• loadJson
• mapSet
• mapGet
• mapContains
• mapConvert
• invoke
• parse
• parseXpath
• in

Selected helper examples

• default: Returns a default value when the evaluated value is empty.

  {{ .some_value | default "something" }}

  If .some_value is empty or not present, the expression resolves to something.

• map / dict: Creates an inline map object (key, value, key, value, ...).

  {{- $someObj := map "X" "chuck" "Y" "norris" "Z" 1234 "something" .something -}}

  This builds a dictionary that can be passed to other templates or helpers. The number of arguments after map/dict must be even (key, value pairs).

  Equivalent JSON shape:

  {
    "X": "chuck",
    "Y": "norris",
    "Z": 1234,
    "something": "<value from .something>"
  }

• template: Renders a loaded template definition.

  {{ template "template_name" $dataObj }}

  The template name matches the file name of the loaded definition when using CLI -d or -p. Use . to pass the root data object, or pass a nested object like .sub_key.

• env: Reads an environment value into the template.

  {{ env "SOME_ENVIRONMENT_VARIABLE" }}

  If SOME_ENVIRONMENT_VARIABLE=something, the rendered result is something.

Advanced helper examples

• mapGet: Reads a value by xpath-like key path, with optional fallback value.

  {{ mapGet . ".service.image.tag" "latest" }}

  Returns the value under .service.image.tag if present; otherwise returns latest.

• mapSet: Sets a value by xpath-like key path in an existing map.

  {{- mapSet . ".service.image.tag" "v2.1.0" true -}}

  The optional fourth argument indicates whether missing parent objects should be created.

• parse: Parses a string as a template using the provided data object.

  {{ parse . "service={{ .name }} version={{ .version }}" }}

  Useful when template fragments are dynamic or loaded from config values.

• invoke: Renders a named template dynamically (name can come from a variable).

  {{- $tplName := "mongo.tmpl" -}}
  {{ invoke $tplName . }}

  Similar to template, but invoke accepts a computed template name instead of only a string literal.

• indent: Indents all lines in a string with the provided indentation string.

  {{ indent (yaml .resources) "    " }}

  Useful when embedding generated YAML/JSON blocks inside already-indented output.