template.sh

Process template from files or stdin and print the rendered text to stdout.

Usage

template.sh 0.3.0
Render templates and print result to stdout. Expressions within {{{ and }}} delimiters will be evaluated as shell script and substituted by their stdout in the rendered output. Context variables can be printed directly as {{{$VAR_NAME}}} or {{{'$VAR_NAME'}}} to escape the result for inclusion in single-quoted shell strings
Usage: template.sh [-C PATH] [-s FILE]... [-e NAME=VALUE]... [--] [- | FILE...]
Options:
 -C PATH Directory to operate in
 -e, --env NAME=VALUE Set variable NAME=VALUE in render context
 -s, --source FILE Source FILE to import its functions/variables in render context
 --help Print this help text and exit
Environment variables:
 TEMPLATE_LOG_LEVEL Log verbosity between 0-5 where 0 is silent (default 3), also recognizes levels by name, and supports a comma separated list of options: [0|none] | [error|warn|info|debug|trace],[color|no-color]
 NO_COLOR=1 Same as TEMPLATE_LOG_LEVEL=no-color (for conformance with the NO_COLOR standard)
Examples:
 template.sh -s ./program.context.sh program.template.sh >program.sh
 template.sh -e VERSION=1.0 -e TAG=latest program.template.sh >program.sh

Example template file

# With the apostrophes, {{{'$VERSION'}}} will be escaped and can be safely included in single-quoted shell strings
VERSION_TEXT='version: {{{'$VERSION'}}}'
# Any command can be executed, the expression will be substituted by the command's standard output
GIT_VERSION='{{{' git describe --tags --long --abbrev=40 '}}}'
# Both Parameter Expansion and Arithmetic Expansion have short forms, you don't need to printf the expansion to stdout
ANSWER={{{$((363636 / 13 / 666))}}}
# Complex Parameter Expansions are supported - anything that can go in a ${var} style expansion, like default values and substring expansions
{{{${VARIABLE:-"Default value"}}}}
# Another template file can be rendered and embedded anywhere in the result
{{{ render ./functions.template.sh }}}
# A "#" symbol preceding the expression delimiters will be removed from the result, allowing templates to be valid shell script as the delimiters will be commented out, for better integration with tools such as shellcheck and IDEs
#{{{
cat ./some/file
#}}}
# Also for better tool support, double-quotes as the immediate first and last characters within an expression are removed before the expression is evaluated, to allow template expressions to represent valid code within double-quoted strings
quoted="Some text {{{" printf "[wrapped]" "}}} around expression"
# Conditional rendering delimiters (triple curly brackets + question mark) can be used to print the delimited lines only if the condition command succeeds
#{{{? [ -n "$DEBUG" ]
	: This line will only be printed if DEBUG is not null
#?}}}

Functions available in render context

• abort, log_error, log_warn, log_info, log_debug, log_trace, log_is_level: Logging functions (they print to stderr) (they will print logs according to the value of the TEMPLATE_LOG_LEVEL environment variable)
• cat [-] [file...]: Simple POSIX-compatible cat utility in pure shell script
• echo [args...]: Portable echo that takes no options for consistent behavior across platforms
• render [-] [file...]: Render templates expanding all expressions recursively, print result to stdout. Accepts input from stdin and/or arguments, same UI as the cat utility

Extra functions

Used internally by template.sh, but exposed publicly because they can be useful.

• assign_variable NAME=VALUE: Use indirection to dynamically assign a variable from argument NAME=VALUE

Dependencies

template.sh only needs a POSIX-compatible shell, there are no external dependencies, not even Unix core utilities.

Contributing

Development of template.sh depends on shellcheck and shfmt. Every change must pass lint and formatting validation with ./make lint. As an option, formatting can be automatically applied with ./make format. Optionally, there's a development container image with all the tools required for development pre-installed, it can easily be used with contr:

# Build the development image
./make dev-image
# Enter the development container
contr -7 nice_things
# Lint, build and run tests
./make
# Print list of available commands
./make help

Similar projects

• preproc – Part of rpkg (unmaintained), works very similarly to template.sh, so much so that the option flags in template.sh were copied directly from its man page, and we include their test in our test suite.

License

This is free and unencumbered software released into the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.

See UNLICENSE file or http://unlicense.org/ for details.