LibStub : Libraries : Elder Scrolls Online AddOns

(1 Kb)

Download

Updated: 11/02/18 08:08 AM

Add Favorite

Install Help

Portal

Bugs

Features

Compatibility:	Murkmire (4.2)
Updated:	11/02/18 08:08 AM
Created:	03/02/14 04:10 PM
Monthly downloads:	11,577
Total downloads:	36,127
Favorites:	128
MD5:

4.2

LibStub

Version: 1.0 r5

by: sirinsidiator, Seerah

Addon Authors: LibStub is no longer needed if you plan to write a new library.
The game can manage the versioning itself, so just write your library like you would any other addon and make sure you add the "AddOnVersion" directive with an unsigned integer as the version number (e.g. "## AddOnVersion 5").

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:

local lib = LibStub:NewLibrary("MyLibrary-1.0", 1)
 
if not lib then
  return    -- already loaded and no upgrade necessary
end
 
function lib:SomeFunction()
  -- do stuff here
end
 
function lib:SomeOtherFunction()
  -- do other stuff here
end

1.0 r5
- api bump (for all the poor people who don't like to check a checkbox)

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 (5)

File Name	Version	Size	Author	Date
LibStub	1.0 r4	1kB	sirinsidiator	07/23/15 02:57 PM
LibStub	1.0 r3	1kB	sirinsidiator	06/14/15 12:55 PM
LibStub	1.0 r2	2kB	sirinsidiator	07/13/14 09:24 PM
LibStub	1.0 r1	2kB	Seerah	03/14/14 07:29 PM
LibStub	1.0.1	2kB	Seerah	03/02/14 04:10 PM

Comment Options

11/03/18, 08:53 AM

sirinsidiator

Forum posts: 1140

File comments: 691

Uploads: 28

Re: Creating a library without LibStub

Originally Posted by tomtomhotep

Originally Posted by sirinsidiator

Addon Authors: LibStub is no longer needed if you plan to write a new library.

This confuses me a bit. How would I do this. I just declare my own global table and hope I gave it a unique-enough name?

I thought the main purpose of LibStub was to take all those table references and stuff them into one big Global table named LibStub, to avoid Globals Pollution?

Also, if I write a library with it's own global table, then it can NEVER be bundled inside another addon. It must be loaded as a standalone addon (which many addon authors are moving towards, but they're not all there yet).

Global namespace pollution never was a major concern in this context and you had to make sure that you use a unique name for the library anyways if you wanted to register it with LibStub. The entire purpose of it was versioning of the library code.

When multiple addons contain some version of the lib and each loads the files from its own manifest, you somehow have to make sure that only the newest version of the code is used. That's what LibStub was made for. However, since a year ago the game itself supports loading of nested addons and you can specify an "AddOnVersion" inside the manifest so it only loads the newest version.

This means you no longer need to add the library files to your addon manifest, but instead can just mark it as a dependency in the manifest via the "DependsOn" directive and let the library handle loading of its own files since it basically has become a full fledged addon. Which also means you can now use xml for ui elements, split the library code into multiple files, use saved variables and no longer have to worry about bugs from old library versions getting carried over, since only the latest code is loaded by the game.

Authors can still put the library inside their own addon if they wish so, since the game will just load it from within the addon folder (as long as it's not nested too deeply), but recently many have opted to move them out, since it means that updating them whenever a new version is uploaded to ESOUI is no longer tied to releasing a new version of dependent addon. Meaning the new library version arrives faster at the users end since it is handled by minion, or users should be aware that they have to check for library updates too.

__________________

>siri.exe MyAddon
Does your addon work? [y/n] n
There is a typo in there.

11/03/18, 08:29 AM

Baertram

Forum posts: 1800

File comments: 1953

Uploads: 48

Re: Creating a library without LibStub

Half correct. You can bundle the lib with your addon but it needs its own txt file with the ## AddOnVersion: tag!
Which Imo makes no sense to bundle it then! Just install it as standalone.

And libStub is not cleaning global name's pace. Each addon with global variables will be still in _G after libs tub loaded it (libraries as well). LibStub just adds the libs to its own global namespace so you can easily access it + check the version and overwrite older major/minor version combinations (where major is the library name most of the time) with newer minor versions. This way you always assure the newest version is loaded no matter if standalone, in subfolders loaded by own libraryName.txt, or in subfolders loaded by the main addonName.txt.

About the new library:
I guess you are right. Create a global variable/table yourLib = {} and add the infos to it. As long as it got a txt with the ##AddOnVersion: it will check the newest version from this info and overwrite the existing global table.
You could also declare it like this to keep existing data already yourLib = yourLib or {}. But this won't overwrite then!
So a newer version could only add data but not overwrite it.

Originally Posted by tomtomhotep

Originally Posted by sirinsidiator

Addon Authors: LibStub is no longer needed if you plan to write a new library.

Last edited by Baertram : 11/03/18 at 08:33 AM.

11/03/18, 08:10 AM

tomtomhotep

Forum posts: 21

File comments: 166

Uploads: 6

Creating a library without LibStub

Originally Posted by sirinsidiator

Addon Authors: LibStub is no longer needed if you plan to write a new library.

11/03/18, 04:12 AM

sirinsidiator

Forum posts: 1140

File comments: 691

Uploads: 28

Originally Posted by F-Lambda

Originally Posted by Dolgubon

Originally Posted by SteveCampsOut

Is this lib even necessary anymore? It hasn't been updated since 2014. I'd like to delete it.

Yes, very much so. If you remove it, almost every single library you have will not work.

Is this still the case, seeing as the add-on description reads "LibStub is no longer needed if you plan to write a new library" at the top.

This is directed towards authors who are creating a new library. Existing libraries that are based on LibStub will always require it as a dependency, until they are updated to no longer depend on it.

__________________

>siri.exe MyAddon
Does your addon work? [y/n] n
There is a typo in there.

Last edited by sirinsidiator : 11/03/18 at 04:13 AM.

11/03/18, 12:44 AM

F-Lambda

Forum posts: 1

File comments: 33

Uploads: 0

Originally Posted by Dolgubon

Originally Posted by SteveCampsOut

Is this lib even necessary anymore? It hasn't been updated since 2014. I'd like to delete it.

Yes, very much so. If you remove it, almost every single library you have will not work.

Is this still the case, seeing as the add-on description reads "LibStub is no longer needed if you plan to write a new library" at the top.

12/09/17, 11:42 PM

Dolgubon

Forum posts: 316

File comments: 533

Uploads: 12

Originally Posted by SteveCampsOut

Is this lib even necessary anymore? It hasn't been updated since 2014. I'd like to delete it.

Yes, very much so. If you remove it, almost every single library you have will not work.

12/09/17, 08:23 PM
SteveCampsOut Forum posts: 16 File comments: 254 Uploads: 0	Is this lib even necessary anymore? It hasn't been updated since 2014. I'd like to delete it.

07/06/14, 01:31 PM

Seerah

Fishing Trainer

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:

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.

07/06/14, 04:12 AM

CrazyDutchGuy

Forum posts: 89

File comments: 324

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:

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

07/03/14, 06:22 PM

Seerah

Fishing Trainer

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:

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

Whoops... Yep.

07/03/14, 02:20 PM
merlight Forum posts: 645 File comments: 208 Uploads: 12	Wonder nobody noticed yet, there's a tiny bug in this tiny lib Lua Code: error(("Cannot find a library instance of %q."):strformat(tostring(major)), 2) change to Lua Code: 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: error(strformat("Cannot find a library instance of %q.", tostring(major)), 2)

06/30/14, 11:18 AM
zgrssd 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 this File