logo
back Back to Downloads

Pkg-MayronDB

A lightweight, feature rich embedded addon database for managing addon settings with built-in profile management.

downloaddownloaddownloadDownload from WoWInterfacedownloaddownloaddownloadDownload from CurseForge
1

About

MayronDB is a lightweight, embedded Lua database designed to store and manage addon settings for World of Warcraft addon projects and supports both Retail and Classic. The prefix Pkg- refers to it being a package that is part of the MayronObjects packaging ecosystem and leverages its features to build a well-defined API to deliver a smooth development experience. Therefore, this package has a dependency on the MayronObjects framework. Please make sure to have downloaded this framework and have it loaded when using this package.

Pkg-MayronDB lets you:

  • Control profiles of addon settings with MayronDB's built-in profile management API, allowing addons to respond to profile changes without requiring a reload of the UI.
  • Define default addon settings that MayronDB will automatically use if the user has not overridden them for custom user settings.
  • Use database table inheritance to avoid duplicate code. Define a database table as a "parent" table to inherit all settings from across multiple tables. For example, instead of storing multiple tables holding appearance and positioning settings for multiple unit frames, MayronDB can be configured to allow multiple tables to inherit from a single table, avoiding the need for manual checks.
  • Register "update functions" against a database setting using its path address. If the value located at that path address changes, MayronDB will automatically execute the registered update function (see section 5).
  • Add settings to a global table to be shared between all profiles.
  • Keep memory usage low by automatically recycling unused resources and pruning empty tables in the database.
  • Call helper methods directly on any database table in the database tree to execute helper methods, such as printing or iterating over each addon setting inside the nested table, and more.

The blog post below compares the differences between AceDB and MayronDB. It also explains update functions in more detail:

Embedded content: https://mayronui.com/blog/post/what-is-the-difference-between-acedb-and-libmayrondb

There is a Test.lua file included in the downloaded addon folder to see other working examples of how to use this package.

As mentioned, this package has a dependency on the MayronObjects framework. Make sure you have that installed first.

2

How it works

When targetting a value in the database using a statement, also referred to as a query, such as db.profile.module.value, MayronDB's Observer system will select the most appropriate value depending on several factors. MayronDB will automatically retrieve default settings, possibly from a parent table if using database inheritance, if the targetted value does not exist in the addon's saved variable table. If the query attempts to access the profile table instead of the global table, MayronDB will only use the active profile's table.

2.1 What is the "Observer" System?

Each database table, also referred to as a database node in the database tree, is controlled by an observer. An observer is an object created by MayronObjects that watches for read/write requests to values inside its database table. When a user attempts to read from a missing value, the observer will look up the appropriate database tables to find the most appropriate value to be returned. For example, if a default value exists for the missing value, then this will be returned. If database inheritance is in use, the observer will check the parent table, or possibly the parent's default table (see section 2.2). You can also call observer methods directly on any database node from any nested level of the database tree, such as: db.profile.module:Print() where module is some arbitrary table (see section 8 for the full list of observer methods).

The embedded addon database is persisted to, and loaded from, a "saved variable". World of Warcraft stores saved variables inside Lua files located in the WTF folder. When the user exits the game, these files get updated with the saved variables' latest state before saving the file. The saved variables are then reinjected into the Lua environment when the game restarts, allowing them to continue using the addon without losing their customized addon settings. MayronDB stores the "real" database inside a table marked as a saved variable. It guards this table by controlling how it is accessed using the Observer system.

2.2 How Observers Control Data

World of Warcraft cannot store and persist functions or metatables inside files, and so the saved variable database table must be kept as a basic Lua table. Instead, MayronDB creates an in-memory representation of the saved variable table representing the "real" embedded database, where each nested database table is an observer object. Each observer runs __index and __newindex meta-methods to control how the saved variable table is accessed and can switch to using default values if necessary. To achieve this, each observer contains a "path address". A path address is a string value used to identify a node's location within the in-memory database tree. For example:

  • Both db.profile and db.profile.aTable are observers.
  • db.profile holds the path address "db.profile".
  • db.profile.aTable holds the path address "db.profile.aTable".

