esh man page

esh — simple template system based on shell

Synopsis

esh [-d] [-o output] [-s shell] [--] file [variable ...]

esh <-h | -V>

Description

esh (embedded shell) is a templating engine for evaluating shell commands embedded in arbitrary templates. It’s like ERB (Embedded RuBy) for shell, intended to be used for templating configuration files.

esh converts template file, or stdin if file is “-”, into a sequence of shell commands. Commands between <% and %> tags are passed as-is, everything else is escaped and prefixed with printf command. These commands are eventually evaluated using shell (unless -d is specified).

Options

-d

Don’t evaluate template, just dump a shell script.

-o file

Output file or “-” for STDOUT. Defaults to “-”.

-s shell

Command name or path of the shell to use for template evaluation. It must not contain spaces. Defaults to “/bin/sh”.

-h

Show help message and exit.

-V

Print version and exit.

Environment

esh may be configured using the following environment variables:

ESH_AWK

Command name of path of the awk program to use. It must not contain spaces. Defaults to “awk”.

ESH_SHELL

The same as -s shell.

Exit Status

esh exits with the exit status of shell or awk.

Template Syntax

ESH has two tags for shell code, a tag for comments, and a way to escape tag delimiters.

<% commands %>

Executes the commands and replaces this tag with its output on stdout.

<%= values %>

Executes printf '%s ' with the values as arguments and replaces this tag with the output (without trailing white space). values are not quoted or escaped, so all shell substitutions are applied.

<%# comment %>

Removed from the final output.

-%>

May be used instead of %>. It trims the following line break if used at the end of line, otherwise has no trimming effect.

<%%

A literal <% when used outside of the above tags.

%%>

A literal %> when used inside of the above tags.

Opening and closing tag may not be at the same line.

Text outside a tag becomes literal text, but it is subject to any tagged shell code surrounding it. For example, text surrounded by a tagged if statement only appears in the output if the condition is true.

Examples

nginx.conf.esh

http {
    access_log <%= $logs_dir/access.log %> main;

    resolver <%= $(sed -En 's/^nameserver ([^#]+)/\1/p' /etc/resolv.conf) %>;

    <% if nginx -V 2>&amp;1 | grep -q lua-nginx-module; then -%>
    lua_package_path '<%= $(pkg-config --variable=INSTALL_LMOD lua) %>/?.lua';
    <% fi -%>

    <%# The rest of the config is omitted %>
}

To generate the resulting configuration file run:

esh -o nginx.conf nginx.conf.esh logs_dir=/var/log/nginx

Authors

esh’s author is Jakub Jirutka.

Reporting Bugs

Report bugs to the project’s issue tracker at https://github.com/jirutka/esh/issues.

See Also

sh(1)

Info

2017-11-18