<metaname="description"content="JSON for Humans! HJSON is the configuration file format used by ENiGMA½ for System Configuration, Menus, etc. HJSON is is JSON for humans!"/>
<metaproperty="og:description"content="JSON for Humans! HJSON is the configuration file format used by ENiGMA½ for System Configuration, Menus, etc. HJSON is is JSON for humans!"/>
{"datePublished":"2023-10-15T23:34:51+00:00","description":"JSON for Humans! HJSON is the configuration file format used by ENiGMA½ for System Configuration, Menus, etc. HJSON is is JSON for humans!","mainEntityOfPage":{"@type":"WebPage","@id":"/enigma-bbs/configuration/hjson.html"},"publisher":{"@type":"Organization","logo":{"@type":"ImageObject","url":"/enigma-bbs/assets/images/enigma-logo.png"}},"url":"/enigma-bbs/configuration/hjson.html","@type":"BlogPosting","headline":"HJSON Config Files","dateModified":"2023-10-15T23:34:51+00:00","@context":"https://schema.org"}</script>
<p>HJSON is the configuration file format used by ENiGMA½ for <ahref="/enigma-bbs/configuration/config-hjson.html">System Configuration</a>, <ahref="/enigma-bbs/configuration/menu-hjson.html">Menus</a>, etc. <ahref="https://hjson.org/">HJSON</a> is is <ahref="https://json.org/">JSON</a> for humans!</p>
<p>For those completely unfamiliar, JSON stands for JavaScript Object Notation. But don’t let that scare you! JSON is simply a text file format with a bit of structure ― kind of like a fancier INI file. HJSON on the other hand as mentioned previously, is JSON for humans. That is, it has the following features and more:</p>
<ul>
<li>More resilient to syntax errors such as missing a comma</li>
<li>Strings generally do not need to be quoted. Multi-line strings are also supported!</li>
<li>Comments are supported (JSON doesn’t allow this!): <codeclass="language-plaintext highlighter-rouge">#</code>, <codeclass="language-plaintext highlighter-rouge">//</code> and <codeclass="language-plaintext highlighter-rouge">/* ... */</code> style comments are allowed.</li>
<li>Keys never need to be quoted</li>
<li>…much more! See <ahref="https://hjson.org/">the official HJSON website</a>.</li>
</ul>
<h2id="terminology">Terminology</h2>
<p>Through the documentation, some terms regarding HJSON and configuration files will be used:</p>
<ul>
<li>
<codeclass="language-plaintext highlighter-rouge">config.hjson</code>: Refers to <codeclass="language-plaintext highlighter-rouge">/path/to/enigma-bbs/config/config.hjson</code>. See <ahref="/enigma-bbs/configuration/config-hjson.html">System Configuration</a>.</li>
<li>
<codeclass="language-plaintext highlighter-rouge">menu.hjson</code>: Refers to <codeclass="language-plaintext highlighter-rouge">/path/to/enigma-bbs/config/<yourBBSName>-menu.hjson</code>. See <ahref="/enigma-bbs/configuration/menu-hjson.html">Menus</a>.</li>
<li>Configuration <em>key</em>: Elements in HJSON are name-value pairs where the name is the <em>key</em>. For example, provided <codeclass="language-plaintext highlighter-rouge">foo: bar</code>, <codeclass="language-plaintext highlighter-rouge">foo</code> is the key.</li>
<li>Configuration <em>section</em> or <em>block</em> (also commonly called an “Object” in code): This is referring to a section in a HJSON file that starts with a <em>key</em>. For example:
<pre><codeclass="language-hjson">someSection: {
foo: bar
}
</code></pre>
<p>Note that <codeclass="language-plaintext highlighter-rouge">someSection</code> is the configuration <em>section</em> (or <em>block</em>) and <codeclass="language-plaintext highlighter-rouge">foo: bar</code> is within it.</p>
</li>
</ul>
<h2id="editing-hjson">Editing HJSON</h2>
<p>HJSON is a text file format, and ENiGMA½ configuration files <strong>should always be saved as UTF-8</strong>.</p>
<p>It is <strong>highly</strong> recommended to use a text editor that has HJSON support. A few (but not all!) examples include:</p>
<ul>
<li>
<ahref="https://www.sublimetext.com/">Sublime Text</a> via the <codeclass="language-plaintext highlighter-rouge">sublime-hjson</code> package.</li>
<li>
<ahref="https://code.visualstudio.com/">Visual Studio Code</a> via the <codeclass="language-plaintext highlighter-rouge">vscode-hjson</code> plugin.</li>
<li>
<ahref="https://notepad-plus-plus.org">Notepad++</a> via the <codeclass="language-plaintext highlighter-rouge">npp-hjson</code> plugin.</li>
</ul>
<p>See https://hjson.org/users.html for more more editors & plugins.</p>
<h3id="hot-reload-aka-live-editing">Hot-Reload A.K.A. Live Editing</h3>
<p>ENiGMA½’s configuration, menu, and theme files can edited while your BBS is running. When a file is saved, it is hot-reloaded into the running system. If users are currently connected and you change a menu for example, the next reload of that menu will show the changes.</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"> See also <ahref="/enigma-bbs/configuration/config-files.html">Configuration Files</a></p>
<p>Configuration keys are <strong>case sensitive</strong>. That means if a configuration key is <codeclass="language-plaintext highlighter-rouge">boardName</code> for example, <codeclass="language-plaintext highlighter-rouge">boardname</code>, or <codeclass="language-plaintext highlighter-rouge">BOARDNAME</code><strong>will not work</strong>.</p>
<h3id="escaping">Escaping</h3>
<p>Some values need escaped. This is especially important to remember on Windows machines where file paths contain backslashes (<codeclass="language-plaintext highlighter-rouge">\</code>). To specify a path to <codeclass="language-plaintext highlighter-rouge">C:\foo\bar\baz.exe</code> for example, an entry may look like this in your configuration file:</p>
<pre><codeclass="language-hjson">something: {
path: "C:\\foo\\bar\\baz.exe" // note the extra \'s!
<p>Remember that standard JSON is fully compatible with HJSON. If you are more comfortable with JSON (or have an editor that works with JSON that you prefer) simply convert your config file(s) to JSON and use that instead!</p>
<p>HJSON can be converted to JSON with the <codeclass="language-plaintext highlighter-rouge">hjson</code> CLI:</p>
<p>You can always convert back to HJSON by omitting <codeclass="language-plaintext highlighter-rouge">-j</code> in the command above.</p>
<h3id="oputil">oputil</h3>
<p>You can easily dump out your current configuration in a pretty-printed style using oputil: <codeclass="language-plaintext highlighter-rouge">./oputil.js config cat</code></p>
</div>
<divclass="PageNavigation">
<aclass="btn"style="float:left;margin-right: 20px;"href="/enigma-bbs/configuration/config-hjson.html">« System Configuration</a>
