LibRock-1.0 API Documentation

From WowAce Wiki

Contents 1 API Documentation 1.1 :AddUnitTest("namespace" , func) 1.1.1 Arguments 1.1.2 Notes 1.1.3 Example 1.2 :DebugRecycle("namespace") 1.2.1 Arguments 1.2.2 Notes 1.2.3 Example 1.3 :DoesObjectUseMixin(object , "mixinName") 1.3.1 Arguments 1.3.2 Returns 1.3.3 Example 1.4 :Embed(object) 1.4.1 Arguments 1.4.2 Notes 1.4.3 Returns 1.4.4 Example 1.5 :FinalizeLibrary("major") 1.5.1 Arguments 1.5.2 Notes 1.5.3 Example 1.6 :GetAddon("name") 1.6.1 Arguments 1.6.2 Returns 1.6.3 Example 1.7 :GetContractFunctions("namespace" , ...) 1.7.1 Arguments 1.7.2 Notes 1.7.3 Example 1.8 :GetLibrary("major" [, dontLoad] [, dontError]) 1.8.1 Arguments 1.8.2 Returns 1.8.3 Example 1.9 :GetLibraryVersion() 1.9.1 Notes 1.9.2 Returns 1.9.3 Example 1.10 :GetLocalizedCategory("name") 1.10.1 Arguments 1.10.2 Returns 1.10.3 Example 1.11 :GetRecyclingFunctions("namespace" , ...) 1.11.1 Arguments 1.11.2 Notes 1.11.3 Example 1.12 :GetUID() 1.12.1 Notes 1.12.2 Returns 1.12.3 Example 1.13 :HasAddon(name) 1.13.1 Arguments 1.13.2 Returns 1.13.3 Example 1.14 :HasLibrary("major" [, dontLoad]) 1.14.1 Arguments 1.14.2 Returns 1.14.3 Example 1.15 :IsActive() 1.15.1 Notes 1.15.2 Returns 1.15.3 Example 1.16 :IsLibraryMixin("name") 1.16.1 Arguments 1.16.2 Returns 1.16.3 Example 1.17 :IterateAddons() 1.17.1 Returns 1.17.2 Example 1.18 :IterateLibraries() 1.18.1 Returns 1.18.2 Example 1.19 :IterateMixinObjects("mixinName") 1.19.1 Arguments 1.19.2 Returns 1.19.3 Example 1.20 :IterateObjectMixins(object) 1.20.1 Arguments 1.20.2 Returns 1.20.3 Example 1.21 :NewAddon("name" , ...) 1.21.1 Arguments 1.21.2 Notes 1.21.3 Returns 1.21.4 Example 1.22 :NewLibrary("major" , version) 1.22.1 Arguments 1.22.2 Notes 1.22.3 Returns 1.22.4 Example 1.23 :SetExportedMethods(...) 1.23.1 Arguments 1.23.2 Notes 1.23.3 Example 1.24 :ToggleActive([state]) 1.24.1 Arguments 1.24.2 Notes 1.24.3 Returns 1.24.4 Example 1.25 :Unembed(object) 1.25.1 Arguments 1.25.2 Notes 1.25.3 Returns 1.25.4 Example

API Documentation

Note: This documentation is auto-generated. Please note that direct modifications may be overwritten on next autogenerate.

:AddUnitTest("namespace" , func)

Arguments

"namespace"

string - the namespace.

func

function - the function to call.

Notes

• Adds a unit test for the specified namespace
• The function provided is called, and it should be where tests are performed, if a problem occurs, an error should fire. If no problems occur, it should return silently.
• You can have as many tests per namespace as you want.

Example

Rock:AddUnitTest("LibMonkey-1.0", function()
	local LibMonkey = Rock("LibMonkey-1.0")
	assert(LibMonkey:Fling() == "Poo")
end)

:DebugRecycle("namespace")

Arguments

"namespace"

string - the namespace. Note: this doesn't necessarily have to be a string.

Notes

• Prints information about the specified recycling namespace, including what tables are still in play and where they come from and how many there are.
• This goes in tandem with :GetRecyclingFunctions

Example

local newList = Rock:GetRecyclingFunctions("MyNamespace", "newList", "Debug")
local t = newList()
Rock:DebugRecycle("MyNamespace")
t = del(t)

:DoesObjectUseMixin(object , "mixinName")

Arguments

object

table - the object to check

"mixinName"

string - the mixin to check