If an addon tries to read a value (a process also known as indexing) at a given path address that does not exist in the saved variable table, it will switch to using the "defaults" table. If an addon attempts to add a value to the database whose value is equal to the value found within the defaults table at the given path address, it will be removed from the saved variable table, and MayronDB prunes the saved variable table by removing empty tables. This process ensures that the saved variable table is kept small to avoid wasting resources.

When an addon tries to read or write a value from an observer located at a given path address, the observer performs several steps to retrieve the most appropriate value:

  1. Check if the key/value pair is located in the saved variable table.
  2. If not found, check if the key/value pair is located in the defaults table.
  3. If not found, check if the observer has a parent. If it does, repeat step 1 using the parent observer.
3

Starting the Database

The following placeholders should be swapped out for the concrete values of the addon using MayronDB:

  • ADDON_NAME: The name of the addon using MayronDB. If supplied, it will automatically start the database after the ADDON_LOADED Blizzard event has fired (when the saved variable becomes accessible).
  • SAVED_VARIABLE_NAME: The saved variable's name to hold the database as defined in the TOC file.
  • DATABASE_NAME: Optionally assign a user-friendly name for the database - useful if an addon uses multiple databases.

First, make sure to load the package before loading the addon that depends on it. Either install the package as a stand-alone addon or reference it in your addon's .toc file. The saved variable used to store the database needs to be registered inside your addon's toc file:

## SavedVariables: SAVED_VARIABLE_NAME

Then, import Pkg-MayronDB into one of your addon's .lua files and create a new database for it to use. Usually, you will want to add a callback function for when the database starts:

-- import the MayronObjects framework: local obj = MayronObjects:GetFramework(); -- import Pkg-MayronDB from MayronObjects: local mayronDB = obj:Import("Pkg-MayronDB.MayronDB"); -- create the database: local db = mayronDB.Static:CreateDatabase( "SAVED_VARIABLE_NAME", manualStartUp, "DATABASE_NAME"); db:OnStartUp(function(self) -- your code here! -- self is a reference to the database. end);

Set manualStartUp to true if you do not want MayronDB to automatically start the database when the saved variable becomes accessible.

4

Using the Database

For both methods, you can add database default values before and after starting the database:

db:AddToDefaults("profile.newModule", { width = 500, height = 300, data = {} });

Once the database has successfully started, you can start adding on to the db.global and db.profile observers just like you would do for a standard table. There are many database methods attached to the database object and observer methods attached to each observer. The database object returned by the CreateDatabase MayronDB method (i.e., the db local variable shown in each code snippet) is not an observer. It contains the profile and global root observers and provides many helper methods, as well as built-in profile management methods, as shown below:

db.profile.myModule = {}; db.profile.myModule.width = 500; print(db.profile.myModule.width); -- prints 500 print(db:GetCurrentProfile()); -- prints "Default" db:SetProfile("new profile"); print(db.profile.newModule.width); -- fails because newModule table is not stored on "new profile"

Line 5 shows the GetCurrentProfile database method being used to return the currently active profile. There are many more database methods, as described in section 7. For the full list of observer methods, see section 8.

4.1 Database Inheritance

MayronDB allows for template tables consisting of generic settings to act as a parent table in an inheritance hierarchy. The template table, usually some nested default settings table, is set as the parent table of multiple other tables. If a requested value is not found in the child table, the observer associated with that child table will look for the value inside the parent template table. This feature reduces the number of duplicate settings stored in-memory as each child can share the same default settings and override them on an individual basis if needed.

For example, a unit frame addon may store several sets of default tables for each unit frame. The player and target unit frame's default settings might be almost identical. With other database libraries, you would either need to store duplicate copies of the same settings or use lots of manual checks in the addon's code to select the correct value. For example, you might need to check if the player unit frame has a custom height, and if not to use the default height:

local height = db.profile.unitFrames.player.height or db.defaults.unitFrames.height;

