This page describes fan-made scripting using the World of Warcraft API which has had notable impact on the game's development/history.
LibStub is a minimalistic versioning library that allows other libraries to easily register themselves and upgrade. It is meant to be a cross-community library sharing system.
LibStub is hereby placed in the Public Domain
Credits: Kaelten, Cladhaire, ckknight, Mikk, Ammo, Nevcairiel, joshborke
LibStub-1.0 API
:GetLibrary(major [, silent])
Arguments
Arg | Type | Details |
---|---|---|
major | string | The name of the library you are requesting |
silent | boolean | (Optional) Suppresses errors when the library is not found |
Returns
Return | Type | Details |
---|---|---|
major | table or nil | The table instance of a registered library or nil if not found |
minor | number | The minor revision of the registered library |
:IterateLibraries()
Returns
An iterator over the registered major libraries.
:NewLibrary(major , minor)
Arguments
Arg | Type | Details |
---|---|---|
major | string | The name of the library you are requesting |
minor | string or number | The minor for the registering library |
Returns
Return | Type | Details |
---|---|---|
major | table or nil | The table to be used by the library. |
oldminor | number | The minor revision of the previously registered library |
Who uses LibStub?
- Ace3, for which it was originally designed
- WoWAce.com Ace3
- Rock, ckknight's framework
- WoWAce.com Rock
- Auctioneer uses it for its libraries
- Some Dongle-related libraries use it.
- ... and hopefully many more to come!
How to include LibStub in a library or addon
Library
- get a copy of the current version
- copy LibStub.lua into your library's folder
- set up your <library>.toc file to load LibStub.lua (in case you support stand alone loading of the lib)
- don't load LibStub via the xml file ment for embedded loading of your lib
- don't set LibStub as X-embeded or OptDep
AddOn
- set up an external pointing to svn://svn.wowace.com/wow/libstub/mainline/tags/1.0
or
- get a copy of the current version
- copy LibStub.lua into your addon's folder or a subfolder of it
- set up your <addon>.toc or embeds.xml file to load LibStub.lua
- don't set LibStub as X-embeded or OptDep
Examples
Basic example
local lib = LibStub:NewLibrary("MyLibrary-1.0", 1) if not lib then return—already loaded and no upgrade necessary end lib.somearray = lib.somearray or {} if not lib.frame then lib.frame=CreateFrame("Frame") end function lib:SomeFunction() -- do stuff here end function lib:SomeOtherFunction() -- do other stuff here end local function OnUpdate() -- timing stuff here end lib.frame:SetScript("OnUpdate", OnUpdate);
Using revision control system tags for minor version
local lib = LibStub:NewLibrary("MyLibrary-1.0", "$Revision: 12345$")
Do be aware that moving a library from one repository to another will change revision numbers. Do not ever let it slide backwards. If you are caught in this situation, you might want to use something like:
local lib = LibStub:NewLibrary("MyLibrary-1.0", 12345+tonumber(strmatch("%d+","$Revision: 2$")) )
Embedding / Mixing in
This is a convention rather than a function of the specification, but all Ace3 and Rock related libraries use the following semantics for doing embedding / mixing in (specifically, libraries with an .Embed() member can be specified as embeds during addon object creation rather than having to embed them explicitly):
lib.mixinTargets = lib.mixinTargets or {} local mixins = {"SomeFunction", "SomeOtherFunction" } function lib:Embed(target) for _,name in pairs(mixins) do target[name] = lib[name] end lib.mixinTargets[target] = true end
... and at the end of the file, we handle library upgrades by simply re-embedding the library in all positions where it has previously been embedded / mixed in:
for target,_ in pairs(mixinTargets) do lib:Embed(target) end