# Handlematters

Self-contained template system with Handlebars and inline shell scripts

## Introduction

Handlematters is a template system that combines Handlebars and shell scripts. It is intended to replace simple substitution tasks such as those done by envsubst.

Here is an example of a Handlematters template:

```
hello.hms

Any text before the context or template block is just a comment.
It will not be output.

--- context ---
greeting: echo hello

list: |
  for v in foo bar baz; do
    echo "* $v"
  done

--- template ---
{{greeting}}, world

{{list}}
```

Passing this file to handlematters will result in the following output:

```
$ handlematters hello.hms
hello, world

* foo
* bar
* baz
```

Let's take a closer look.

```
--- context ---
greeting: echo hello

list: |
  for v in foo bar baz; do
    echo "* $v"
  done
```

The `context` block is a YAML document. Each value of the property will be executed as a shell script and the output will be the resulting value.

```
--- template ---
{{greeting}}, world

{{list}}
```

The `template` block is a Handlebars template. `{{...}}` to output the context value. If you are not familiar with Handlebars syntax, have a look at https://handlebarsjs.com/.

Let's look at a more practical example:

```
Note: The expression in triplet braces {{{...}}} will be output without HTML escaping.

--- context ---
name: cargo metadata --format-version=1 --no-deps | jq -r .packages[0].name
author: cargo metadata --format-version=1 --no-deps | jq -r .packages[0].authors[0]

--- template ---
{{{name}}} by {{{author}}}
```

Will result in:

```
handlematters by Keita Urashima <ursm@ursm.jp>
```

Of course, this README is also generated by Handlematters. See: https://github.com/ursm/handlematters/blob/main/README.md.hms

## Usage

```
Self-contained template system with Handlebars and inline shell scripts

Usage: handlematters [FILE]

Arguments:
  [FILE]  Input file [default: stdin]

Options:
  -h, --help     Print help
  -V, --version  Print version
```