MayronDB can ensure that db.profile.unitFrames.player.height always refers to the correct value using the customized value if there is one or defaulting to the defaults table. So the line above simplifies to:

local height = db.profile.unitFrames.player.height;

All you need to do is setup inheritance so that the player table inherits from some template table:

db:AddToDefaults("profile.unitFrames", { __templateUnitFrame = { height = 123; }; player = {} }); db.profile.unitFrames.player:SetParent( db.profile.unitFrames.__templateCastBar);

For a real use-case, see the code in MayronUI that uses templates for the timerbar fields.

The template observer is added to the defaults table, and then each timer-bar field database table is assigned that template as a parent. The user can later customize each concrete timer-bar field by assigning concrete values to the child tables.

It is recommended to prefix template tables with __template as shown in the previous example. By doing so, this tells MayronDB that it is used for inheritance only and should be ignored under certain internal conditions for optimization purposes.

5

Update Functions

Update functions are a unique feature to MayronDB. They are used to separate your addon's update logic from its configuration logic; how your addon updates its appearance and functionality when its configuration changes. When you allow a user to change your addon's configuration settings, you will typically execute custom functions to change the addon's database (i.e., the saved variable table). You would then usually update the UI to reflect those changes.

Typically, the configuration logic contains many functions to handle these changes. You would pull the relevant modules (chunks of code) or functions into the configuration code to trigger them manually. Update functions remove this coupling by keeping functions used to update your code's relevant modules separate from the configuration code. Update functions are callback functions registered with a given database path address and are automatically triggered by MayronDB when the value at the location specified by the path address changes.

Because MayronDB uses observers to observe values in the saved variables table, it can trigger the correct update function when a given value is changed. For example, we can register an update function to execute when db.profile.module.value is changed. This update function can be placed anywhere in your addon's codebase, preferably where it has access to all of the resources it needs to perform its task. This approach is much more straightforward than having it embedded in the same .lua file your config menu uses to display widgets for changing settings.

__ For example:__ The below code snippet shows how to register multiple update functions. If the width or height values are changed in the module saved variables table for your addon's current profile then these functions will execute and update the size of the frame assigned to the myFrame variable (assuming it exists):

db:RegisterUpdateFunctions("profile.module", { width = function(value) myFrame:SetWidth(value); end; height = function(value) myFrame:SetHeight(value); end; });

If you only want to register one function, then you can pass it into RegisterUpdateFunctions as the 2nd argument:

db:RegisterUpdateFunctions("profile.module.width", function(value) myFrame:SetWidth(value); end);

When you change a database value, the update function will trigger. For example, both of these lines will trigger the update function previously defined:

db.profile.module.width = 500; db:SetPathValue("profile.module.width", 500);

When using db:SetPathValue(path, value), this will call the update function (if one has been registered for that path value) using db:TriggerUpdateFunction(path) after it has changed the value. If you call TriggerUpdateFunction manually, then it will execute your update function but it will not change the database value.

5.1 When to trigger update functions manually.

You would only usually call db:TriggerUpdateFunction(path) when you want to execute update functions without manually changing the database value. The two most popular use-cases for this are:

  1. When loading your addon.
  2. When your addon changes profiles.

Typically, the startup code for your addon partially overlaps with your update logic. For example, you always need to set the width and height of certain frame elements when you log into the game, and most likely, you will allow the user to customize these width and height values. Therefore, you may want to execute the update functions manually during startup rather than duplicating the code to be used across different files for both the startup and update processes. You can always use a global variable or write some code to provide the reference to this function to call it manually, or you can use the database object you already have to let MayronDB handle this for you:

db:TriggerUpdateFunction("profile.myModule.width")

You can also assign a callback handler function to your database's OnProfileChange event and then trigger update functions manually. It is a good idea to refresh the appearance and functionality of your addon when its profile changes:

db:OnProfileChange(function(self, newProfileName, oldProfileName) self:TriggerUpdateFunction("profile.myModule.width"); end);

5.2 Overriding the automatic execution

