LibStub

Addons
3.9k Downloads

While Rift has a built-in version checking system, LibStub is primarily designed to do two things:

  1. Load LibCallbackHandler
  2. Make porting World of Warcraft libraries that use CallbackHandler much easier.

riftui.com's wiki article about RiftAddon.toc

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

This is a port of LibStub to Rift by Lorandii aka Myrroddin.

rift.curseforge.com is the main development hub; however, so I don't have to look all over the place to find bug reports or suggestions, please post a comment on the riftui.com LibStub page.

Addon Authors:

While it is not strictly necessary, in your RiftAddon.toc, please add "Lib" to indicate to everybody, both authors and end users, that your file is indeed a library.

Identifier = "LibMyLibrary"
Name = "Lib: MyLibrary"

LibStub-1.0 API

:GetLibrary(major [, silent])

Returns

The table instance of a registered library or nil if not found and the minor version of the library as the second return value.

Arguments

major The name of the library you are requesting

silent (Optional) Suppresses errors when the library is not found

:IterateLibraries()

Returns

An iterator over the registered major libraries.

:NewLibrary(major , minor)

Returns

The table to be used by the library as well as the minor version of the previously registered library, if any.

Arguments

major The name of the library you are requesting

minor The minor for the registering library

Who uses LibStub?

  • Ace3, for which it was originally designed (not ported to Rift yet)
  • Rock, ckknight's framework (obsolete, abandoned)
  • Norganna has announced that the next major version of Auctioneer will use it for its libraries
  • Some Dongle-related libraries use it
  • And now Rift!

How to include LibStub in a library or addon

Library

if using the CurseForge repositories

  • setup an external pointing to svn://svn.curseforge.net/rift/libstub/mainline/trunk in the .pkgmeta file
  • disable nolib creation by adding enable-nolib-creation: no to the .pkgmeta file
  • 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 meant for embedded loading of your lib
  • don't set LibStub as X-embeded or OptDep

otherwise

  • 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 meant for embedded loading of your lib
  • don't set LibStub as X-embeded or OptDep

AddOn

if using the CurseForge repositories

otherwise

  • 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 {}
local context = UI.CreateContext("Context")

if not lib.frame then
  lib.frame = UI.CreateFrame("Frame", "Frame", context)
end


function lib:SomeFunction()
  -- do stuff here
end

function lib:SomeOtherFunction()
  -- do other stuff here
end

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(string.match("%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