<metaname="description"content="General Information ENiGMA½ configuration files such as the system config, menus and themes are formatted in the HJSON format."/>
<metaproperty="og:description"content="General Information ENiGMA½ configuration files such as the system config, menus and themes are formatted in the HJSON format."/>
{"publisher":{"@type":"Organization","logo":{"@type":"ImageObject","url":"/enigma-bbs/assets/images/enigma-logo.png"}},"description":"General Information ENiGMA½ configuration files such as the system config, menus and themes are formatted in the HJSON format.","url":"/enigma-bbs/configuration/config-files.html","@type":"BlogPosting","headline":"Configuration Files","dateModified":"2022-04-06T02:48:32+00:00","datePublished":"2022-04-06T02:48:32+00:00","mainEntityOfPage":{"@type":"WebPage","@id":"/enigma-bbs/configuration/config-files.html"},"@context":"https://schema.org"}</script>
<p>ENiGMA½ configuration files such as the <ahref="/enigma-bbs/configuration/config-hjson.html">system config</a>, <ahref="/enigma-bbs/configuration/menu-hjson.html">menus</a> and <ahref="/enigma-bbs/art/themes.html">themes</a> are formatted in the <ahref="/enigma-bbs/configuration/hjson.html">HJSON format</a>.</p>
<h2id="hot-reload">Hot-Reload</h2>
<p>Nearly all of ENiGMA½’s configuration can be hot-reloaded. That is, a live system can have it’s configuration modified and it will be loaded in place.</p>
<p><imgclass="emoji"title=":bulb:"alt=":bulb:"src="https://github.githubassets.com/images/icons/emoji/unicode/1f4a1.png"height="20"width="20"><ahref="/enigma-bbs/troubleshooting/monitoring-logs.html">Monitoring live logs</a> is useful when making live changes. The system will complain if something is wrong!</p>
<h2id="common-directives">Common Directives</h2>
<h3id="includes">Includes</h3>
<p>Most configuration files offer an <codeclass="language-plaintext highlighter-rouge">includes</code> directive that allows users to break up large configuration files into smaller and organized parts. For example, consider a system with many menus/screens. Instead of a single <codeclass="language-plaintext highlighter-rouge">menu.hjson</code>, the SysOp may break this into <codeclass="language-plaintext highlighter-rouge">message-base.hjson</code>, <codeclass="language-plaintext highlighter-rouge">file-base.hjson</code>, etc.</p>
<p>The <codeclass="language-plaintext highlighter-rouge">includes</code> directive may be used the top-level scope of a configuration file:</p>
<p>Often times in a configuration you will find that you’re repeating yourself quite a bit. ENiGMA½ provides an <codeclass="language-plaintext highlighter-rouge">@reference</code> that can help with this in the form of <codeclass="language-plaintext highlighter-rouge">@reference:dot.path.to.section</code>.</p>
<p>Consider <codeclass="language-plaintext highlighter-rouge">actionKeys</code> in a menu. Often times you may show a screen and the user presses <codeclass="language-plaintext highlighter-rouge">Q</code> or <codeclass="language-plaintext highlighter-rouge">ESC</code> to fall back to the previous. Instead of repeating this in many menus, a generic block can be referenced:</p>
<pre><codeclass="language-hjson">{
// note that 'recycle' here is arbitrary;
// only 'menus' and 'prompts' is reserved at this level.
recycle: {
prevMenu: [
{
keys: [ "escape" ]
action: @systemMethod:prevMenu
}
]
}
menus: {
someMenu: {
form: {
0: {
actionKeys: @reference:recycle.prevMenu
}
}
}
}
}
</code></pre>
<p><imgclass="emoji"title=":information_source:"alt=":information_source:"src="https://github.githubassets.com/images/icons/emoji/unicode/2139.png"height="20"width="20"> An unresolved <codeclass="language-plaintext highlighter-rouge">@reference</code> will be left intact.</p>
<p>Especially in a container environment such as <ahref="/enigma-bbs/installation/docker.html">Docker</a>, environment variable access in configuration files can become very handy. ENiGMA½ provides a flexible way to access variables using the <codeclass="language-plaintext highlighter-rouge">@environment</code> directive. The most basic form of <codeclass="language-plaintext highlighter-rouge">@environment:VAR_NAME</code> produces a string value. Additionally a <codeclass="language-plaintext highlighter-rouge">:type</code> suffix can be supplied to coerece the value to a particular type. Variables pointing to a comma separated list can be turned to arrays using an additional <codeclass="language-plaintext highlighter-rouge">:array</code> suffix.</p>
<td>An array of <ahref="https://momentjs.com/">moment</a> objects representing 2020-01-05 and 2016-05-16T01:15:37</td>
</tr>
</tbody>
</table>
<p><imgclass="emoji"title=":bulb:"alt=":bulb:"src="https://github.githubassets.com/images/icons/emoji/unicode/1f4a1.png"height="20"width="20"><codeclass="language-plaintext highlighter-rouge">bool</code> may be used as an alias to <codeclass="language-plaintext highlighter-rouge">boolean</code>.</p>
<p><imgclass="emoji"title=":bulb:"alt=":bulb:"src="https://github.githubassets.com/images/icons/emoji/unicode/1f4a1.png"height="20"width="20"><codeclass="language-plaintext highlighter-rouge">timestamp</code> values can be in any form that <ahref="https://momentjs.com/docs/#/parsing/">moment can parse</a>.</p>
<p><imgclass="emoji"title=":information_source:"alt=":information_source:"src="https://github.githubassets.com/images/icons/emoji/unicode/2139.png"height="20"width="20"> An unresolved or invalid <codeclass="language-plaintext highlighter-rouge">@environment</code> will be left intact.</p>
<p>Consider the following fragment:</p>
<pre><codeclass="language-hjson">{
foo: {
bar: @environment:BAR_VAR:number
}
}
</code></pre>
<p>If the environment has <codeclass="language-plaintext highlighter-rouge">BAR_VAR=1337</code>, this would produce:</p>