If you want to use update functions but don't want update functions automatically executing for certain situations then you can provide a manual function to decide whether to execute it or not. For example, if a module in your addon is disabled then you most likely do not need to update its appearance or functionality. You can pass a manual decision function as the 3rd argument of RegisterUpdateFunctions to achieve this:

local manualUpdater = function(updateFunction, fullPath, newValue) -- updateFunction will be a reference to updateWidth -- fullPath = "profile.myModule.width" if (db.profile.myModule.enabled) then updateFunction(newValue); end end local updateWidth = function(value) myFrame:SetWidth(value); end db:RegisterUpdateFunctions("profile.myModule.width", updateWidth, manualUpdater);
6

MayronDB API

Each method described in this section is a static MayronDB class method. The MayronDB class is contained inside the Pkg-MayronDB package imported from MayronObjects:

local obj = MayronObjects:GetFramework(); local C_MayronDB = obj:Import("Pkg-MayronDB.MayronDB");

When using MayronObjects, it is conventional to include the C_ prefix for class variables.

You should then call the following methods using the .Static table directly from the class (you do not create an instance of the MayronDB class). For example:

local db = C_MayronDB.Static:CreateDatabase(...);

Static:CreateDatabase(addonName, svName, manualStartUp, databaseName)

  • @param svName (string): The name of the saved variable defined in the toc file.
  • @param addonName (string): The name of the addon using MayronDB. If supplied, it will automatically start the database after the ADDON_LOADED event has fired, and the saved variable becomes accessible.
  • @param manualStartUp (optional boolean): Set to true if you do not want MayronDB to automatically start the database as soon as the saved variable becomes accessible.
  • @param databaseName (optional string): Assign a user-friendly name for the database (useful if you have multiple databases for a single addon).
  • @return (Database): The created database object.

This function creates the database object, but the saved variable table or profiles will not be available until after the ADDON_LOADED event executes. This event will trigger the database to "start up". However, you can add default values before the database has started.

Static:GetDatabaseByName(dbName)

  • @param dbName (string): The name of the database registered with MayronDB.
  • @return (Database or nil): The created/registered database object associated with the addon pecified by addonName.

Gets the database registered with the specified database name (if given a name when created using CreateDatabase). Must be registered using CreateDatabase, else nil will be returned. The database does not need to have been started for the database to be returned using this method.

Static:GetDatabaseBySavedVariableName(svName)

  • @param svName (string): The name of the saved variable registered with MayronDB.
  • @return (Database or nil): The created/registered database object associated with the addon specified by addonName.
  • Gets the database registered with the specified saved variable name. Must be registered using CreateDatabase, else nil will be returned. The database does not need to have been started for the database to be returned using this method.

Static:IterateDatabases()

Returns addonName, db (the Database object) for each registered database (using db:CreateDatabase()) per iteration.

Static:SetPathValue(rootTable, path, value)

  • @param rootTable (table): The table to traverse through using the path.
  • @param path (string): The path of nested sub-tables contained inside the root table for MayronDB to traverse. If any of the sub-tables do not exist, MayronDB will create them.
  • @param value (any): A value to be added in the last nested sub-tabl specified by the path address. The key will be the last idenftifier inside the path.

This is similar to the Database object's SetPathValue, except it can be used as a helper method on any table. This method does not accept Observer objects as the root table as you should use the Database SetPathValue method for this instead.

Example:

local myTable = {}; C_MayronDB.Static:SetPathValue(myTable, "nestedTable.module.height", 200); print(myTable.nestedTable.module.height); -- will print 200

Static:ParsePathValue(rootTable, path)

  • @param rootTable (table): The table to traverse through using the path.
  • @param path (string): The path of nested sub-tables and possibly a final value contained inside the root table for MayronDB to traverse. Unlike SetPathValue, if any of the sub-tables do not exist, MayronDB will return nil and will not create them.

This is similar to the Database object's ParsePathValue, except it can be used as a helper method on any table. This method does not accept Observer objects as the root table as you should use the Database ParsePathValue method for this instead.

