Config Library

A library that allows character-based addon configuration. It handles creation and maintenance of settings XML files for all user-related settings for an addon. It follows the standard Windower settings XML format as observed in plugins and most current addons.

Usage

config = require('config')

Functions

config.load(path, defaults)

settings = config.load(path, defaults)

• settings table - The resulting settings object

• path string [optional: Windower/addons/<addon>/data/settings.xml] - Path to the file to read from

• defaults table [optional: {}] - A table in the same format as the resulting settings containing default values

Loads the XML from a specified path (or the default path) and parses it. First it uses the provided defaults table (or an empty table, if none was specified) as a base table. Next it reads all elements under the <global> tag and treats XML elements and their text contents as key/value pairs. It overwrites the default table entries with values from the <global> tag. Finally it checks the current character's name and looks for an element under the settings root with that name. If it finds one, it overwrites the currently parsed table with values it gets from there.

If a default settings table is provided, it will try to coerce values so their type matches the default table value. If it reads the value <foo>246</foo> it will treat it as a string "246", unless the default table also contains a key foo with a numeric value. Then it will try to interpret the string as a number and parse it accordingly.

Unless the values are entirely unpredictable, it is strongly recommended to always provide a table with default values so the types can be coerced correctly.

config.register(settings, fn, ...)

handle = config.register(settings, fn, ...)

• handle number - Handle the event is known by

• settings table - A settings table that was returned by config.load

• fn function - A function to execute

• ... any - Extra arguments to pass to fn

Registers a function to be executed every time the config library reloads settings (i.e. on load/logout/login). The function will get the settings table as first parameter, following by any other arguments provided to config.register and is guaranteed to be executed after the settings are fully reloaded for the new character.

config.reload(settings)

config.reload(settings)

• settings table - A settings table that was returned by config.load

Reloads settings from the XML, applies any changes made to the file since the original load to the provided table. Parsing happens according to the same rules as with config.load.

config.save(settings, character)

config.save(settings, character)

• settings table - A settings table that was returned by config.load
• character string [optional: current character's name] - The character the settings should be saved under

Saves the previously parsed settings object to the file it was loaded from. Writes in a format that can later be loaded again by config.load. The current settings table will be applied to the character provided, defaulting to the current character. If 'all' is provided as character, it will overwrite the <global> settings and erase all character-specific settings, making the currently loaded settings applicable for every character.

config.unregister(settings, handle)

config.unregister(settings, handle)

• settings table - A settings table that was returned by config.load
• handle number - Handle returned by config.register

Unregisters an event previously registered by config.register for the provided settings object.