Class Core.Configuration
The Configuration class is responsible for managing the addon's configurations, settings, options, and anything else that can be persisted in the table used by the game client to store saved variables.
It provides methods to easily access and manipulate the configuration properties. That reduces the need to pollute the addon code with sanity checks, index initializations, etc.
All the configuration keys in this class can be accessed using the dot notation, similar to the how the Arr class works.
Local Functions
| core.configuration.handle (...) | The handle method is used forward the configuration operation coming from the library config() method. |
| core.configuration.maybePrefixKey (key) | Prefixes a key with the prefix key if it's set. |
Methods
| core.configuration:get (key, default) | Gets a configuration property by a dot notation key or returns a default value if the key does not exist. |
| core.configuration:getOrInitialize (key, default) | Gets a configuration property by a dot notation key or initializes it with a default value if the key does not exist. |
| core.configuration:set (key, value) | Sets a configuration property by a dot notation key. |
| core.configuration:setPrefixKey (value) | Sets a prefix key that will be used to prefix all the configuration keys. |
Metamethods
| core.configuration:__construct (savedVariable) | Configuration constructor. |
Local Functions
Methods- core.configuration.handle (...)
-
The handle method is used forward the configuration operation coming
from the library config() method.
This method should not be called directly. It is used internally by the library to handle the configuration operations.
Parameters:
- ...
- core.configuration.maybePrefixKey (key)
-
Prefixes a key with the prefix key if it's set.
This method is used internally to prefix the configuration keys with the prefix key if it's set. It should not be called directly, especially when getting or setting configuration properties, otherwise the prefix may be added twice.
Parameters:
- key string The key to be prefixed
Returns:
-
string
The key with the prefix if it's set, or the key itself
Methods
- core.configuration:get (key, default)
-
Gets a configuration property by a dot notation key or returns a default
value if the key does not exist.
Parameters:
- key string The dot notation key to be used to retrieve the configuration property
- default any The default value to be returned if the key does not exist
Returns:
-
any
The configuration property value or the default value if the
key does not exist
Usage:
library.configuration:get('test.property', 'default-value')
- core.configuration:getOrInitialize (key, default)
-
Gets a configuration property by a dot notation key or initializes it
with a default value if the key does not exist.
This method is similar to the get() method, but it also initializes the property with the default value if the key does not exist.
Parameters:
- key string The dot notation key to be used to retrieve the configuration property
- default any The default value to be returned if the key does not exist
Returns:
-
any
The configuration property value or the default value if the
key does not exist
See also:
Usage:
library.configuration:getOrInitialize('test.property', 'default-value')
- core.configuration:set (key, value)
-
Sets a configuration property by a dot notation key.
This will update the configuration property with the new value. If the key does not exist, it will be created.
Parameters:
- key string The dot notation key to be used to set the configuration property
- value any The value to be set in the configuration property
Usage:
library.configuration:set('test.property', 'new-value')
- core.configuration:setPrefixKey (value)
-
Sets a prefix key that will be used to prefix all the configuration keys.
If this method is not called during the addon lifecycle, no prefixes will be used.
One of the reasons to use a prefix key is to group configuration values and settings per player, realm, etc.
Note: The prefix will be concatenated with a dot before any key used in this class, which means that this method should not be called with a prefix key that already ends with a dot.
Parameters:
- value string The prefix key to be used to prefix all the configuration keys
Returns:
-
Core.Configuration
The Configuration instance itself to allow method chaining
Metamethods
- core.configuration:__construct (savedVariable)
-
Configuration constructor.
The configuration instance expects a table with the configuration data which is also referenced in the TOC file. That way, each instance of this class will handle a saved variable.
Stormwind Library will automatically create an instance of this class when the addon is loaded in case a table is referenced in the addon's properties, however, if the addon needs to have multiple configurations, one instance of this class should be created for each table.
Parameters:
- savedVariable table The configuration data to be used by the addon. This table instance must be the same one referenced in the TOC SavedVariables property.