Example:

local myTable = {}; C_MayronDB.Static:SetPathValue(myTable, "nestedTable.module.height", 200); local height = C_MayronDB.Static:ParsePathValue( myTable, "nestedTable.module.height"); print("Height: ", height); -- will print "Height: 200"
7

Database API

Below is the full list of all Database class methods. An instance of this class is returned using the CreateDatabase MayronDB method.

OnStartUp(func)

  • @param func (function): Assign a callback function to the database StartUp event. The function will receive a reference to the database as its first argument.

Example:

db:OnStartUp(function(self) -- self is a reference to the Database instance object. -- It is useful to assign this to a global variable: MyUI.db = self; if (not self.global.isInstalled) ShowInstaller(); end end);

OnProfileChange(callback)

  • @param callback (function): The function to be called after the database's profile has changed.

Hooks a callback function onto the ProfileChange event to be called when the database changes profile. This is only changed by the user using db:SetProfile() or db:RemoveProfile(currentProfile).

MayronDB executes this callback function with three arguments:

  • 1st argument = self; a reference to the database object
  • 2nd argument = the new profile name
  • 3rd argument = the old profile name

AddToDefaults(path, value)

  • @param path (string): The path to locate a new value being added into the database defaults table.
  • @param value (any): The new value to be added into the database defaults table.
  • @return (boolean): Whether a key and value pair was added successfully.

Adds default values that are used if there is no value for the given path in the saved variables table. You can use this method before and after MayronDB starts the database.

Example:

db:AddToDefaults("profile.aModule['red theme'][10].object", value);

PrintDefaults(depth, path)

  • @param depth (optional int): A value greater than 1 to represent the depth of tables to print. If 1, only the root-level table will be printed. If 2, nested tables of the root-table will also be printed, and so on.
  • @param path (optional string): Used to print a table within the defaults table rather than the whole thing.

A helper method to print the defaults table.

SetProfile(name)

  • @param name (string): The name of the profile to assign to the character.

Sets the addon profile for the currently logged in character. Creates a new profile if the named profile does not exist.

GetProfiles()

  • @return (table): A table containing string profile names for all profiles associated with the addon.

Gets a table of all profile names associated with the addon's database.

IterateProfiles()

Similar to db:GetProfiles() except usable in a for loop to loop through all profiles associated with the addon.

Each loop returns values: id, profileName, profile

  • (int) id: current loop iteration
  • (string) profileName: the name of the profile
  • (table) profile: the profile data

GetNumProfiles()

  • @return (int): The number of profiles associated with the addon.

ResetProfile(name)

  • @param name (string): The name of the profile to reset.

A helper method to reset a profile.

RenameProfile(oldName, newName)

  • @param oldName (string): The old profile name.
  • @param newName (string): The new profile name.

Renames an existing profile to a new profile name. If the new name already exists, it appends a number to avoid clashing: 'example (1)'. This method will trigger the OnProfileChange event, which will trigger any callback associated with this event (see the db:OnProfileChange(callback) documentation above).

RemoveProfile(name)

  • @param name (string): The name of the profile to move to the bin.

Moves the profile to the bin. The profile cannot be accessed from the bin. Use db:RestoreProfile(name) to restore the profile.

RestoreProfile(name)

  • @param name (string): The name of the profile to restore from the bin.

Profiles will remain in the bin until a reload of the UI occurs. If the bin contains a profile, this method can restore it.

GetProfilesInBin()

  • @return (table): An index table containing the names of all profiles in the bin.

Gets all profiles that can be restored from the bin.

GetCurrentProfile()

  • @return (string): The current profile associated with the currently logged in character.

ParsePathValue(path)

  • @param path (string): A string representing the path to traverse in the database to locate a value. The path should start with "global" or "profile".
  • @return (any): The value found at the location specified by the path address. Might return nil if the path address is invalid or no value is located at the specified path address.

Searches a path address and returns the located value if found.

Example:

local value = db:ParsePathValue("global.core.settings[".. moduleName .. "[5]");