Returns

boolean - whether the object has the given mixin embedded into it.

Example

local LibMonkey = Rock:NewLibrary("LibMonkey-1.0")
local Darwin = Rock:NewAddon("Darwin", "LibMonkey-1.0")
assert(Rock:DoesObjectUseMixin(Darwin, "LibMonkey-1.0"))

:Embed(object)

Arguments

object

table - the table with which to export methods onto.

Notes

• This is exported to all libraries
• Embeds all the methods previously set to export onto a table.
• This will call :OnEmbed(object) on the library if it is available.

Returns

The table provided, after embedding.

Example

local LibMonkey = Rock:NewLibrary("LibMonkey-1.0", 50)
LibMonkey.FlingPoo = function(self)
	return "Splat!"
end
LibMonkey:SetExportedMethods("FlingPoo")
-- later
local Darwin = {}
Rock("LibMonkey-1.0"):Embed(Darwin)
assert(Darwin:FlingPoo() == "Splat!")

:FinalizeLibrary("major")

Arguments

"major"

string - name of the library.

Notes

• properly finalizes the library, essentially stating that it has loaded properly.
• This will call :OnLibraryLoad("major", library) on every other library
• This will also call :OnLibraryLoad("major", library) on the library provided, using every other library as the arguments.
• An error will occur if this is not done before ADDON_LOADED.

Example

local LibMonkey, oldLib = Rock:NewLibrary("LibMonkey-1.0", 50)
if not LibMonkey then
	-- opt out now, out of date
	return
end
Rock:FinalizeLibrary("LibMonkey-1.0")

:GetAddon("name")

Arguments

"name"

string - name of the addon.

Returns

addon

• table or nil - the addon requested

Example

local MyAddon = Rock:GetAddon("MyAddon")

:GetContractFunctions("namespace" , ...)

Arguments

"namespace"

string - the namespace. Note: this doesn't necessarily have to be a string.

...

type - (needs documentation)

Notes

• Returns functions for the specified namespace based on what is provided.
• function types:

"precondition" 

to set the pre-condition for a method.

"postcondition" 

to set the post-condition for a method.

"argCheck" 

to check the type of an argument, to be executed within a pre-condition.

• preconditon is in the form of precondition(object, "methodName", func(self, ...))
• postcondition is in the form of either postcondition(object, "methodName", func(returnValues, self, ...)) or postcondition(object, "methodName", func(oldValues, returnValues, self, ...), populateOld(oldValues, self, ...))
  • returnValues is the list of return values, empty if no return values were sent.
  • if the populateOld function is provided, then the empty oldValues table is provided and expected to be filled, and then given to the func.
