esh(1) - f39

1ESH(1)                                                                  ESH(1)
2
3
4

NAME

6       esh - simple template system based on shell
7

SYNOPSIS

9       esh [-d] [-o output] [-s shell] [--] file [variable ...]
10
11       esh <-h | -V>
12

DESCRIPTION

14       esh (embedded shell) is a templating engine for evaluating shell
15       commands embedded in arbitrary templates. It’s like ERB (Embedded RuBy)
16       for shell, intended to be used for templating configuration files.
17       Unlike ERB it provides support for including one ESH template into
18       another (since version 0.2.0).
19
20       esh converts template file, or stdin if file is “-”, into a sequence of
21       shell commands. Commands between <% and %> tags are passed as-is,
22       everything else is escaped and prefixed with printf command. These
23       commands are eventually evaluated using shell (unless -d is specified).
24

OPTIONS

26       -d
27           Don’t evaluate template, just dump a shell script.
28
29       -o file
30           Output file or “-” for STDOUT. Defaults to “-”.
31
32       -s shell
33           Command name or path of the shell to use for template evaluation.
34           It must not contain spaces. Defaults to “/bin/sh”.
35
36       -h
37           Show help message and exit.
38
39       -V
40           Print version and exit.
41

ENVIRONMENT

43       esh may be configured using the following environment variables:
44
45       ESH_AWK
46           Command name of path of the awk program to use. It must not contain
47           spaces. Defaults to “awk”.
48
49       ESH_MAX_DEPTH
50           Maximum include depth. Defaults to 3.
51
52       ESH_SHELL
53           The same as -s shell.
54
55       The following extra environment variables are available inside the
56       template and for the processes spawned by esh:
57
58       ESH
59           Path of the esh interpreter.
60

EXIT STATUS

62       esh exits with the exit status of shell or awk unless some error has
63       encountered before converting the template.
64
65       •   0  - Clean exit, no error has encountered.
66
67       •   1  - Generic error.
68
69       •   10 - Invalid usage.
70
71       •   11 - ESH syntax error.
72
73       •   12 - Include error: file not found.
74
75       •   13 - Include error: exceeded max include depth (ESH_MAX_DEPTH).
76

TEMPLATE SYNTAX

78       ESH has two tags for shell code, a tag for include, comments, and a way
79       to escape tag delimiters.
80
81       <% commands %>
82           Executes the commands and replaces this tag with its output on
83           stdout.
84
85       <%= values %>
86           Executes printf '%s ' with the values as arguments and replaces
87           this tag with the output (without trailing white space). values are
88           not quoted or escaped, so all shell substitutions are applied.
89
90       <%+ filename %>
91           Reads and converts ESH template from the filename and puts it in
92           place of this tag. Includes are processed recursively, but the
93           depth is limited by ESH_MAX_DEPTH.
94
95           If the filename is relative, it’s resolved against the directory of
96           the template file in which this tag resides. If the template is
97           read from stdin, the first level includes are resolved against the
98           current working directory. Please note that includes are processed
99           during the conversion, not the evaluation phase, so the filename
100           cannot be an expression or a variable!
101
102           Unlike the others, this tag must be closed on the same line,
103           otherwise it’s a syntax error.
104
105       <%# comment %>
106           Removed from the final output.
107
108       -%>
109           May be used instead of %>. It trims the following line break if
110           used at the end of line, otherwise has no trimming effect.
111
112       <%%
113           A literal <% when used outside of the above tags.
114
115       %%>
116           A literal %> when used inside of the above tags.
117
118       Opening and closing tag may not be at the same line.
119
120       Text outside a tag becomes literal text, but it is subject to any
121       tagged shell code surrounding it. For example, text surrounded by a
122       tagged if statement only appears in the output if the condition is
123       true.
124

EXAMPLES

126       nginx.conf.esh
127
128           http {
129               access_log <%= $logs_dir/access.log %> main;
130
131               resolver <%= $(sed -En 's/^nameserver ([^#]+)/\1/p' /etc/resolv.conf) %>;
132
133               <% if nginx -V 2>&1 | grep -q lua-nginx-module; then -%>
134               lua_package_path '<%= $(pkg-config --variable=INSTALL_LMOD lua) %>/?.lua';
135               <% fi -%>
136
137               <%+ ./http-common.esh %>
138
139               <%# The rest of the config is omitted %>
140           }
141
142       To generate the resulting configuration file run:
143
144           esh -o nginx.conf nginx.conf.esh logs_dir=/var/log/nginx
145

AUTHORS

147       esh's author is Jakub Jirutka.
148

REPORTING BUGS

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