SetPathValue(path, value)

  • @param path (string): The path address to indicate where the value should be stored in the database (e.g. "db.profile.table.myValue").
  • @param value (optional any): The value to be stored. This method will replace any existing value, so if the value is nil, then this will remove the existing value.

Adds a value to the database at the specified path address.

Example:

db:SetPathValue("profile.aModule.aSubTable[".. attributeName .."][5]", 123)

AppendOnce(rootObserver, path, appendKey, value)

  • @param rootObserver (Observer): The root database observer (e.g. profile or global, or a nested table/observer) to append the value to, relative to the path address provided.
  • @param path (optional string): The path address to specify where the value should be appended.
  • @param appendKey (optional string): An optional key that can be used instead of the path for registering an appended value inside the appended history table (found in the saved variable table).
  • @param value (table): The table of values to be appended to the database.
  • @return boolean @Returns whether the value was successfully added.

Adds a new value to the saved variable table only once. Adds to a special appended history table.

Example:

The following will inject a "defaultFields" key and table value into the current profile saved variable table only once. If the "defaultFields" key/value is removed, MayronObjects will never reinject it unless the appended key is removed from the appended history table (found in the saved variables table).

db:AppendOnce(db.profile, nil, "defaultFields", { fieldNames = { "Player"; }; fields = { Player = { unitID = "player"; }; }; });

RemoveAppended(path, rootTable, path)

  • @param rootTable (string): The root database table (observer) to append the value to relative to the path address provided.
  • @param path (string): The path address to specify the location of the value that should be removed.
  • @return (boolean): Returns whether the value was successfully removed.

Removes the appended history (i.e., the registry key and appended data).

GetDatabaseName()

  • @return (string): The name of the database

Returns the name of the database, which will be the addon name and the saved variable name joined together: MyAddOn:MY_ADDON_SV

RegisterUpdateFunctions(path, updateFunctions, manualFunc)

  • @param path (string): A database path string, such as myTable.mySubTable[2].
  • @param updateFunctions (table or function): A table containing functions, or a function, to attach to a database path.
  • @param manualFunc (optional function): When TriggerUpdateFunction is called, the manualFunc will be called and is passed the update function to allow the user to decide how it should be called.

Register an update function to be triggered when a database value changes based on its path address. You can also register many update functions by passing a table of update functions reflecting the saved variables table's structure with nested tables.

Example:

db:RegisterUpdateFunctions("profile.myModule", { width = function(newValue) ... end; height = function(newValue) ... end; appearance = { color = function(newValue, path) print(path) -- "db.profile.myModule.appearance.color" end; } }

TriggerUpdateFunction(path)

  • @param fullPath (string): A database path address, such as profile.myTable.mySubTable[2].

Locates the database value found at the path address provided and executes the update function registered with that path address if one exists.

GetUpdateFunctions(path)

  • @param path (string): A database path address, such as myTable.mySubTable[2].
  • @return (table or function): A table containing update functions, or a single update function, associated with the path address.

Returns a table of update functions registered with the corresponding path address.

8

Observer API

Below is the full list of the Observer class method. Observer instance objects are automatically created by the database and make up the in-memory database tree nodes. The db.global and db.profile root-level nodes are both observer instances.

SetParent(parentObserver)

@param parentObserver (Observer): The observer calling the SpetParent method will be assigned the parentObserver as its parent.

This method is used to achieve database inheritance. If an observer cannot find a value, it uses the value found in the parent table. Useful if many separate tables in the saved variables table should use the same set of default values.

It is always recommended to use the prefix __template at the start of an abstract/template database table if using inheritance (i.e., a child observer representing settings to describe how a certain frame will be rendered should inherit from the parent __templateFrame table). By doing this, the database parser will treat tables with a __template key differently for memory performance reasons.

Example:

db.profile.aFrame:SetParent(db.profile.__templateFrame);

GetParent()

  • @return (Observer): Returns the Observer's parent.

HasParent()

  • @return (boolean): Returns true if the current Observer has a parent.

Similar to Observer:GetParent() except it returns a boolean result.

GetDatabase()

  • @return (Database): The database object associated with the observer.

A helper method to get database reference in case it is hard to access.

GetSavedVariable()

  • @return (table or nil): The underlining saved variables table. If not in the saved variable as the observer only contains default values or parent values (for example), nil will be returned.

Gets the underlining saved variables table associated with the observer. Default and parent values are not included in the saved variables table.

GetDefaults()

  • @return (table or nil): The default table attached to the database observer if one exists, else nil will be returned.

Gets the default database table associated with the observer. Real saved variable and parent values will not be included in this!

GetUntrackedTable()

  • @return (table): A table containing cloned values from the associated saved variables table, parent table, and defaults table.

Returns a copy table containing all values from the underlining saved variables table, parent table, and defaults table. Changing this table will not affect the saved variables table! This copied table should be for read-only use-cases and can improve performance if the table is accessed very frequently.

Example:

-- settings is now disconnected from the database. It is no longer an Observer! local settings = db.profile.aModule:GetUntrackedTable();

The non-observer, untracked table returned comes with a few additional helper methods:

  • tbl:GetTrackedTable() - Converts the untracked table to a tracked, savable, table that track changes to be saved at a later date (see documentation on Observer:GetTrackedTable()).
  • tbl:GetObserver() - Gets the observer originally used to create the untracked table.
  • tbl:Refresh() - Updates all data in the table to reflect the current data found in the database to keep it in sync.

GetTrackedTable()

  • @return (table): A tracking table containing all merged values and some helper methods.

Returns a table containing all values from the underlining saved variables table, parent table, and defaults table and tracks all changes but does not apply them until tbl:SaveChanges() is called.

The non-observer, tracked table returned also comes with additional methods:

  • tbl:ResetChanges() - Resets any pending changes so that calling tbl:SaveChanges() will not apply anything.
  • tbl:GetUntrackedTable() - Converts the tracked table to a standard, read-only, table that does not track changes.
  • tbl:GetObserver() - Gets the observer originally used to create the tracked table.
  • tbl:GetTotalPendingChanges() - Returns the total nubmer of changes pending to be saved to the database.
  • tbl:SaveChanges() - Saves all pending changes to the database, after which the call to GetTotalPendingChanges will be 0.
  • tbl:Iterate() - Iterates through all values in the table (using the underlining untracked table, so any changes made to an iterated value will not be saved/added to the change history).
  • tbl:Refresh() - Updates all data in the table to reflect the current data found in the database to keep it in sync.

Example:

-- settings is now disconnected from the database. It is no longer an Observer! -- However, you can save changes made, which will be written to the database. local settings = db.profile.aModule:GetTrackedTable(); settings.newValue = 5; print(settings:GetTotalPendingChanges()) -- prints 1 settings:SaveChanges(); -- save to database print(settings:GetTotalPendingChanges()) -- prints 0 settings.newValue = 10; print(settings:GetTotalPendingChanges()) -- prints 1 settings:ResetChanges(); -- remove tracked history to avoid saving to the database print(settings:GetTotalPendingChanges()) -- prints 0

Iterate()

Usable in a for loop. Uses the merged table to iterate through key and value pairs of the default and saved variable table paired together using the Observer path address.

for key, value in db.profile.aModule:Iterate() do print(string.format("%s : %s", key, value)) end

GetLength()

  • @return (int): The length of the merged table (Observer:GetTable()).

Remove()

Used to remove a table in the saved variable database and clean the database. Cannot be used to remove any other value type!

Example:

db.global.deleteMe:Remove()

Print(depth)

  • @param depth (optional int): The depth of tables to print before only printing table references.

A helper function to print all contents of a table pointed to by the selected Observer.

Example:

-- prints all values found in aModule, and also prints the contents of tables inside aModule but no further as we are specified recursion using a depth of 2: db.profile.aModule:Print(2)
back Back to Downloads

© 2021 MayronUI.com, All rights reserved.