• argCheck is in the form of argCheck(value, n, "type1" [, "type2", ...])
  • value is the value provided to the function you're checking.
  • n is the argument position. Note: 1 is the position of `self'. 2 would be the first "real" position.
  • the tuple of types can be any string, but specifically "nil", "boolean", "string", "number", "function", "userdata", "table", etc.

Example

local precondition, postcondition, argCheck = Rock:GetRecyclingFunctions("Stack", "precondition", "postcondition", "argCheck")
local stack = {}
stack.IsEmpty = function(self)
	return self[1] == nil
end
stack.GetLength = function(self)
	return #self
end
stack.Push = function(self, value)
	self[#self+1] = value
end
precondition(stack, "Push", function(self, value)
	argCheck(value, 2, "string") -- only accept strings, no other values
end)
postcondition(stack, "Push", function(old, ret, self, value)
	assert(self:GetLength() == old.length+1)
	assert(not self:IsEmpty())
end, function(old, self)
	old.length = self:GetLength()
end)
stack.Pop = function(self)
	local value = self[#self]
	self[#self] = nil
	return value
end
precondition(stack, "Pop", function(self)
	assert(self:GetLength() >= 1)
end)
postcondition(stack, "Pop", function(old, ret, self)
	assert(self:GetLength() == old.length-1)
end, function(old, self)
	old.length = self:GetLength()
end)
stack.Peek = function(self)
	return self[#self]
end
precondition(stack, "Peek", function(self)
	assert(self:GetLength() >= 1)
end)
postcondition(stack, "Peek", function(old, ret, self)
	assert(self:GetLength() == old.length)
end, function(old, self)
	old.length = self:GetLength()
end)
local t = setmetatable({}, {__index=stack})
t:Push("Alpha")
t:Push("Bravo")
t:Push(5) -- error, only strings
assert(t:Pop() == "Bravo")
assert(t:Pop() == "Alpha")
t:Pop() -- error, out of values

boolean boolean

:GetLibrary("major" [, dontLoad] [, dontError])

Arguments

"major"

string - name of the library.

dontLoad

boolean - whether to not load a library if it is not found. Default: false

dontError

boolean - whether to not error if a library is not found. Default: false

Returns

library

• table or nil - the library requested

Example

local LibMonkey = Rock:GetLibrary("LibMonkey-1.0")
-- or
local LibMonkey = Rock("LibMonkey-1.0")

:GetLibraryVersion()

Notes

• This is exported to all libraries

Returns

major, minor

• string - name of the library
• number - version of the library

Example

local major, minor = Rock:GetLibraryVersion() -- will be "LibRock-1.0", 12345
local major, minor = LibMonkey:GetLibraryVersion() -- will be "LibMonkey-1.0", 50

:GetLocalizedCategory("name")

Arguments

"name"

string - the English name of the category.

Returns

string - the localized name of the given category.

Example

local uf = Rock:GetLocalizedCategory("UnitFrame")

:GetRecyclingFunctions("namespace" , ...)

Arguments

"namespace"

string - the namespace. Note: this doesn't necessarily have to be a string.

...

type - (needs documentation)

Notes

• Returns functions for the specified namespace based on what is provided.
• function types:

"newList" 

to create a list

"newDict" 

to create a dictionary

"newSet" 

to create a set

"del" 

to delete a table

"unpackListAndDel" 

deletes a table and returns what its contents were as a list, in order.

"unpackSetAndDel" 

deletes a table and returns what its contents were as a set, in no particular order.

"unpackDictAndDel" 

deletes a table and returns what its contents were as a dictionary, in no particular order.

• If you provide "Debug" as the last argument, then the namespace can be debugged with :DebugRecycle
• It is not recommended to use table recycling with tables that have more than 128 keys, as it is typically faster to let lua's garbage collector handle it.

Example

local newList, newDict, newSet, del, unpackListAndDel, unpackSetAndDel, unpackDictAndDel = Rock:GetRecyclingFunctions("MyNamespace", "newList", "newDict", "newSet", "del", "unpackListAndDel", "unpackSetAndDel", "unpackDictAndDel")
local t = newList('alpha', 'bravo') -- same as t = {'alpha', 'bravo'}
local u = newDict('alpha', 'bravo') -- same as t = {['alpha'] = 'bravo'}
local v = newSet('alpha', 'bravo') -- same as t = {['alpha'] = true, ['bravo'] = true}
t = del(t) -- you want to clear your reference as well as deleting.
u = del(u)
v = del(v)
-- for debugging
local newList = Rock:GetRecyclingFunctions("MyNamespace", "newList", "Debug")
local t = newList()
Rock:DebugRecycle("MyNamespace")
t = del(t)
-- unpacking functions
unpackListAndDel(newList(...)) => ...
unpackSetAndDel(newSet(...)) => ...
unpackDictAndDel(newDict(...)) => ...
newList(unpackListAndDel(t)) => t
newSet(unpackSetAndDel(t)) => t
newDict(unpackDictAndDel(t)) => t
-- as you can see, they are inverses of each other.

:GetUID()

Notes

• This UID is not unique across sessions. If you save a UID in a saved variable, the same UID can be generated in another session.

Returns

number - a unique number.

Example

local UID = Rock:GetUID()

:HasAddon(name)

Arguments

name

string or table - name of the addon or the addon itself.

Returns

boolean - whether the addon requested exists.

Example

local hasMyAddon = Rock:HasAddon("MyAddon")
-- or
local hasMyAddon = Rock:HasAddon(MyAddon)

boolean

:HasLibrary("major" [, dontLoad])

Arguments

"major"

string - name of the library.

dontLoad

boolean - whether to not load a library if it is not found. Default: false

Returns

library

• table or nil - the library requested

Example

local hasLibMonkey = Rock:HasLibrary("LibMonkey-1.0")

:IsActive()

Notes

• This is exported to all addons.
• This information is retrieved from LibRockModuleCore-1.0 if it is a module, otherwise from LibRockDB-1.0 if it uses that as a mixin, otherwise it keeps a variable locally.

Returns

boolean - whether the addon is in an active state or not.

Example

local active = MyAddon:IsActive()

:IsLibraryMixin("name")

Arguments

"name"

string - name of the library.

Returns

boolean - whether the library exists and is a proper mixin which can be embedded.

Example

local isMixin = Rock:IsLibraryMixin("LibMonkey-1.0")

:IterateAddons()

Returns

an iterator to traverse all addons created with Rock.

Example

for name, addon in Rock:IterateAddons() do
	-- do something with name and addon
end

:IterateLibraries()

Returns

an iterator to traverse all registered libraries.

Example

for major, library in Rock:IterateLibraries() do
	-- do something with major and library
end

:IterateMixinObjects("mixinName")

Arguments

"mixinName"

string - major version of the mixin library

Returns

an iterator to traverse all objects that the given mixin has embedded into

Example

local LibMonkey = Rock:NewLibrary("LibMonkey-1.0")
local Darwin = Rock:NewAddon("Darwin", "LibMonkey-1.0")
for object in LibMonkey:IterateMixinObjects("LibMonkey-1.0") do
	assert(object == Darwin)
end

:IterateObjectMixins(object)

Arguments

object

type - (needs documentation)

Returns

an iterator to traverse all mixins that an object has embedded

Example

local LibMonkey = Rock:NewLibrary("LibMonkey-1.0")
local Darwin = Rock:NewAddon("Darwin", "LibMonkey-1.0")
for mixin in Rock:IterateObjectMixins(Darwin) do
	assert(mixin == LibMonkey)
end

:NewAddon("name" , ...)

Arguments

"name"

string - name of the addon.

...

tuple - list of mixins with which to embed into this addon.

Notes

• create a new addon with the specified name.

Returns

addon

• table - the addon with which to manipulate

Example

local MyAddon = Rock:NewAddon("MyAddon", "Mixin-1.0", "OtherMixin-2.0")

:NewLibrary("major" , version)

Arguments

"major"

string - name of the library.

version

number - version of the library.

Notes

• create a new library if the version provided is not out of date.

Returns

library, oldLibrary

• table or nil - the library with which to manipulate
• table or nil - the old version of the library to upgrade from

Example

local LibMonkey, oldLib = Rock:NewLibrary("LibMonkey-1.0", 50)
if not LibMonkey then
	-- opt out now, out of date
	return
end

:SetExportedMethods(...)

Arguments

...

tuple - the list of method names to export.

Notes

• This is exported to all libraries
• Allows you to set precisely what methods for the library to export.
• This automatically turns a library into a mixin.

Example

local LibMonkey = Rock:NewLibrary("LibMonkey-1.0", 50)
LibMonkey.FlingPoo = function(self)
	return "Splat!"
end
LibMonkey:SetExportedMethods("FlingPoo")
-- later
local Darwin = Rock:NewAddon("Darwin", "LibMonkey-1.0")
assert(Darwin:FlingPoo() == "Splat!")

boolean

:ToggleActive([state])

Arguments

state

boolean - whether the addon should be in an active state or not. Default: not :IsActive()

Notes

• This is exported to all addons.
• If it enables the addon, it will call :OnEnable(first) on the addon and :OnEmbedEnable(addon, first) on all its mixins.
• If it disables the addon, it will call :OnDisable(first) on the addon and :OnEmbedDisable(addon, first) on all its mixins.
• This information is stored by LibRockModuleCore-1.0 if it is a module, otherwise from LibRockDB-1.0 if it uses that as a mixin, otherwise it keeps a variable locally.

Returns

boolean - whether the addon is in an active state or not.

Example

MyAddon:ToggleActive() -- switch
MyAddon:ToggleActive(true) -- force on
MyAddon:ToggleActive(false) -- force off

:Unembed(object)

Arguments

object

table - the table with which to export methods onto.

Notes

• This is exported to all libraries
• Unembeds all the methods previously set to export onto a table.
• This will error if the library is not embedded on the object
• This will call :OnUnembed(object) on the library if it is available.

Returns

The table provided, after embedding.

Example

local LibMonkey = Rock:NewLibrary("LibMonkey-1.0", 50)
LibMonkey.FlingPoo = function(self)
	return "Splat!"
end
LibMonkey:SetExportedMethods("FlingPoo")
-- later
local Darwin = {}
Rock("LibMonkey-1.0"):Embed(Darwin)
assert(Darwin:FlingPoo() == "Splat!")
Rock("LibMonkey-1.0"):Unembed(Darwin)
assert(Darwin.FlingPoo == nil)