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