settings

The settings library is used to allow addons to create per-character configuration files. The library manages and handles the switching of characters automatically, addons simply need to register to an event, per-settings block, to receive the updated settings table information when a character switch happens.

Settings are serialized into a readable Lua table format making it easy for users to modify the settings on disk if needed.

The library will default to a character alias of _default_ when no character is logged in. Most of the functions of this library that accept an alias consider the alias optional. When no alias is given to these functions, then a default alias of settings is used instead.

The settings files are saved to the daochook configurations folder. These are saved within this folder under a series of subfolders. For example:

• Defaults: <daochook_path>/config/addons/<addon_name>/_defaults_/<alias>.lua
• Character: <daochook_path>/config/addons/<addon_name>/<character_name>/<alias>.lua

An example set of paths would be the following for the fps addon:

• Defaults: <daochook_path>/config/addons/fps/_defaults_/settings.lua
• Character: <daochook_path>/config/addons/fps/Atomos/settings.lua

Using The Library

1local settings = require 'settings';

Functions

settings_path

Returns the current settings path. (Specific to the given addons namespace.)

1string settings.settings_path();

The path returned by this function will look like this:

• When logged out: <daochook_path>/config/addons/<addon_name>/_defaults_/
• When logged in: <daochook_path>/config/addons/<addon_name>/<character_name>/

load

Loads and returns a settings table.

1table settings.load(defaults);
2table settings.load(defaults, alias);

If no alias is given, then the default alias of settings will be used instead.

Note: This function will raise events against the alias.

save

Saves a settings table to disk.

1boolean settings.save();
2boolean settings.save(alias);

If no alias is given, then the default alias of settings will be used instead.

reload

Reloads a settings table from disk.

1boolean settings.reload();
2boolean settings.reload(alias);

If no alias is given, then the default alias of settings will be used instead.

Note: This function will raise events against the alias.

reset

Resets a settings table to its defaults.

1boolean settings.reset();
2boolean settings.reset(alias);

If no alias is given, then the default alias of settings will be used instead.

Note: This function will raise events against the alias.

get

Returns the settings table for the given alias.

1table|nil settings.get();
2table|nil settings.get(alias);

If no alias is given, then the default alias of settings will be used instead.

register

Registers an event callback to a settings block.

1settings.register(alias, event_alias, callback);

unregister

Unregisters an event callback from a settings block.

1settings.unregister(alias, event_alias);

process

Processes a settings table, converting it to a string that can be reloaded into Lua later.

1string settings.process(o, space);

Event Usage

The settings library makes use of a custom event setup (similar to normal addon events) that is used to inform an addon of when a settings table is changed. (Via loading, reload, or resetting.) Addons can register to a specific settings table for this event to ensure their current settings are up to date with what the library has currently loaded and cached.

The registration to the given event looks like this:

1settings.register('settings', 'settings_update', function (e)
2
3end);

Note: The alias given here, settings is the default alias when a unique one is not given. If you are using a specific alias for your settings, then you should change this string to match!

When this event is invoked, e will contain the updated settings table that your addon should make use of. It is also ideal for your addon to make any adjustments, update its various properties/UI/etc. and such in relation to these new settings to ensure what is curerntly being shown/used is properly up to date. Afterward, it is suggested that you also save the settings after to ensure your settings and the library match on disk.

Here is an example of all of this:

 1-- Include the needed libraries..
 2require 'common';
 3local settings = require 'settings';
 4
 5-- Define your addons default settings..
 6local default_settings = T{
 7    value1 = 1234,
 8    value2 = true,
 9    value3 = 'Hello world.',
10};
11
12-- Load the addon settings..
13local cfg = settings.load(default_settings);
14
15-- Register to the settings update event..
16settings.register('settings', 'settings_update', function (e)
17    -- Update the settings table..
18    cfg = e;
19
20    --[[
21    Do additional updates to your addons properties here.
22    --]]
23
24    -- Ensure settings are saved to disk when changed..
25    settings.save();
26end);

You should not edit your default_settings table ever when defining it as the defauls/outline of what you expect for your addons settings. All edits should be made to the table returned from settings.load(...). If you need to obtain the settings table again you can use settings.get(...) to obtain the table from the settings library.