settings

This library allows addons to persist and load configuration options.

local settings = require('settings')

❗ Dependency Required

To use this library, you must include settings in the manifest.xml file for your package:

<dependency>settings</dependency>

Tables

The settings table has the following entries:

• settings.load : Loads a set of configuration options from a file.
• settings.save : Saves a set of configuration options to a file.
• settings.get : Gets a specific setting for the provided path.
• settings.set : Sets a specific setting for the provided path to the provided value.
• settings.settings_change : Event that triggers when the configuration options are reparsed.

---

settings.load

Loads a table of configuration options from a file.

Definition

function settings.load(defaults : table, name : string = 'settings', global: boolean = false) : table

Parameters

defaults table

A table that contains the default configuration options.

name string [default: 'settings']

A name to associate the options with. Only necessary if an addon uses multiple distinct option tables.

global boolean [default: false]

Indicates whether or not a settings object should apply globally, which prevents character-specific settings files.

Return

options table

A table that contains the loaded configuration options. The table returned is a combination of options loaded from the file, where available, and the defaults table, where not.

settings.save

Saves a table of configuration settings to a file.

Definition

function settings.save(options : table)

Parameters

options table

The table that contains the configuration options to save.

Return

This function does not return any values.

settings.get

Gets a specific setting for the provided path.

Definition

function settings.get(path : string, name : string = 'settings') : any

Parameters

path string

The path which identifies a specific setting.

name string [default: 'settings']

A name to identify the options table.

Return

value any

The setting at the specified path.

Example

local options = settings.load({
    window = {
        position = {
            x = 123,
            y = 456,
        },
    }
}

print(settings.get('window.position.y')) -- prints 456

settings.set

Gets a specific setting for the provided path to the provided value.

Definition

function settings.set(path : string, value : any, name : string = 'settings')

Parameters

path string

The path which identifies a specific setting.

value any

The value to assign to the setting.

name string [default: 'settings']

A name to identify the options table.

Return

This function does not return any values.

settings.settings_change

An event that triggers when the configuration options are reparsed, currently on account login and account logout.

Definition

settings.settings_change : event

Parameters

This event does not receive any parameters.