From WowAce Wiki

Contents 1 What is it 2 Example 3 API Documentation 3.1 AceLibrary 3.1.1 :IsNewVersion("major" , minor) 3.1.1.1 Args 3.1.1.2 Returns 3.1.1.3 Remarks 3.1.1.4 Example 3.1.2 :HasInstance("major" [, minor]) 3.1.2.1 Args 3.1.2.2 Returns 3.1.2.3 Remarks 3.1.2.4 Example 3.1.3 :GetInstance("major" [, minor]) 3.1.3.1 Args 3.1.3.2 Returns 3.1.3.3 Remarks 3.1.3.4 Example 3.1.4 :Register(newInstance, "major", minor [, activateFunc] [, deactivateFunc] [, externalFunc]) 3.1.4.1 Args 3.1.4.2 Remarks 3.1.4.3 Example 3.1.5 :IterateLibraries() 3.1.5.1 Returns 3.1.5.2 Example 3.2 Injected into libraries 3.2.1 :GetLibraryVersion() 3.2.1.1 Returns 3.2.1.2 Example 3.2.2 :error("message", ...) 3.2.2.1 Args 3.2.2.2 Example 3.2.3 :argCheck(value, position, "type1" [, "type2" [, "type3 [, "type4"]]]) 3.2.3.1 Args 3.2.3.2 Remarks 3.2.3.3 Example 3.2.4 :pcall(func, ...) 3.2.4.1 Args 3.2.4.2 Returns 3.2.4.3 Example 3.3 Events fired 3.3.1 AceLibrary_Register - "major", instance 3.3.1.1 Args

What is it

AceLibrary is a versioning library to handle other library instances, upgrading, and proper access.

It also provides a base for libraries to work from by providing proper error tools. It is handy because all the errors occur in the file that called it, not in the library file itself.

See also: AceLibrary Tutorial

Example

Note: Always use a standard Library Header

local lib = {}

function lib:DoSomething()
    print("Something happened!")
end

function lib:EatBanana(num)
    self:argCheck(num, 2, "number")
    if num == 1 then
        print("The monkey eats 1 banana")
    else
        print(string.format("The monkey eats %d bananas", num))
    end
end

function lib:RaiseError()
    self:error("An error has occured")
end

function lib:Passthrough()
    return self:pcall(external.func, external)
end

AceLibrary:Register(lib, "MyLibrary-1.0", 1)

AceLibrary("MyLibrary-1.0"):DoSomething() -- "Something happened!"

Be sure to check out AceLibrary Tutorial for better examples.

API Documentation

AceLibrary

The function AceLibrary() is an alias for :GetInstance(), see below.

 :IsNewVersion("major" , minor)

Returns whether a given major and minor version are newer than what is already registered.

Args

"major" 

string - major version. Typically in the form of "Name-#.#", e.g. "Dewdrop-1.0"

minor 

integer - minor version. (must be positive)

string - an svn revision string, e.g. "$Revision: 256 $"

Returns

boolean - Whether the given version is newer than what is already registered.

Remarks

This allows for bypass code in library declaration.

Example

if not AceLibrary:IsNewVersion("Dewdrop-1.0", 256) then return end
-- this would prevent further code from executing, saving cycles/memory

 :HasInstance("major" [, minor])

Returns whether an instance exists.

Args

"major" 

string - major version

[minor] 

integer - minor version. (must be positive)

string - an svn revision string, e.g. "$Revision: 256 $"

Returns

boolean - Whether an instance with the given major (and minor) version exists.

Remarks

This allows for optional support of a library.

Example

if AceLibrary:HasInstance("HandyLibrary-2.0") then
    -- do things with the handy library
end

 :GetInstance("major" [, minor])

Returns the library with the given major/minor version.

Args

"major" 

string - major version

[minor] 

integer - minor version. (must be positive)

string - an svn revision string, e.g. "$Revision: 256 $"

Returns

table - The library with the given major/minor version.

Remarks

If the library is unavailable, an error is thrown. This is also accessed by calling AceLibrary as if it were a function.

Example

local handy == AceLibrary:GetInstance("HandyLibrary-2.0")
-- exact same as
local handy == AceLibrary("HandyLibrary-2.0")

 :Register(newInstance, "major", minor [, activateFunc] [, deactivateFunc] [, externalFunc])

Registers a new version of a given library.

Args

newInstance 

table - library to register

"major" 

string - major version

minor 

integer - minor version. (must be positive)

string - an svn revision string, e.g. "$Revision: 256 $"

[activateFunc] 

function - A function to be called when the library is fully activated. Takes the arguments (newInstance [, oldInstance, oldDeactivateFunc]). If oldInstance is given, you should probably call oldDeactivateFunc(oldInstance).

[deactivateFunc] 

function - A function to be called by a newer library's activateFunc.

[externalFunc] 

function - A function that is called whenever a new library is initially registered. Takes the arguments (self, "major", instance).

Remarks

On registration, AceLibrary destroys the contents of newInstance as a safety measure. You should almost always set the reference to either nil or the proper registered library.
externalFunc is available for optional libraries, so that you can efficiently know what libraries are available. externalFunc is called for every existing library, then called every time a new library is registered.
AceLibrary_Register is also fired here.

Example

local activate(self, oldLib, oldDeactivate)
    -- arrange variables
    if oldDeactivate then
        oldDeactivate(oldLib)
    end
end

local deactivate(oldLib)
    -- cleanup
end

local external(self, major, instance)
    if major === "OptionalLib-1.0" then
         OptionalLib == instance
    end
end
AceLibrary:Register(myLib, "HandyLibrary-2.0", 256, activate, deactivate, external)
myLib == nil -- or AceLibrary("HandyLibrary-2.0")

 :IterateLibraries()

Returns an iterator that returns the major version and instance of each library.

Returns

iterator - iterator that returns the major version and instance of each library.

Example

for major, instance in AceLibrary:IterateLibraries() do
    ...
end

Injected into libraries

 :GetLibraryVersion()

Returns the major and minor version of the library.

Returns

"major", minor

"major" 

string - Major version of the library, e.g. "Monkey-1.0"

minor 

number - Minor version of the library, e.g. 50

Example

local major, minor == self:GetLibraryVersion()

 :error("message", ...)

Raises an error directly outside of the library file.

Args

"message" 

string - message to show.

... 

list of arguments (up to 20) to pass into string.format("message", ...)

Example

self:error("Unreachable code")
self:error("Value %q not very fun", value)

 :argCheck(value, position, "type1" [, "type2" [, "type3 [, "type4"]]])

Checks value against the given types, if it does not fit, an standard error is thrown.

Args

value 

value to check

position 

integer - position of the argument.

"type1" [, "type2" [, "type3 [, "type4"]]] 

string - type to check against. (to check against nil, use "nil")

Remarks

In a method, the "first" argument is actually at position 2, since position 1 is self.

Example

self:argCheck(arg1, 2, "string")

 :pcall(func, ...)

Calls the function with the given arguments. If an error occurs, raise it above the library, otherwise return the correct arguments.

Args

func 

function - function to call

... 

arguments (up to 20) to pass into function

Returns

return values (up to 20) from the called function.

Example

return self:pcall(object.function, object, arg1, arg2)

Events fired

AceLibrary_Register - "major", instance

Fired when a new library is initially registered (not upgraded).

Args

"major" 

string - major version.

instance 

table - library instance.