Mercurial > wow > hansgar_and_franzok_assist

annotate Libs/AceDB-3.0/AceDB-3.0.lua @ 23:52973d00a183

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
- framework update.
author Tercio
date Tue, 08 Sep 2015 13:23:31 -0300
parents
children dbf04157d63e
rev   line source
Tercio@23 1 --- **AceDB-3.0** manages the SavedVariables of your addon.
Tercio@23 2 -- It offers profile management, smart defaults and namespaces for modules.\\
Tercio@23 3 -- Data can be saved in different data-types, depending on its intended usage.
Tercio@23 4 -- The most common data-type is the `profile` type, which allows the user to choose
Tercio@23 5 -- the active profile, and manage the profiles of all of his characters.\\
Tercio@23 6 -- The following data types are available:
Tercio@23 7 -- * **char** Character-specific data. Every character has its own database.
Tercio@23 8 -- * **realm** Realm-specific data. All of the players characters on the same realm share this database.
Tercio@23 9 -- * **class** Class-specific data. All of the players characters of the same class share this database.
Tercio@23 10 -- * **race** Race-specific data. All of the players characters of the same race share this database.
Tercio@23 11 -- * **faction** Faction-specific data. All of the players characters of the same faction share this database.
Tercio@23 12 -- * **factionrealm** Faction and realm specific data. All of the players characters on the same realm and of the same faction share this database.
Tercio@23 13 -- * **global** Global Data. All characters on the same account share this database.
Tercio@23 14 -- * **profile** Profile-specific data. All characters using the same profile share this database. The user can control which profile should be used.
Tercio@23 15 --
Tercio@23 16 -- Creating a new Database using the `:New` function will return a new DBObject. A database will inherit all functions
Tercio@23 17 -- of the DBObjectLib listed here. \\
Tercio@23 18 -- If you create a new namespaced child-database (`:RegisterNamespace`), you'll get a DBObject as well, but note
Tercio@23 19 -- that the child-databases cannot individually change their profile, and are linked to their parents profile - and because of that,
Tercio@23 20 -- the profile related APIs are not available. Only `:RegisterDefaults` and `:ResetProfile` are available on child-databases.
Tercio@23 21 --
Tercio@23 22 -- For more details on how to use AceDB-3.0, see the [[AceDB-3.0 Tutorial]].
Tercio@23 23 --
Tercio@23 24 -- You may also be interested in [[libdualspec-1-0|LibDualSpec-1.0]] to do profile switching automatically when switching specs.
Tercio@23 25 --
Tercio@23 26 -- @usage
Tercio@23 27 -- MyAddon = LibStub("AceAddon-3.0"):NewAddon("DBExample")
Tercio@23 28 --
Tercio@23 29 -- -- declare defaults to be used in the DB
Tercio@23 30 -- local defaults = {
Tercio@23 31 -- profile = {
Tercio@23 32 -- setting = true,
Tercio@23 33 -- }
Tercio@23 34 -- }
Tercio@23 35 --
Tercio@23 36 -- function MyAddon:OnInitialize()
Tercio@23 37 -- -- Assuming the .toc says ## SavedVariables: MyAddonDB
Tercio@23 38 -- self.db = LibStub("AceDB-3.0"):New("MyAddonDB", defaults, true)
Tercio@23 39 -- end
Tercio@23 40 -- @class file
Tercio@23 41 -- @name AceDB-3.0.lua
Tercio@23 42 -- @release $Id: AceDB-3.0.lua 1124 2014-10-27 21:00:07Z funkydude $
Tercio@23 43 local ACEDB_MAJOR, ACEDB_MINOR = "AceDB-3.0", 26
Tercio@23 44 local AceDB, oldminor = LibStub:NewLibrary(ACEDB_MAJOR, ACEDB_MINOR)
Tercio@23 45
Tercio@23 46 if not AceDB then return end -- No upgrade needed
Tercio@23 47
Tercio@23 48 -- Lua APIs
Tercio@23 49 local type, pairs, next, error = type, pairs, next, error
Tercio@23 50 local setmetatable, getmetatable, rawset, rawget = setmetatable, getmetatable, rawset, rawget
Tercio@23 51
Tercio@23 52 -- WoW APIs
Tercio@23 53 local _G = _G
Tercio@23 54
Tercio@23 55 -- Global vars/functions that we don't upvalue since they might get hooked, or upgraded
Tercio@23 56 -- List them here for Mikk's FindGlobals script
Tercio@23 57 -- GLOBALS: LibStub
Tercio@23 58
Tercio@23 59 AceDB.db_registry = AceDB.db_registry or {}
Tercio@23 60 AceDB.frame = AceDB.frame or CreateFrame("Frame")
Tercio@23 61
Tercio@23 62 local CallbackHandler
Tercio@23 63 local CallbackDummy = { Fire = function() end }
Tercio@23 64
Tercio@23 65 local DBObjectLib = {}
Tercio@23 66
Tercio@23 67 --[[-------------------------------------------------------------------------
Tercio@23 68 AceDB Utility Functions
Tercio@23 69 ---------------------------------------------------------------------------]]
Tercio@23 70
Tercio@23 71 -- Simple shallow copy for copying defaults
Tercio@23 72 local function copyTable(src, dest)
Tercio@23 73 if type(dest) ~= "table" then dest = {} end
Tercio@23 74 if type(src) == "table" then
Tercio@23 75 for k,v in pairs(src) do
Tercio@23 76 if type(v) == "table" then
Tercio@23 77 -- try to index the key first so that the metatable creates the defaults, if set, and use that table
Tercio@23 78 v = copyTable(v, dest[k])
Tercio@23 79 end
Tercio@23 80 dest[k] = v
Tercio@23 81 end
Tercio@23 82 end
Tercio@23 83 return dest
Tercio@23 84 end
Tercio@23 85
Tercio@23 86 -- Called to add defaults to a section of the database
Tercio@23 87 --
Tercio@23 88 -- When a ["*"] default section is indexed with a new key, a table is returned
Tercio@23 89 -- and set in the host table. These tables must be cleaned up by removeDefaults
Tercio@23 90 -- in order to ensure we don't write empty default tables.
Tercio@23 91 local function copyDefaults(dest, src)
Tercio@23 92 -- this happens if some value in the SV overwrites our default value with a non-table
Tercio@23 93 --if type(dest) ~= "table" then return end
Tercio@23 94 for k, v in pairs(src) do
Tercio@23 95 if k == "*" or k == "**" then
Tercio@23 96 if type(v) == "table" then
Tercio@23 97 -- This is a metatable used for table defaults
Tercio@23 98 local mt = {
Tercio@23 99 -- This handles the lookup and creation of new subtables
Tercio@23 100 __index = function(t,k)
Tercio@23 101 if k == nil then return nil end
Tercio@23 102 local tbl = {}
Tercio@23 103 copyDefaults(tbl, v)
Tercio@23 104 rawset(t, k, tbl)
Tercio@23 105 return tbl
Tercio@23 106 end,
Tercio@23 107 }
Tercio@23 108 setmetatable(dest, mt)
Tercio@23 109 -- handle already existing tables in the SV
Tercio@23 110 for dk, dv in pairs(dest) do
Tercio@23 111 if not rawget(src, dk) and type(dv) == "table" then
Tercio@23 112 copyDefaults(dv, v)
Tercio@23 113 end
Tercio@23 114 end
Tercio@23 115 else
Tercio@23 116 -- Values are not tables, so this is just a simple return
Tercio@23 117 local mt = {__index = function(t,k) return k~=nil and v or nil end}
Tercio@23 118 setmetatable(dest, mt)
Tercio@23 119 end
Tercio@23 120 elseif type(v) == "table" then
Tercio@23 121 if not rawget(dest, k) then rawset(dest, k, {}) end
Tercio@23 122 if type(dest[k]) == "table" then
Tercio@23 123 copyDefaults(dest[k], v)
Tercio@23 124 if src['**'] then
Tercio@23 125 copyDefaults(dest[k], src['**'])
Tercio@23 126 end
Tercio@23 127 end
Tercio@23 128 else
Tercio@23 129 if rawget(dest, k) == nil then
Tercio@23 130 rawset(dest, k, v)
Tercio@23 131 end
Tercio@23 132 end
Tercio@23 133 end
Tercio@23 134 end
Tercio@23 135
Tercio@23 136 -- Called to remove all defaults in the default table from the database
Tercio@23 137 local function removeDefaults(db, defaults, blocker)
Tercio@23 138 -- remove all metatables from the db, so we don't accidentally create new sub-tables through them
Tercio@23 139 setmetatable(db, nil)
Tercio@23 140 -- loop through the defaults and remove their content
Tercio@23 141 for k,v in pairs(defaults) do
Tercio@23 142 if k == "*" or k == "**" then
Tercio@23 143 if type(v) == "table" then
Tercio@23 144 -- Loop through all the actual k,v pairs and remove
Tercio@23 145 for key, value in pairs(db) do
Tercio@23 146 if type(value) == "table" then
Tercio@23 147 -- if the key was not explicitly specified in the defaults table, just strip everything from * and ** tables
Tercio@23 148 if defaults[key] == nil and (not blocker or blocker[key] == nil) then
Tercio@23 149 removeDefaults(value, v)
Tercio@23 150 -- if the table is empty afterwards, remove it
Tercio@23 151 if next(value) == nil then
Tercio@23 152 db[key] = nil
Tercio@23 153 end
Tercio@23 154 -- if it was specified, only strip ** content, but block values which were set in the key table
Tercio@23 155 elseif k == "**" then
Tercio@23 156 removeDefaults(value, v, defaults[key])
Tercio@23 157 end
Tercio@23 158 end
Tercio@23 159 end
Tercio@23 160 elseif k == "*" then
Tercio@23 161 -- check for non-table default
Tercio@23 162 for key, value in pairs(db) do
Tercio@23 163 if defaults[key] == nil and v == value then
Tercio@23 164 db[key] = nil
Tercio@23 165 end
Tercio@23 166 end
Tercio@23 167 end
Tercio@23 168 elseif type(v) == "table" and type(db[k]) == "table" then
Tercio@23 169 -- if a blocker was set, dive into it, to allow multi-level defaults
Tercio@23 170 removeDefaults(db[k], v, blocker and blocker[k])
Tercio@23 171 if next(db[k]) == nil then
Tercio@23 172 db[k] = nil
Tercio@23 173 end
Tercio@23 174 else
Tercio@23 175 -- check if the current value matches the default, and that its not blocked by another defaults table
Tercio@23 176 if db[k] == defaults[k] and (not blocker or blocker[k] == nil) then
Tercio@23 177 db[k] = nil
Tercio@23 178 end
Tercio@23 179 end
Tercio@23 180 end
Tercio@23 181 end
Tercio@23 182
Tercio@23 183 -- This is called when a table section is first accessed, to set up the defaults
Tercio@23 184 local function initSection(db, section, svstore, key, defaults)
Tercio@23 185 local sv = rawget(db, "sv")
Tercio@23 186
Tercio@23 187 local tableCreated
Tercio@23 188 if not sv[svstore] then sv[svstore] = {} end
Tercio@23 189 if not sv[svstore][key] then
Tercio@23 190 sv[svstore][key] = {}
Tercio@23 191 tableCreated = true
Tercio@23 192 end
Tercio@23 193
Tercio@23 194 local tbl = sv[svstore][key]
Tercio@23 195
Tercio@23 196 if defaults then
Tercio@23 197 copyDefaults(tbl, defaults)
Tercio@23 198 end
Tercio@23 199 rawset(db, section, tbl)
Tercio@23 200
Tercio@23 201 return tableCreated, tbl
Tercio@23 202 end
Tercio@23 203
Tercio@23 204 -- Metatable to handle the dynamic creation of sections and copying of sections.
Tercio@23 205 local dbmt = {
Tercio@23 206 __index = function(t, section)
Tercio@23 207 local keys = rawget(t, "keys")
Tercio@23 208 local key = keys[section]
Tercio@23 209 if key then
Tercio@23 210 local defaultTbl = rawget(t, "defaults")
Tercio@23 211 local defaults = defaultTbl and defaultTbl[section]
Tercio@23 212
Tercio@23 213 if section == "profile" then
Tercio@23 214 local new = initSection(t, section, "profiles", key, defaults)
Tercio@23 215 if new then
Tercio@23 216 -- Callback: OnNewProfile, database, newProfileKey
Tercio@23 217 t.callbacks:Fire("OnNewProfile", t, key)
Tercio@23 218 end
Tercio@23 219 elseif section == "profiles" then
Tercio@23 220 local sv = rawget(t, "sv")
Tercio@23 221 if not sv.profiles then sv.profiles = {} end
Tercio@23 222 rawset(t, "profiles", sv.profiles)
Tercio@23 223 elseif section == "global" then
Tercio@23 224 local sv = rawget(t, "sv")
Tercio@23 225 if not sv.global then sv.global = {} end
Tercio@23 226 if defaults then
Tercio@23 227 copyDefaults(sv.global, defaults)
Tercio@23 228 end
Tercio@23 229 rawset(t, section, sv.global)
Tercio@23 230 else
Tercio@23 231 initSection(t, section, section, key, defaults)
Tercio@23 232 end
Tercio@23 233 end
Tercio@23 234
Tercio@23 235 return rawget(t, section)
Tercio@23 236 end
Tercio@23 237 }
Tercio@23 238
Tercio@23 239 local function validateDefaults(defaults, keyTbl, offset)
Tercio@23 240 if not defaults then return end
Tercio@23 241 offset = offset or 0
Tercio@23 242 for k in pairs(defaults) do
Tercio@23 243 if not keyTbl[k] or k == "profiles" then
Tercio@23 244 error(("Usage: AceDBObject:RegisterDefaults(defaults): '%s' is not a valid datatype."):format(k), 3 + offset)
Tercio@23 245 end
Tercio@23 246 end
Tercio@23 247 end
Tercio@23 248
Tercio@23 249 local preserve_keys = {
Tercio@23 250 ["callbacks"] = true,
Tercio@23 251 ["RegisterCallback"] = true,
Tercio@23 252 ["UnregisterCallback"] = true,
Tercio@23 253 ["UnregisterAllCallbacks"] = true,
Tercio@23 254 ["children"] = true,
Tercio@23 255 }
Tercio@23 256
Tercio@23 257 local realmKey = GetRealmName()
Tercio@23 258 local charKey = UnitName("player") .. " - " .. realmKey
Tercio@23 259 local _, classKey = UnitClass("player")
Tercio@23 260 local _, raceKey = UnitRace("player")
Tercio@23 261 local factionKey = UnitFactionGroup("player")
Tercio@23 262 local factionrealmKey = factionKey .. " - " .. realmKey
Tercio@23 263 local localeKey = GetLocale():lower()
Tercio@23 264
Tercio@23 265 local regionTable = { "US", "KR", "EU", "TW", "CN" }
Tercio@23 266 local regionKey = regionTable[GetCurrentRegion()]
Tercio@23 267 local factionrealmregionKey = factionrealmKey .. " - " .. regionKey
Tercio@23 268
Tercio@23 269 -- Actual database initialization function
Tercio@23 270 local function initdb(sv, defaults, defaultProfile, olddb, parent)
Tercio@23 271 -- Generate the database keys for each section
Tercio@23 272
Tercio@23 273 -- map "true" to our "Default" profile
Tercio@23 274 if defaultProfile == true then defaultProfile = "Default" end
Tercio@23 275
Tercio@23 276 local profileKey
Tercio@23 277 if not parent then
Tercio@23 278 -- Make a container for profile keys
Tercio@23 279 if not sv.profileKeys then sv.profileKeys = {} end
Tercio@23 280
Tercio@23 281 -- Try to get the profile selected from the char db
Tercio@23 282 profileKey = sv.profileKeys[charKey] or defaultProfile or charKey
Tercio@23 283
Tercio@23 284 -- save the selected profile for later
Tercio@23 285 sv.profileKeys[charKey] = profileKey
Tercio@23 286 else
Tercio@23 287 -- Use the profile of the parents DB
Tercio@23 288 profileKey = parent.keys.profile or defaultProfile or charKey
Tercio@23 289
Tercio@23 290 -- clear the profileKeys in the DB, namespaces don't need to store them
Tercio@23 291 sv.profileKeys = nil
Tercio@23 292 end
Tercio@23 293
Tercio@23 294 -- This table contains keys that enable the dynamic creation
Tercio@23 295 -- of each section of the table. The 'global' and 'profiles'
Tercio@23 296 -- have a key of true, since they are handled in a special case
Tercio@23 297 local keyTbl= {
Tercio@23 298 ["char"] = charKey,
Tercio@23 299 ["realm"] = realmKey,
Tercio@23 300 ["class"] = classKey,
Tercio@23 301 ["race"] = raceKey,
Tercio@23 302 ["faction"] = factionKey,
Tercio@23 303 ["factionrealm"] = factionrealmKey,
Tercio@23 304 ["factionrealmregion"] = factionrealmregionKey,
Tercio@23 305 ["profile"] = profileKey,
Tercio@23 306 ["locale"] = localeKey,
Tercio@23 307 ["global"] = true,
Tercio@23 308 ["profiles"] = true,
Tercio@23 309 }
Tercio@23 310
Tercio@23 311 validateDefaults(defaults, keyTbl, 1)
Tercio@23 312
Tercio@23 313 -- This allows us to use this function to reset an entire database
Tercio@23 314 -- Clear out the old database
Tercio@23 315 if olddb then
Tercio@23 316 for k,v in pairs(olddb) do if not preserve_keys[k] then olddb[k] = nil end end
Tercio@23 317 end
Tercio@23 318
Tercio@23 319 -- Give this database the metatable so it initializes dynamically
Tercio@23 320 local db = setmetatable(olddb or {}, dbmt)
Tercio@23 321
Tercio@23 322 if not rawget(db, "callbacks") then
Tercio@23 323 -- try to load CallbackHandler-1.0 if it loaded after our library
Tercio@23 324 if not CallbackHandler then CallbackHandler = LibStub:GetLibrary("CallbackHandler-1.0", true) end
Tercio@23 325 db.callbacks = CallbackHandler and CallbackHandler:New(db) or CallbackDummy
Tercio@23 326 end
Tercio@23 327
Tercio@23 328 -- Copy methods locally into the database object, to avoid hitting
Tercio@23 329 -- the metatable when calling methods
Tercio@23 330
Tercio@23 331 if not parent then
Tercio@23 332 for name, func in pairs(DBObjectLib) do
Tercio@23 333 db[name] = func
Tercio@23 334 end
Tercio@23 335 else
Tercio@23 336 -- hack this one in
Tercio@23 337 db.RegisterDefaults = DBObjectLib.RegisterDefaults
Tercio@23 338 db.ResetProfile = DBObjectLib.ResetProfile
Tercio@23 339 end
Tercio@23 340
Tercio@23 341 -- Set some properties in the database object
Tercio@23 342 db.profiles = sv.profiles
Tercio@23 343 db.keys = keyTbl
Tercio@23 344 db.sv = sv
Tercio@23 345 --db.sv_name = name
Tercio@23 346 db.defaults = defaults
Tercio@23 347 db.parent = parent
Tercio@23 348
Tercio@23 349 -- store the DB in the registry
Tercio@23 350 AceDB.db_registry[db] = true
Tercio@23 351
Tercio@23 352 return db
Tercio@23 353 end
Tercio@23 354
Tercio@23 355 -- handle PLAYER_LOGOUT
Tercio@23 356 -- strip all defaults from all databases
Tercio@23 357 -- and cleans up empty sections
Tercio@23 358 local function logoutHandler(frame, event)
Tercio@23 359 if event == "PLAYER_LOGOUT" then
Tercio@23 360 for db in pairs(AceDB.db_registry) do
Tercio@23 361 db.callbacks:Fire("OnDatabaseShutdown", db)
Tercio@23 362 db:RegisterDefaults(nil)
Tercio@23 363
Tercio@23 364 -- cleanup sections that are empty without defaults
Tercio@23 365 local sv = rawget(db, "sv")
Tercio@23 366 for section in pairs(db.keys) do
Tercio@23 367 if rawget(sv, section) then
Tercio@23 368 -- global is special, all other sections have sub-entrys
Tercio@23 369 -- also don't delete empty profiles on main dbs, only on namespaces
Tercio@23 370 if section ~= "global" and (section ~= "profiles" or rawget(db, "parent")) then
Tercio@23 371 for key in pairs(sv[section]) do
Tercio@23 372 if not next(sv[section][key]) then
Tercio@23 373 sv[section][key] = nil
Tercio@23 374 end
Tercio@23 375 end
Tercio@23 376 end
Tercio@23 377 if not next(sv[section]) then
Tercio@23 378 sv[section] = nil
Tercio@23 379 end
Tercio@23 380 end
Tercio@23 381 end
Tercio@23 382 end
Tercio@23 383 end
Tercio@23 384 end
Tercio@23 385
Tercio@23 386 AceDB.frame:RegisterEvent("PLAYER_LOGOUT")
Tercio@23 387 AceDB.frame:SetScript("OnEvent", logoutHandler)
Tercio@23 388
Tercio@23 389
Tercio@23 390 --[[-------------------------------------------------------------------------
Tercio@23 391 AceDB Object Method Definitions
Tercio@23 392 ---------------------------------------------------------------------------]]
Tercio@23 393
Tercio@23 394 --- Sets the defaults table for the given database object by clearing any
Tercio@23 395 -- that are currently set, and then setting the new defaults.
Tercio@23 396 -- @param defaults A table of defaults for this database
Tercio@23 397 function DBObjectLib:RegisterDefaults(defaults)
Tercio@23 398 if defaults and type(defaults) ~= "table" then
Tercio@23 399 error("Usage: AceDBObject:RegisterDefaults(defaults): 'defaults' - table or nil expected.", 2)
Tercio@23 400 end
Tercio@23 401
Tercio@23 402 validateDefaults(defaults, self.keys)
Tercio@23 403
Tercio@23 404 -- Remove any currently set defaults
Tercio@23 405 if self.defaults then
Tercio@23 406 for section,key in pairs(self.keys) do
Tercio@23 407 if self.defaults[section] and rawget(self, section) then
Tercio@23 408 removeDefaults(self[section], self.defaults[section])
Tercio@23 409 end
Tercio@23 410 end
Tercio@23 411 end
Tercio@23 412
Tercio@23 413 -- Set the DBObject.defaults table
Tercio@23 414 self.defaults = defaults
Tercio@23 415
Tercio@23 416 -- Copy in any defaults, only touching those sections already created
Tercio@23 417 if defaults then
Tercio@23 418 for section,key in pairs(self.keys) do
Tercio@23 419 if defaults[section] and rawget(self, section) then
Tercio@23 420 copyDefaults(self[section], defaults[section])
Tercio@23 421 end
Tercio@23 422 end
Tercio@23 423 end
Tercio@23 424 end
Tercio@23 425
Tercio@23 426 --- Changes the profile of the database and all of it's namespaces to the
Tercio@23 427 -- supplied named profile
Tercio@23 428 -- @param name The name of the profile to set as the current profile
Tercio@23 429 function DBObjectLib:SetProfile(name)
Tercio@23 430 if type(name) ~= "string" then
Tercio@23 431 error("Usage: AceDBObject:SetProfile(name): 'name' - string expected.", 2)
Tercio@23 432 end
Tercio@23 433
Tercio@23 434 -- changing to the same profile, dont do anything
Tercio@23 435 if name == self.keys.profile then return end
Tercio@23 436
Tercio@23 437 local oldProfile = self.profile
Tercio@23 438 local defaults = self.defaults and self.defaults.profile
Tercio@23 439
Tercio@23 440 -- Callback: OnProfileShutdown, database
Tercio@23 441 self.callbacks:Fire("OnProfileShutdown", self)
Tercio@23 442
Tercio@23 443 if oldProfile and defaults then
Tercio@23 444 -- Remove the defaults from the old profile
Tercio@23 445 removeDefaults(oldProfile, defaults)
Tercio@23 446 end
Tercio@23 447
Tercio@23 448 self.profile = nil
Tercio@23 449 self.keys["profile"] = name
Tercio@23 450
Tercio@23 451 -- if the storage exists, save the new profile
Tercio@23 452 -- this won't exist on namespaces.
Tercio@23 453 if self.sv.profileKeys then
Tercio@23 454 self.sv.profileKeys[charKey] = name
Tercio@23 455 end
Tercio@23 456
Tercio@23 457 -- populate to child namespaces
Tercio@23 458 if self.children then
Tercio@23 459 for _, db in pairs(self.children) do
Tercio@23 460 DBObjectLib.SetProfile(db, name)
Tercio@23 461 end
Tercio@23 462 end
Tercio@23 463
Tercio@23 464 -- Callback: OnProfileChanged, database, newProfileKey
Tercio@23 465 self.callbacks:Fire("OnProfileChanged", self, name)
Tercio@23 466 end
Tercio@23 467
Tercio@23 468 --- Returns a table with the names of the existing profiles in the database.
Tercio@23 469 -- You can optionally supply a table to re-use for this purpose.
Tercio@23 470 -- @param tbl A table to store the profile names in (optional)
Tercio@23 471 function DBObjectLib:GetProfiles(tbl)
Tercio@23 472 if tbl and type(tbl) ~= "table" then
Tercio@23 473 error("Usage: AceDBObject:GetProfiles(tbl): 'tbl' - table or nil expected.", 2)
Tercio@23 474 end
Tercio@23 475
Tercio@23 476 -- Clear the container table
Tercio@23 477 if tbl then
Tercio@23 478 for k,v in pairs(tbl) do tbl[k] = nil end
Tercio@23 479 else
Tercio@23 480 tbl = {}
Tercio@23 481 end
Tercio@23 482
Tercio@23 483 local curProfile = self.keys.profile
Tercio@23 484
Tercio@23 485 local i = 0
Tercio@23 486 for profileKey in pairs(self.profiles) do
Tercio@23 487 i = i + 1
Tercio@23 488 tbl[i] = profileKey
Tercio@23 489 if curProfile and profileKey == curProfile then curProfile = nil end
Tercio@23 490 end
Tercio@23 491
Tercio@23 492 -- Add the current profile, if it hasn't been created yet
Tercio@23 493 if curProfile then
Tercio@23 494 i = i + 1
Tercio@23 495 tbl[i] = curProfile
Tercio@23 496 end
Tercio@23 497
Tercio@23 498 return tbl, i
Tercio@23 499 end
Tercio@23 500
Tercio@23 501 --- Returns the current profile name used by the database
Tercio@23 502 function DBObjectLib:GetCurrentProfile()
Tercio@23 503 return self.keys.profile
Tercio@23 504 end
Tercio@23 505
Tercio@23 506 --- Deletes a named profile. This profile must not be the active profile.
Tercio@23 507 -- @param name The name of the profile to be deleted
Tercio@23 508 -- @param silent If true, do not raise an error when the profile does not exist
Tercio@23 509 function DBObjectLib:DeleteProfile(name, silent)
Tercio@23 510 if type(name) ~= "string" then
Tercio@23 511 error("Usage: AceDBObject:DeleteProfile(name): 'name' - string expected.", 2)
Tercio@23 512 end
Tercio@23 513
Tercio@23 514 if self.keys.profile == name then
Tercio@23 515 error("Cannot delete the active profile in an AceDBObject.", 2)
Tercio@23 516 end
Tercio@23 517
Tercio@23 518 if not rawget(self.profiles, name) and not silent then
Tercio@23 519 error("Cannot delete profile '" .. name .. "'. It does not exist.", 2)
Tercio@23 520 end
Tercio@23 521
Tercio@23 522 self.profiles[name] = nil
Tercio@23 523
Tercio@23 524 -- populate to child namespaces
Tercio@23 525 if self.children then
Tercio@23 526 for _, db in pairs(self.children) do
Tercio@23 527 DBObjectLib.DeleteProfile(db, name, true)
Tercio@23 528 end
Tercio@23 529 end
Tercio@23 530
Tercio@23 531 -- switch all characters that use this profile back to the default
Tercio@23 532 if self.sv.profileKeys then
Tercio@23 533 for key, profile in pairs(self.sv.profileKeys) do
Tercio@23 534 if profile == name then
Tercio@23 535 self.sv.profileKeys[key] = nil
Tercio@23 536 end
Tercio@23 537 end
Tercio@23 538 end
Tercio@23 539
Tercio@23 540 -- Callback: OnProfileDeleted, database, profileKey
Tercio@23 541 self.callbacks:Fire("OnProfileDeleted", self, name)
Tercio@23 542 end
Tercio@23 543
Tercio@23 544 --- Copies a named profile into the current profile, overwriting any conflicting
Tercio@23 545 -- settings.
Tercio@23 546 -- @param name The name of the profile to be copied into the current profile
Tercio@23 547 -- @param silent If true, do not raise an error when the profile does not exist
Tercio@23 548 function DBObjectLib:CopyProfile(name, silent)
Tercio@23 549 if type(name) ~= "string" then
Tercio@23 550 error("Usage: AceDBObject:CopyProfile(name): 'name' - string expected.", 2)
Tercio@23 551 end
Tercio@23 552
Tercio@23 553 if name == self.keys.profile then
Tercio@23 554 error("Cannot have the same source and destination profiles.", 2)
Tercio@23 555 end
Tercio@23 556
Tercio@23 557 if not rawget(self.profiles, name) and not silent then
Tercio@23 558 error("Cannot copy profile '" .. name .. "'. It does not exist.", 2)
Tercio@23 559 end
Tercio@23 560
Tercio@23 561 -- Reset the profile before copying
Tercio@23 562 DBObjectLib.ResetProfile(self, nil, true)
Tercio@23 563
Tercio@23 564 local profile = self.profile
Tercio@23 565 local source = self.profiles[name]
Tercio@23 566
Tercio@23 567 copyTable(source, profile)
Tercio@23 568
Tercio@23 569 -- populate to child namespaces
Tercio@23 570 if self.children then
Tercio@23 571 for _, db in pairs(self.children) do
Tercio@23 572 DBObjectLib.CopyProfile(db, name, true)
Tercio@23 573 end
Tercio@23 574 end
Tercio@23 575
Tercio@23 576 -- Callback: OnProfileCopied, database, sourceProfileKey
Tercio@23 577 self.callbacks:Fire("OnProfileCopied", self, name)
Tercio@23 578 end
Tercio@23 579
Tercio@23 580 --- Resets the current profile to the default values (if specified).
Tercio@23 581 -- @param noChildren if set to true, the reset will not be populated to the child namespaces of this DB object
Tercio@23 582 -- @param noCallbacks if set to true, won't fire the OnProfileReset callback
Tercio@23 583 function DBObjectLib:ResetProfile(noChildren, noCallbacks)
Tercio@23 584 local profile = self.profile
Tercio@23 585
Tercio@23 586 for k,v in pairs(profile) do
Tercio@23 587 profile[k] = nil
Tercio@23 588 end
Tercio@23 589
Tercio@23 590 local defaults = self.defaults and self.defaults.profile
Tercio@23 591 if defaults then
Tercio@23 592 copyDefaults(profile, defaults)
Tercio@23 593 end
Tercio@23 594
Tercio@23 595 -- populate to child namespaces
Tercio@23 596 if self.children and not noChildren then
Tercio@23 597 for _, db in pairs(self.children) do
Tercio@23 598 DBObjectLib.ResetProfile(db, nil, noCallbacks)
Tercio@23 599 end
Tercio@23 600 end
Tercio@23 601
Tercio@23 602 -- Callback: OnProfileReset, database
Tercio@23 603 if not noCallbacks then
Tercio@23 604 self.callbacks:Fire("OnProfileReset", self)
Tercio@23 605 end
Tercio@23 606 end
Tercio@23 607
Tercio@23 608 --- Resets the entire database, using the string defaultProfile as the new default
Tercio@23 609 -- profile.
Tercio@23 610 -- @param defaultProfile The profile name to use as the default
Tercio@23 611 function DBObjectLib:ResetDB(defaultProfile)
Tercio@23 612 if defaultProfile and type(defaultProfile) ~= "string" then
Tercio@23 613 error("Usage: AceDBObject:ResetDB(defaultProfile): 'defaultProfile' - string or nil expected.", 2)
Tercio@23 614 end
Tercio@23 615
Tercio@23 616 local sv = self.sv
Tercio@23 617 for k,v in pairs(sv) do
Tercio@23 618 sv[k] = nil
Tercio@23 619 end
Tercio@23 620
Tercio@23 621 local parent = self.parent
Tercio@23 622
Tercio@23 623 initdb(sv, self.defaults, defaultProfile, self)
Tercio@23 624
Tercio@23 625 -- fix the child namespaces
Tercio@23 626 if self.children then
Tercio@23 627 if not sv.namespaces then sv.namespaces = {} end
Tercio@23 628 for name, db in pairs(self.children) do
Tercio@23 629 if not sv.namespaces[name] then sv.namespaces[name] = {} end
Tercio@23 630 initdb(sv.namespaces[name], db.defaults, self.keys.profile, db, self)
Tercio@23 631 end
Tercio@23 632 end
Tercio@23 633
Tercio@23 634 -- Callback: OnDatabaseReset, database
Tercio@23 635 self.callbacks:Fire("OnDatabaseReset", self)
Tercio@23 636 -- Callback: OnProfileChanged, database, profileKey
Tercio@23 637 self.callbacks:Fire("OnProfileChanged", self, self.keys["profile"])
Tercio@23 638
Tercio@23 639 return self
Tercio@23 640 end
Tercio@23 641
Tercio@23 642 --- Creates a new database namespace, directly tied to the database. This
Tercio@23 643 -- is a full scale database in it's own rights other than the fact that
Tercio@23 644 -- it cannot control its profile individually
Tercio@23 645 -- @param name The name of the new namespace
Tercio@23 646 -- @param defaults A table of values to use as defaults
Tercio@23 647 function DBObjectLib:RegisterNamespace(name, defaults)
Tercio@23 648 if type(name) ~= "string" then
Tercio@23 649 error("Usage: AceDBObject:RegisterNamespace(name, defaults): 'name' - string expected.", 2)
Tercio@23 650 end
Tercio@23 651 if defaults and type(defaults) ~= "table" then
Tercio@23 652 error("Usage: AceDBObject:RegisterNamespace(name, defaults): 'defaults' - table or nil expected.", 2)
Tercio@23 653 end
Tercio@23 654 if self.children and self.children[name] then
Tercio@23 655 error ("Usage: AceDBObject:RegisterNamespace(name, defaults): 'name' - a namespace with that name already exists.", 2)
Tercio@23 656 end
Tercio@23 657
Tercio@23 658 local sv = self.sv
Tercio@23 659 if not sv.namespaces then sv.namespaces = {} end
Tercio@23 660 if not sv.namespaces[name] then
Tercio@23 661 sv.namespaces[name] = {}
Tercio@23 662 end
Tercio@23 663
Tercio@23 664 local newDB = initdb(sv.namespaces[name], defaults, self.keys.profile, nil, self)
Tercio@23 665
Tercio@23 666 if not self.children then self.children = {} end
Tercio@23 667 self.children[name] = newDB
Tercio@23 668 return newDB
Tercio@23 669 end
Tercio@23 670
Tercio@23 671 --- Returns an already existing namespace from the database object.
Tercio@23 672 -- @param name The name of the new namespace
Tercio@23 673 -- @param silent if true, the addon is optional, silently return nil if its not found
Tercio@23 674 -- @usage
Tercio@23 675 -- local namespace = self.db:GetNamespace('namespace')
Tercio@23 676 -- @return the namespace object if found
Tercio@23 677 function DBObjectLib:GetNamespace(name, silent)
Tercio@23 678 if type(name) ~= "string" then
Tercio@23 679 error("Usage: AceDBObject:GetNamespace(name): 'name' - string expected.", 2)
Tercio@23 680 end
Tercio@23 681 if not silent and not (self.children and self.children[name]) then
Tercio@23 682 error ("Usage: AceDBObject:GetNamespace(name): 'name' - namespace does not exist.", 2)
Tercio@23 683 end
Tercio@23 684 if not self.children then self.children = {} end
Tercio@23 685 return self.children[name]
Tercio@23 686 end
Tercio@23 687
Tercio@23 688 --[[-------------------------------------------------------------------------
Tercio@23 689 AceDB Exposed Methods
Tercio@23 690 ---------------------------------------------------------------------------]]
Tercio@23 691
Tercio@23 692 --- Creates a new database object that can be used to handle database settings and profiles.
Tercio@23 693 -- By default, an empty DB is created, using a character specific profile.
Tercio@23 694 --
Tercio@23 695 -- You can override the default profile used by passing any profile name as the third argument,
Tercio@23 696 -- or by passing //true// as the third argument to use a globally shared profile called "Default".
Tercio@23 697 --
Tercio@23 698 -- Note that there is no token replacement in the default profile name, passing a defaultProfile as "char"
Tercio@23 699 -- will use a profile named "char", and not a character-specific profile.
Tercio@23 700 -- @param tbl The name of variable, or table to use for the database
Tercio@23 701 -- @param defaults A table of database defaults
Tercio@23 702 -- @param defaultProfile The name of the default profile. If not set, a character specific profile will be used as the default.
Tercio@23 703 -- You can also pass //true// to use a shared global profile called "Default".
Tercio@23 704 -- @usage
Tercio@23 705 -- -- Create an empty DB using a character-specific default profile.
Tercio@23 706 -- self.db = LibStub("AceDB-3.0"):New("MyAddonDB")
Tercio@23 707 -- @usage
Tercio@23 708 -- -- Create a DB using defaults and using a shared default profile
Tercio@23 709 -- self.db = LibStub("AceDB-3.0"):New("MyAddonDB", defaults, true)
Tercio@23 710 function AceDB:New(tbl, defaults, defaultProfile)
Tercio@23 711 if type(tbl) == "string" then
Tercio@23 712 local name = tbl
Tercio@23 713 tbl = _G[name]
Tercio@23 714 if not tbl then
Tercio@23 715 tbl = {}
Tercio@23 716 _G[name] = tbl
Tercio@23 717 end
Tercio@23 718 end
Tercio@23 719
Tercio@23 720 if type(tbl) ~= "table" then
Tercio@23 721 error("Usage: AceDB:New(tbl, defaults, defaultProfile): 'tbl' - table expected.", 2)
Tercio@23 722 end
Tercio@23 723
Tercio@23 724 if defaults and type(defaults) ~= "table" then
Tercio@23 725 error("Usage: AceDB:New(tbl, defaults, defaultProfile): 'defaults' - table expected.", 2)
Tercio@23 726 end
Tercio@23 727
Tercio@23 728 if defaultProfile and type(defaultProfile) ~= "string" and defaultProfile ~= true then
Tercio@23 729 error("Usage: AceDB:New(tbl, defaults, defaultProfile): 'defaultProfile' - string or true expected.", 2)
Tercio@23 730 end
Tercio@23 731
Tercio@23 732 return initdb(tbl, defaults, defaultProfile)
Tercio@23 733 end
Tercio@23 734
Tercio@23 735 -- upgrade existing databases
Tercio@23 736 for db in pairs(AceDB.db_registry) do
Tercio@23 737 if not db.parent then
Tercio@23 738 for name,func in pairs(DBObjectLib) do
Tercio@23 739 db[name] = func
Tercio@23 740 end
Tercio@23 741 else
Tercio@23 742 db.RegisterDefaults = DBObjectLib.RegisterDefaults
Tercio@23 743 db.ResetProfile = DBObjectLib.ResetProfile
Tercio@23 744 end
Tercio@23 745 end