Quantcast
Download
(1 Kb)
Download
Updated: 07/23/15 02:57 PM
Updated:07/23/15 02:57 PM
Created:03/02/14 04:10 PM
Monthly downloads:236
Total downloads:12,315
Favorites:55
MD5:
LibStub  Popular! (More than 5000 hits)
Version: 1.0 r4
by: sirinsidiator, Seerah
sirinsidiator has offered to take over both LibStub and LAM-2.0.

LibStub was written for World of Warcraft by Kaelten, Cladhaire, ckknight, Mikk, Ammo, Nevcairiel and joshborke. It was ported to Elder Scrolls Online by Seerah. The below description was copied from WowAce with a few minor revisions.


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


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. You can pass LibStub.SILENT for better readability
: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?
LibAddonMenu-1.0
... 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>.txt file to load LibStub.lua (in case your library supports being installed standalone)
  • don't set LibStub as OptionalDependsOn

AddOn
  • get a copy of the current version
  • copy LibStub.lua into your addon's folder or a subfolder of it
  • set up your <addon>.txt file to load LibStub.lua
  • don't set LibStub as OptionalDependsOn


Basic Example

Lua Code:
  1. local lib = LibStub:NewLibrary("MyLibrary-1.0", 1)
  2.  
  3. if not lib then
  4.   return    -- already loaded and no upgrade necessary
  5. end
  6.  
  7. function lib:SomeFunction()
  8.   -- do stuff here
  9. end
  10.  
  11. function lib:SomeOtherFunction()
  12.   -- do other stuff here
  13. end
1.0 r4
- added a named constant for the silent flag as proposed by merlight

1.0 r3
- added support for fractional numbers in minor library version as proposed by merlight

1.0 r2
- fixed error handling

1.0 r1
- updated version number in LibStub.txt to match internal Major, minor revisions (1.0 r1 instead of 1.0.1)
Archived Files (4)
File Name
Version
Size
Author
Date
1.0 r3
1kB
sirinsidiator
06/14/15 12:55 PM
1.0 r2
2kB
sirinsidiator
07/13/14 09:24 PM
1.0 r1
2kB
Seerah
03/14/14 07:29 PM
1.0.1
2kB
Seerah
03/02/14 04:10 PM


Post A Reply Comment Options
Unread 07/06/14, 01:31 PM  
Seerah
Fishing Trainer
 
Seerah's Avatar
ESOUI Super Moderator
AddOn Author - Click to view AddOns

Forum posts: 651
File comments: 112
Uploads: 1
Originally Posted by CrazyDutchGuy
Originally Posted by Seerah
Originally Posted by merlight
Wonder nobody noticed yet, there's a tiny bug in this tiny lib

or (I guess that's what that local strformat was intended for)
Lua Code:
  1. error(strformat("Cannot find a library instance of %q.", tostring(major)), 2)
Whoops... Yep.
Just reminding that this is still not fixed.
I know. I haven't uploaded it yet.
Report comment to moderator  
Reply With Quote
Unread 07/06/14, 04:12 AM  
CrazyDutchGuy
 
CrazyDutchGuy's Avatar
AddOn Author - Click to view AddOns

Forum posts: 88
File comments: 301
Uploads: 9
Originally Posted by Seerah
Originally Posted by merlight
Wonder nobody noticed yet, there's a tiny bug in this tiny lib

or (I guess that's what that local strformat was intended for)
Lua Code:
  1. error(strformat("Cannot find a library instance of %q.", tostring(major)), 2)
Whoops... Yep.
Just reminding that this is still not fixed.
__________________
Your Crazy Dutch Addon Developer : ATLAS - Lost Treasure - Show Loot - Bank Stack - ATLAS Boss Logger

Donations : paypal
Report comment to moderator  
Reply With Quote
Unread 07/03/14, 06:22 PM  
Seerah
Fishing Trainer
 
Seerah's Avatar
ESOUI Super Moderator
AddOn Author - Click to view AddOns

Forum posts: 651
File comments: 112
Uploads: 1
Originally Posted by merlight
Wonder nobody noticed yet, there's a tiny bug in this tiny lib

or (I guess that's what that local strformat was intended for)
Lua Code:
  1. error(strformat("Cannot find a library instance of %q.", tostring(major)), 2)
Whoops... Yep.
Report comment to moderator  
Reply With Quote
Unread 07/03/14, 02:20 PM  
merlight
AddOn Author - Click to view AddOns

Forum posts: 645
File comments: 208
Uploads: 12
Wonder nobody noticed yet, there's a tiny bug in this tiny lib

Lua Code:
  1. error(("Cannot find a library instance of %q."):strformat(tostring(major)), 2)

change to
Lua Code:
  1. error(("Cannot find a library instance of %q."):format(tostring(major)), 2)

or (I guess that's what that local strformat was intended for)
Lua Code:
  1. error(strformat("Cannot find a library instance of %q.", tostring(major)), 2)
Report comment to moderator  
Reply With Quote
Unread 06/30/14, 11:18 AM  
zgrssd
AddOn Author - Click to view AddOns

Forum posts: 281
File comments: 26
Uploads: 3
Need some info on LibStub usage

Since I was never part of the WoW Addon community, so I had some questions regarding how exactly libStub works.
The features I could identify so far:
If you have more then instance of the same library (local copy and several embedded ones), Stub makes certain only the most current stays in memory.
That also means some minor loadigntiem increase, as already loaded embedded libs do not have thier code executed again.
It also keeps the global namespace clean. Nothing about the lib needs to be globally exposed, as libStub is globaly exposed and can hand out references.

Now to my questions (specifically towards the examples):

Code:
    local lib = LibStub:NewLibrary("MyLibrary-1.0", 1)

    if not lib then
      return    -- already loaded and no upgrade necessary
    end
As I understand it, this will give you either:
A reference to a libs Table to assign your libs functions too.
Or nil/false in case this lib (with same or higher version) has already been run
Here you check if the return values is nil or false and then just cancel the .lua files execution (hence prevent older version from overwriting newer ones and save some processing time).

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

     
    function lib:SomeOtherFunction()
      -- do other stuff here
    end
Here you assign two functions using this variant of the Lua Namespace Syntax:
http://www.lua.org/pil/15.1.html

Could I also assign them like this:
Code:
    local function SomeFunction()
      -- do stuff here
    end

     
    local function SomeOtherFunction()
      -- do other stuff here
    end
lib.SomeFunction = SomeFunction
lib.SomeOtherFunction = SomeOtherFunction
:GetLibrary(major [, silent])
This will always only get me a refence to the highest version of hte library currently loaded.
But will this be a clone of the table currently registerd in LibStub, or the real table (wich means I have to look out not to assign anything).

Also what happens with the reference if a never version is loaded only after I called GetLibrary? Would the functions calls still target the previous version of the lib, or would even that "old" reference link to the new functions?
I generally call it in the OnLoaded event only, but I don't know if others might call it in code.


You also say "don't set LibStub as OptionalDependsOn", but I wonder why?
Is it not properly versioning itself?
Should I install a local copy of libStub? (the idea is that usually local copies are more likely up to date then embedded ones; and with optional dependencies libStub can get the local copy first).
What happens if a local copy is loaded by pure chance before the last embedded is run?
What if the local copy runs last by pure chance?
Last edited by zgrssd : 06/30/14 at 11:20 AM.
Report comment to moderator  
Reply With Quote
Post A Reply



Category Jump: