LibStub

LibStub is a minimalistic versioning library embedded by thousands of other addons. 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.
==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
:
* Rock, ckknight's framework
:
* 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 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==