enigma-bbs/docs/configuration/config-files.md

layout	title
page	Configuration Files

General Information

ENiGMA½ configuration files such as the system config, menus and themes are formatted in the HJSON format.

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:

// menu.hjson
{
    includes: [
        message-base.hjson
        file-base.hjson
    ]

    menus: {
        someOtherMenu: {
            // ...
        }
    }
}

// message-base.hjson
{
    menus: {
        someMessageMenu: {
            // ...
        }
    }
}

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 block can be referenced:

{
    //  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
                }
            }
        }
    }
}

ℹ️ An unresolved @reference will be left intact.

Environment Variables

Especially in a container environment such as Docker, 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 object representing 2020-01-05
@environment:SOME_VAR:timestamp:array	"2020-01-05,2016-05-16T01:15:37'"	An array of moment objects representing 2020-01-05 and 2016-05-16T01:15:37

ℹ️ bool may be used as an alias to boolean.

ℹ️ timestamp values can be in any form that moment can parse.

ℹ️ An unresolved or invalid @environment will be left intact.

Consider the following fragment:

{
    foo: {
        bar: @environment:BAR_VAR:number
    }
}

If the environment has BAR_VAR=1337, this would produce:

{
    foo: {
        bar: 1337
    }
}

See Also

• System Configuration
• Menu Configuration
• The HJSON Format