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 |