diff --git a/WHATSNEW.md b/WHATSNEW.md index 21d43083..27b8dfa2 100644 --- a/WHATSNEW.md +++ b/WHATSNEW.md @@ -4,8 +4,8 @@ This document attempts to track **major** changes and additions in ENiGMA½. For ## 0.0.12-beta * The `master` branch has become mainline. What this means to users is `git pull` will always give you the latest and greatest. Make sure to read [Updating](/docs/admin/updating.md) and keep an eye on `WHATSNEW.md` (this file) and [UPGRADE](UPGRADE.md)! See also [ticket #276](https://github.com/NuSkooler/enigma-bbs/issues/276). * The default configuration has been moved to [config_default.js](/core/config_default.js). -* A full configuration revamp has taken place. Configuration files such as `config.hjson`, `menu.hjson`, and `theme.hjson` can now utilize includes via the `include` directive, reference 'self' sections using `@reference:` and import environment variables with `@environment`. -* An explicit prompt file previously specified by `general.promptFile` in `config.hjson` is no longer necessary. Instead, this now simply part of the `prompts` section in `menu.hjson`. The default setup still creates a separate prompt HJSON file, but it is `include`ed in `menu.hjson`. +* A full configuration revamp has taken place. Configuration files such as `config.hjson`, `menu.hjson`, and `theme.hjson` can now utilize includes via the `includes` directive, reference 'self' sections using `@reference:` and import environment variables with `@environment`. +* An explicit prompt file previously specified by `general.promptFile` in `config.hjson` is no longer necessary. Instead, this now simply part of the `prompts` section in `menu.hjson`. The default setup still creates a separate prompt HJSON file, but it is `includes`ed in `menu.hjson`. ## 0.0.11-beta * Upgraded from `alpha` to `beta` -- The software is far along and mature enough at this point! diff --git a/core/system_events.js b/core/system_events.js index 129dacfd..00f242ca 100644 --- a/core/system_events.js +++ b/core/system_events.js @@ -9,7 +9,6 @@ module.exports = { ThemeChanged : 'codes.l33t.enigma.system.theme_changed', // (theme.hjson): { themeId } ConfigChanged : 'codes.l33t.enigma.system.config_changed', // (config.hjson) MenusChanged : 'codes.l33t.enigma.system.menus_changed', // (menu.hjson) - PromptsChanged : 'codes.l33t.enigma.system.prompts_changed', // (prompt.hjson) // User - includes { user, ...} NewUser : 'codes.l33t.enigma.system.user_new', // { ... } diff --git a/docs/_includes/nav.md b/docs/_includes/nav.md index 941637c3..1f8e27c7 100644 --- a/docs/_includes/nav.md +++ b/docs/_includes/nav.md @@ -13,6 +13,7 @@ - Configuration - [Creating Config Files]({{ site.baseurl }}{% link configuration/creating-config.md %}) - [SysOp Setup]({{ site.baseurl }}{% link configuration/sysop-setup.md %}) + - [Configuration Files]({{ site.baseurl }}{% link configuration/config-files.md %}) - [System Configuration]({{ site.baseurl }}{% link configuration/config-hjson.md %}) - [HJSON Config Files]({{ site.baseurl }}{% link configuration/hjson.md %}) - [Menus]({{ site.baseurl }}{% link configuration/menu-hjson.md %}) diff --git a/docs/configuration/config-files.md b/docs/configuration/config-files.md new file mode 100644 index 00000000..ae625d2a --- /dev/null +++ b/docs/configuration/config-files.md @@ -0,0 +1,99 @@ +--- +layout: page +title: Configuration Files +--- +## General Information +ENiGMA½ configuration files such as the [system config](config-hjson.md), [menus](menu-hjson.md) and [themes](../art/themes.md) are formatted in the [HJSON format](hjson.md). + +## Hot-Reload +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. + +## Common Directives +### Includes +Most configuration files offer an `includes` 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 `menu.hjson`, the SysOp may break this into `message-base.hjson`, `file-base.hjson`, etc. + +The `includes` directive may be used the top-level scope of a configuration file: +```hjson +{ + // menu.hjson + + includes: [ + message-base.hjson + file-base.hjson + ] + + menus: { + someMenu: { + // ... + } + } +} +``` + +### References +Often times in a configuration you will find that you're repeating yourself quite a bit. ENiGMA½ provides an `@reference` that can help with this in the form of `@reference:dot.path.to.section`. + +Consider `actionKeys` in a menu. Often times you may show a screen and the user presses `Q` or `ESC` to fall back to the previous. Instead of repeating this in many menus, a generic recyclable block can be utilized: + +```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 + } + } + } + } +} +``` + +:information_source: An unresolved @reference will be left intact. + +### Environment Variables +Especially in a container environment such as [Docker](/docs/installation/docker.md), environment variable access in configuration files can become very handy. ENiGMA½ provides a flexible way to access variables using the `@environment` directive. The most basic form of `@environment:VAR_NAME` produces a string value. Additionally a `:type` 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 `:array` suffix. + +Below is a table of the various forms: +| Form | Variable Value | Produces | +|------|----------------|----------| +| `@environment:SOME_VAR` | "Foo" | `"Foo"` (without quotes) | +| `@environment:SOME_VAR` | "123" | `"123"` (without quotes) | +| `@environment:SOME_VAR:string` | "Bar" | `"Bar"` (without quotes) | +| `@environment:SOME_VAR:string:array` | "Foo,Bar" | `[ 'Foo', 'Bar' ]` | +| `@environment:SOME_VAR:boolean` | "1" | `true` | +| `@environment:SOME_VAR:boolean` | "True" | `true` | +| `@environment:SOME_VAR:boolean` | "false" | `false` | +| `@environment:SOME_VAR:boolean` | "cat" | `false` | +| `@environment:SOME_VAR:boolean:array` | "True,false,TRUE" | `[ true, false, true ]` | +| `@environment:SOME_VAR:number` | "123" | `123` | +| `@environment:SOME_VAR:number:array` | "123,456" | `[ 123, 456 ]` | +| `@environment:SOME_VAR:number` | "kitten" | (invalid) | +| `@environment:SOME_VAR:object` | '{"a":"b"}' | `{ 'a' : 'b' }` | +| `@environment:SOME_VAR:object:array` | '{"a":"b"},{"c":"d"}' | `[ { 'a' : 'b' }, { 'c' : 'd' } ]` | +| `@environment:SOME_VAR:timestamp` | "2020-01-05" | A [moment](https://momentjs.com/) object representing 2020-01-05 | +| `@environment:SOME_VAR:timestamp:array` | "2020-01-05,2016-05-16T01:15:37'" | An array of [moment](https://momentjs.com/) objects representing 2020-01-05 and 2016-05-16T01:15:37 | + +:information_source: `bool` may be used as an alias to `boolean`. + +:information_source: `timestamp` values can be in any form that [moment can parse](https://momentjs.com/docs/#/parsing/). + +:information_source: An unresolved or invalid @environment will be left intact. + +## See Also +* [System Configuration](config-hjson.md) +* [Menu Configuration](menu-hjson.md) +* [The HJSON Format](hjson.md)