LibStub
LibStub | |
---|---|
Library versioning tool | |
Details | |
TOC | n/a - meant to be embedded |
Category | Libraries |
Author | Kaelten et al. |
Links | |
CurseForge |
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 embedded by thousands of other addons.[1] It allows addons to more easily share libraries by checking for the most recent version and making it available to other installed addons. This cross-community library-sharing system was creditted to Kaelten, Cladhaire, ckknight, Mikk, Ammo, Nevcairiel and joshborke; and has resided in the Public Domain since c. 2007.[2][3]
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 loadLibStub.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 loadLibStub.lua
- don't set LibStub as X-embeded or OptDep
Examples
Basic usage
Using an integer for minor versions:
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 versions:
local lib = LibStub:NewLibrary("MyLibrary-1.0", "$Revision: 12345$")
if not lib then
return -- already loaded and no upgrade necessary
end
Bumping the number from a revision control system after it resets or slides backwards (i.e. when moving code from one repository to another):
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. At the end of the file, we handle library upgrades by re-embedding it in all positions where it was previously embedded / mixed in:
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
-- At the end of the file
for target,_ in pairs(mixinTargets) do
lib:Embed(target)
end
External links
References
- ^ LibStub: Addon dependents list (A list of more than 2,000 addons who self-identified via wowace or curseforge as depending on LibStub). wowace.com. Retrieved on 2020-02-20.
- ^ Edit history of LibStub on 2007-08-29T17:25:43
- ^ Nevcairiel 2008-09-28. Alpha version r89 at wowace.com (See X-License in .toc, and comment at top of .lua).