io

Take data, make documents!

Overview

io is supposed to be a small and useful tool for reworking data from JSON, YAML, or CSV sources into any text or HTML format.

The templates used for the transformation feature all the elements of Go Templates plus a set of useful functions.

Gems are the exec functions from tplfuncs that, combined with the line based matchers and filters, can be used to create dynamic auto-generated documents.

Also, this tool can be used to set up simple and easy includes for the system Hostsfile at /etc/hosts, see here.

How to Use

Usage:
  io [flags]
  io [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  version     

Flags:
      --allow-exec               allow execution of commands during templating phase, implies --allow-io and --allow-network
      --allow-io                 allow reading and writing files during templating phase
      --allow-network            allow network communication during templating phase
  -h, --help                     help for io
  -i, --input string             input filename including extension optionally with path, or inline JSON if first char is { (default "{}")
  -o, --output string            output filename including extension optionally with path
  -w, --overwrite stringArray    overwrite input data by path (for YML and JSON inputs only)
  -t, --template string          template filename including extension optionally with path
      --template-inline string   inline template content

Use "io [command] --help" for more information about a command.

Example

With input data from test/input/simple.yml

creator:
  name: John Doe
  age: 54

and the template test/template/creator.html

<h1>
    Creator:
    {{ .creator.name }}
    ( {{- .creator.age }}yo)
</h1>

you can use io to get this result:

> io -i test/input/simple.yml -t test/template/creator.html
<h1>
    Creator:
    John Doe
    (54yo)
</h1>

If you want to overwrite values from the input data uses --overwrite like this:

> io --input test/input/simple.yml --template test/template/creator.html --overwrite creator.age=62 --overwrite creator.name=Walther
<h1>
    Creator:
    Walther
    (62yo)
</h1>

Auto-generate /etc/hosts

Create a file named /etc/hosts.gen:

##########################################################################
#   update /etc/hosts ONLY like this after editing                       #
#   /etc/hosts.d/ and /etc/hosts.gen:                                    #
#   sudo io --allow-exec --template /etc/hosts.gen --output /etc/hosts   #
##########################################################################

# Host addresses
127.0.0.1  localhost
::1        localhost ip6-localhost ip6-loopback
ff02::1    ip6-allnodes
ff02::2    ip6-allrouters

{{- /* Loop files */}}
{{- range glob "/etc/hosts.d/*" }}
    {{- newline 2 -}}
    # START {{ . }}
    {{- newline -}}
    {{ include . | trim }}
    {{- newline -}}
    # END {{ . }}
{{- end }}

Now you can place an arbitrary number of files in /etc/hosts.d (create the directory like this: mkdir /etc/hosts.d). These files will be inlined as described in the template. The generated comment makes sure that you always know which source file to edit if there is anything to be changed.

To update the hostsfile the system will use at /etc/hosts, run this:

sudo io --allow-exec --template /etc/hosts.gen --output /etc/hosts

Other content around the range operation is left untouched, but can still only be edited in /etc/hosts.gen otherwise it would be overwritten.

Template Functions

All functions defined in jojomi/tplfuncs (the exec* variants are only avaiable when --allow-exec is given when calling io due to security implications)

A quick introduction to Golang Templates can be found at Hugo.

How to Install

io Command

go install github.com/jojomi/io/cmd/io@latest

github.com/jojomi/io Library

go get -u github.com/jojomi/io

Who uses it?

io does itself, see build.sh which generates this very document from docu/README.tpl.md. It shows how to use exec functions as well, but does not take dynamic input data.