moon
/
enigma-bbs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
enigma-bbs/configuration/hjson.html

2386 lines
22 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html lang="en-US">
<head>
<meta charset='utf-8'>
<meta http-equiv="X-UA-Compatible" content="chrome=1">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="icon" type="image/png" sizes="16x16" href="/enigma-bbs/assets/images/favicon-16x16.png">
<link rel="icon" type="image/png" sizes="32x32" href="/enigma-bbs/assets/images/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="32x32" href="/enigma-bbs/assets/images/favicon-32x32.png">
<link rel="stylesheet" href="/enigma-bbs/assets/css/style.css?v=">
<!-- Begin Jekyll SEO tag v2.7.1 -->
<title>HJSON Config Files | ENiGMA½ BBS Software</title>
<meta name="generator" content="Jekyll v4.2.1" />
<meta property="og:title" content="HJSON Config Files" />
<meta property="og:locale" content="en_US" />
<meta name="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!" />
<meta property="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!" />
<meta property="og:site_name" content="ENiGMA½ BBS Software" />
<meta property="og:type" content="article" />
<meta property="article:published_time" content="2023-08-24T03:50:04+00:00" />
<meta name="twitter:card" content="summary" />
<meta property="twitter:title" content="HJSON Config Files" />
<script type="application/ld+json">
{"description":"JSON for Humans! HJSON is the configuration file format used by ENiGMA½ for System Configuration, Menus, etc. HJSON is is JSON for humans!","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-08-24T03:50:04+00:00","datePublished":"2023-08-24T03:50:04+00:00","mainEntityOfPage":{"@type":"WebPage","@id":"/enigma-bbs/configuration/hjson.html"},"@context":"https://schema.org"}</script>
<!-- End Jekyll SEO tag -->
</head>
<body>
<div id="container">
<div class="sidebar" id="sidebar">
<hr class="mobile-divide">
<div class="container">
<a href="/enigma-bbs/"><img src="/enigma-bbs/assets/images/enigma-logo.png" class="logo" alt="Enigma logo"></a>
</div>
<ul>
<li>Installation</li>
<ul>
<li><a href="/enigma-bbs/installation/installation-methods.html">Installation Methods</a></li>
<li><a href="/enigma-bbs/installation/install-script.html">Install Script</a></li>
<li><a href="/enigma-bbs/installation/docker.html">Docker</a></li>
<li><a href="/enigma-bbs/installation/manual.html">Manual Installation</a></li>
<li>OS / Hardware Specific</li>
<ul>
<li><a href="/enigma-bbs/installation/hardware/rpi.html">Raspberry Pi</a></li>
<li><a href="/enigma-bbs/installation/hardware/windows.html">Installation Under Windows</a></li>
</ul>
<li><a href="/enigma-bbs/installation/network.html">Network Setup</a></li>
<li><a href="/enigma-bbs/installation/testing.html">Testing Your Installation</a></li>
<li><a href="/enigma-bbs/installation/production.html">Production Installation</a></li>
</ul>
<li>Configuration</li>
<ul>
<li><a href="/enigma-bbs/configuration/creating-config.html">Creating Initial Config Files</a></li>
<li><a href="/enigma-bbs/configuration/sysop-setup.html">SysOp Setup</a></li>
<li><a href="/enigma-bbs/configuration/config-files.html">Configuration Files</a></li>
<li><a href="/enigma-bbs/configuration/config-hjson.html">System Configuration</a></li>
<li class="active-nav">HJSON Config Files</li>
<li><a href="/enigma-bbs/configuration/menu-hjson.html">Menu HSJON</a></li>
<li><a href="/enigma-bbs/configuration/directory-structure.html">Directory Structure</a></li>
<li><a href="/enigma-bbs/configuration/external-binaries.html">External Support Binaries</a></li>
<li><a href="/enigma-bbs/configuration/archivers.html">Archivers</a></li>
<li><a href="/enigma-bbs/configuration/file-transfer-protocols.html">File Transfer Protocols</a></li>
<li><a href="/enigma-bbs/configuration/email.html">Email</a></li>
<li><a href="/enigma-bbs/configuration/colour-codes.html">Colour Codes</a></li>
<li><a href="/enigma-bbs/configuration/event-scheduler.html">Event Scheduler</a></li>
<li><a href="/enigma-bbs/configuration/acs.html">Access Condition System (ACS)</a></li>
<li><a href="/enigma-bbs/configuration/security.html">Security</a></li>
</ul>
<li>Miscellaneous</li>
<ul>
<li><a href="/enigma-bbs/misc/user-interrupt.html">User Interruptions</a></li>
</ul>
<li>File Base</li>
<ul>
<li><a href="/enigma-bbs/filebase/index.html">About File Areas</a></li>
<li><a href="/enigma-bbs/filebase/first-file-area.html">Configuring a File Base</a></li>
<li><a href="/enigma-bbs/filebase/acs.html">ACS</a></li>
<li><a href="/enigma-bbs/filebase/uploads.html">Uploads</a></li>
<li><a href="/enigma-bbs/filebase/web-access.html">Web Access</a></li>
<li><a href="/enigma-bbs/filebase/tic-support.html">TIC Support</a></li>
<li><a href="/enigma-bbs/filebase/network-mounts-and-symlinks.html">Network Mounts &amp; Symlinks</a></li>
</ul>
<li>Message Areas</li>
<ul>
<li><a href="/enigma-bbs/messageareas/configuring-a-message-area.html">Message Base</a></li>
<li><a href="/enigma-bbs/messageareas/message-networks.html">Message Networks</a></li>
<li><a href="/enigma-bbs/messageareas/bso-import-export.html">BSO Import / Export</a></li>
<li><a href="/enigma-bbs/messageareas/netmail.html">Netmail</a></li>
<li><a href="/enigma-bbs/messageareas/qwk.html">QWK Support</a></li>
<li><a href="/enigma-bbs/messageareas/ftn.html">FidoNet-Style Networks (FTN)</a></li>
</ul>
<li>Art</li>
<ul>
<li><a href="/enigma-bbs/art/general.html">General Art Information</a></li>
<li><a href="/enigma-bbs/art/themes.html">Themes</a></li>
<li><a href="/enigma-bbs/art/mci.html">MCI Codes</a></li>
<li>Views</li>
<ul>
<li><a href="/enigma-bbs/art/views/button_view.html">Button View</a></li>
<li><a href="/enigma-bbs/art/views/edit_text_view.html">Edit Text View</a></li>
<li><a href="/enigma-bbs/art/views/full_menu_view.html">Full Menu View</a></li>
<li><a href="/enigma-bbs/art/views/horizontal_menu_view.html">Horizontal Menu View</a></li>
<li><a href="/enigma-bbs/art/views/mask_edit_text_view.html">Mask Edit Text View</a></li>
<li><a href="/enigma-bbs/art/views/multi_line_edit_text_view.html">Multi Line Edit Text View</a></li>
<li><a href="/enigma-bbs/art/views/spinner_menu_view.html">Spinner Menu View</a></li>
<li><a href="/enigma-bbs/art/views/text_view.html">Text View</a></li>
<li><a href="/enigma-bbs/art/views/toggle_menu_view.html">Toggle Menu View</a></li>
<li><a href="/enigma-bbs/art/views/vertical_menu_view.html">Vertical Menu View</a></li>
</ul>
</ul>
<li>Servers</li>
<ul>
<li>Login Servers</li>
<ul>
<li><a href="/enigma-bbs/servers/loginservers/telnet.html">Telnet Server</a></li>
<li><a href="/enigma-bbs/servers/loginservers/ssh.html">SSH Server</a></li>
<li><a href="/enigma-bbs/servers/loginservers/websocket.html">Web Socket / Web Interface Server</a></li>
</ul>
<li>Content Servers</li>
<ul>
<li><a href="/enigma-bbs/servers/contentservers/web-server.html">Web Server</a></li>
<li><a href="/enigma-bbs/servers/contentservers/gopher.html">Gopher Server</a></li>
<li><a href="/enigma-bbs/servers/contentservers/nntp.html">NNTP Server</a></li>
</ul>
</ul>
<li>Modding</li>
<ul>
<li><a href="/enigma-bbs/modding/local-doors.html">Local Doors</a></li>
<li><a href="/enigma-bbs/modding/door-servers.html">Door Servers</a></li>
<li><a href="/enigma-bbs/modding/telnet-bridge.html">Telnet Bridge</a></li>
<li><a href="/enigma-bbs/modding/existing-mods.html">Existing Mods</a></li>
<li><a href="/enigma-bbs/modding/file-area-list.html">File Area List</a></li>
<li><a href="/enigma-bbs/modding/last-callers.html">Last Callers</a></li>
<li><a href="/enigma-bbs/modding/whos-online.html">Who's Online</a></li>
<li><a href="/enigma-bbs/modding/user-list.html">User List</a></li>
<li><a href="/enigma-bbs/modding/msg-conf-list.html">Message Conference List</a></li>
<li><a href="/enigma-bbs/modding/msg-area-list.html">Message Area List</a></li>
<li><a href="/enigma-bbs/modding/bbs-list.html">BBS List</a></li>
<li><a href="/enigma-bbs/modding/rumorz.html">Rumorz</a></li>
<li><a href="/enigma-bbs/modding/file-transfer-protocol-select.html">File Transfer Protocol Select</a></li>
<li><a href="/enigma-bbs/modding/onelinerz.html">Onelinerz</a></li>
<li><a href="/enigma-bbs/modding/show-art.html">The Show Art Module</a></li>
<li><a href="/enigma-bbs/modding/file-base-download-manager.html">File Base Download Manager</a></li>
<li><a href="/enigma-bbs/modding/file-base-web-download-manager.html">File Base Web Download Manager</a></li>
<li><a href="/enigma-bbs/modding/set-newscan-date.html">Set Newscan Date Module</a></li>
<li><a href="/enigma-bbs/modding/node-msg.html">Node to Node Messaging</a></li>
<li><a href="/enigma-bbs/modding/top-x.html">TopX</a></li>
<li><a href="/enigma-bbs/modding/user-2fa-otp-config.html">2FA/OTP Config</a></li>
<li><a href="/enigma-bbs/modding/autosig-edit.html">Auto Signature Editor</a></li>
<li><a href="/enigma-bbs/modding/menu-modules.html">Menu Modules</a></li>
</ul>
<li>Administration</li>
<ul>
<li><a href="/enigma-bbs/admin/administration.html">Administration</a></li>
</ul>
<li>Modding</li>
<ul>
<li><a href="/enigma-bbs/modding/wfc.html">Waiting For Caller (WFC)</a></li>
</ul>
<li>Administration</li>
<ul>
<li><a href="/enigma-bbs/admin/oputil.html">oputil</a></li>
<li><a href="/enigma-bbs/admin/updating.html">Updating</a></li>
</ul>
<li>Troubleshooting</li>
<ul>
<li><a href="/enigma-bbs/troubleshooting/monitoring-logs.html">Monitoring Logs</a></li>
</ul>
</ul>
</div>
<div class="main_area">
<div class="container">
<section id="main_content">
<div class="PageNavigation">
<a class="btn" style="float:left;margin-right: 20px;" href="/enigma-bbs/configuration/config-hjson.html">« System Configuration</a>
<a href="#sidebar" class="btn menu_button">MENU</a>
<a class="btn" style="float: right;margin-left: 20px" href="/enigma-bbs/configuration/menu-hjson.html">Menu HSJON »</a>
<br clear="both">
</div>
<div class="page">
<h1 class="page-title">HJSON Config Files</h1>
<h2 id="json-for-humans">JSON for Humans!</h2>
<p>HJSON is the configuration file format used by ENiGMA½ for <a href="/enigma-bbs/configuration/config-hjson.html">System Configuration</a>, <a href="/enigma-bbs/configuration/menu-hjson.html">Menus</a>, etc. <a href="https://hjson.org/">HJSON</a> is is <a href="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!): <code class="language-plaintext highlighter-rouge">#</code>, <code class="language-plaintext highlighter-rouge">//</code> and <code class="language-plaintext highlighter-rouge">/* ... */</code> style comments are allowed.</li>
<li>Keys never need to be quoted</li>
<li>…much more! See <a href="https://hjson.org/">the official HJSON website</a>.</li>
</ul>
<h2 id="terminology">Terminology</h2>
<p>Through the documentation, some terms regarding HJSON and configuration files will be used:</p>
<ul>
<li>
<code class="language-plaintext highlighter-rouge">config.hjson</code>: Refers to <code class="language-plaintext highlighter-rouge">/path/to/enigma-bbs/config/config.hjson</code>. See <a href="/enigma-bbs/configuration/config-hjson.html">System Configuration</a>.</li>
<li>
<code class="language-plaintext highlighter-rouge">menu.hjson</code>: Refers to <code class="language-plaintext highlighter-rouge">/path/to/enigma-bbs/config/&lt;yourBBSName&gt;-menu.hjson</code>. See <a href="/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 <code class="language-plaintext highlighter-rouge">foo: bar</code>, <code class="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><code class="language-hjson">someSection: {
foo: bar
}
</code></pre>
<p>Note that <code class="language-plaintext highlighter-rouge">someSection</code> is the configuration <em>section</em> (or <em>block</em>) and <code class="language-plaintext highlighter-rouge">foo: bar</code> is within it.</p>
</li>
</ul>
<h2 id="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>
<a href="https://www.sublimetext.com/">Sublime Text</a> via the <code class="language-plaintext highlighter-rouge">sublime-hjson</code> package.</li>
<li>
<a href="https://code.visualstudio.com/">Visual Studio Code</a> via the <code class="language-plaintext highlighter-rouge">vscode-hjson</code> plugin.</li>
<li>
<a href="https://notepad-plus-plus.org">Notepad++</a> via the <code class="language-plaintext highlighter-rouge">npp-hjson</code> plugin.</li>
</ul>
<p>See https://hjson.org/users.html for more more editors &amp; plugins.</p>
<h3 id="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>
<blockquote>
<p><img class="emoji" title=":information_source:" alt=":information_source:" src="https://github.githubassets.com/images/icons/emoji/unicode/2139.png" height="20" width="20"> See also <a href="/enigma-bbs/configuration/config-files.html">Configuration Files</a></p>
</blockquote>
<h3 id="case-sensitive">CaSe SeNsiTiVE</h3>
<p>Configuration keys are <strong>case sensitive</strong>. That means if a configuration key is <code class="language-plaintext highlighter-rouge">boardName</code> for example, <code class="language-plaintext highlighter-rouge">boardname</code>, or <code class="language-plaintext highlighter-rouge">BOARDNAME</code> <strong>will not work</strong>.</p>
<h3 id="escaping">Escaping</h3>
<p>Some values need escaped. This is especially important to remember on Windows machines where file paths contain backslashes (<code class="language-plaintext highlighter-rouge">\</code>). To specify a path to <code class="language-plaintext highlighter-rouge">C:\foo\bar\baz.exe</code> for example, an entry may look like this in your configuration file:</p>
<pre><code class="language-hjson">something: {
path: "C:\\foo\\bar\\baz.exe" // note the extra \'s!
}
</code></pre>
<h2 id="tips--tricks">Tips &amp; Tricks</h2>
<h3 id="json-compatibility">JSON Compatibility</h3>
<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 <code class="language-plaintext highlighter-rouge">hjson</code> CLI:</p>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">cd</span> /path/to/enigma-bbs
<span class="nb">cp</span> ./config/config.hjson ./config/config.hjson.backup
./node_modules/hjson/bin/hjson ./config/config.hjson.backup <span class="nt">-j</span> <span class="o">&gt;</span> ./config/config.hjson
</code></pre></div></div>
<p>You can always convert back to HJSON by omitting <code class="language-plaintext highlighter-rouge">-j</code> in the command above.</p>
<h3 id="oputil">oputil</h3>
<p>You can easily dump out your current configuration in a pretty-printed style using oputil: <code class="language-plaintext highlighter-rouge">./oputil.js config cat</code></p>
</div>
<div class="PageNavigation">
<a class="btn" style="float:left;margin-right: 20px;" href="/enigma-bbs/configuration/config-hjson.html">« System Configuration</a>
<a class="btn" style="float: right;margin-left: 20px" href="/enigma-bbs/configuration/menu-hjson.html">Menu HSJON »</a>
<br clear="both">
</div>
</section>
</div>
</div>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink