README.tpl.md

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

{{ exec "io --help" }}

Example

{{ $input := "test/input/simple.yml" -}} With input data from [{{ $input }}]({{ $input }})

{{ printf "cat %s" $input | exec }}

{{ $template := "test/template/creator.html" -}} and the template [{{ $template }}]({{ $template }})

{{ printf "cat %s" $template | exec }}

you can use io to get this result:

{{ $ioCmd := printf "io -i %s -t %s" $input $template -}}

> {{ $ioCmd }}
{{ exec $ioCmd | trim }}

If you want to overwrite values from the input data uses --overwrite like this: {{ $ioCmdOverwrite := printf "io --input %s --template %s --overwrite creator.age=62 --overwrite creator.name=Walther" $input $template -}}

> {{ $ioCmdOverwrite }}
{{ exec $ioCmdOverwrite | trim }}

Auto-generate /etc/hosts

Create a file named /etc/hosts.gen:

{{ include "docu/hosts.gen" }}

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:

{{ regexpReplaceLiteral "(^\\s*#\\s*)|(\\s*#\\s*$)" "" (include "docu/hosts.gen" | match "sudo io") }}

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

{{ $base := (exec "git config --get remote.origin.url" | trim | replace "git@" "" | replace "https://" "" | replace ".git" "" | replace ":" "/" ) -}}

io Command

go install {{ $base }}/cmd/io@latest

github.com/jojomi/io Library

go get -u {{ $base }}

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.