SeaHooks

From WoWWiki

Always wanted to use standard hooking and unhooking methods that are safe, flexible, compatible with other hooks and easy to debug but didn't want to require your users to download all of the Sea Library? Well now you can embed that functionality into your addon as easily as modifying your TOC! Not only that but if multiple Sea/SeaHook libraries are loaded a simple versioning system with keep the live copy up to date without extraneous loading and having multiple copies in memory.

This is the most flexible hooking system you've ever seen; plus it's optimized to create the least gc possible!

Contents 1 Download 2 Function Hooking 3 Frame Script Element Hooking 4 Indexed Variables 5 Installation/Utilization 6 Debugging

Download

Seahooks is availible at both Curse-Gaming and WoWInterface

Function Hooking

• Sea.util.hook( "origFunctionName", "hookFunctionName", "hide/before/replace/after")
• Sea.util.unhook( "origFunctionName", "hookFunctionName", "hide/before/replace/after")

Hook types :

1. "hide" - called instead of the orig function. If you return true, subsequent hooks will be called afterwards, otherwise no further non-hide hooks nor the orig function will be called.
2. "before" - called before the orig function. If you return true, the subsequent args will be fed into the calls of the orig function as well as any other functions that hook the same orig function.
3. "replace" - called instead of the orig function. If you return true, the orig function will be called afterwards. Subsequent args will be returned by the hooked function call.
4. "after" - called after the orig function. If you return true, the subsequent args will be returned by the hooked function call.

• Sea.util.getReturnArgs() - Get the current return values of a hooked function from within an 'after' hook. (So that you don't have to duplicate logic and/or can simply modify the return arguments.)

Frame Script Element Hooking

Sea.util.hook( "frameName", "hookFunctionName", "before/after/replace/hide", "scriptElementName")

Sea.util.unhook( "frameName", "hookFunctionName", "before/after/replace/hide", "scriptElementName")

Indexed Variables

The variables for origFunctionName/frameName/hookFunctionName may all be tabled index strings. Thus "myTable.key" works as a valid function definition if you would normally call it by doing myTable.key() or myTable["key"]() This is made possible by the following functions (which can by themselves as well):

• Sea.util.split( "text", "separator"[, oldTable[, noPurge]] )
• Sea.util.getValue("indexed.variablename")
• Sea.util.setValue("indexed.variablename", value)

Installation/Utilization

Embedding:

1. Drop the SeaHooks folder into your Interface\AddOns\YourAddon\ folder
2. Add Sea and SeaHooks as optional dependancies
3. Add the following line to the end of your TOC file, before your addon files:

SeaHooks\SeaHooks.lua

Standard:

1. Drop the SeaHooks folder into your Interface\AddOns\ directory
2. Add SeaHooks a required dependency

Debugging

Another nice thing about Sea hooks is that you can look in one place to find all your hooking conflicts. If there's a problem just look in the Sea.util.Hooks table. Hooks are listed by the name of the orig function, or by "frameName.scriptElementName". If all your addons are using this method it makes them infinitely easier to debug conflicts. Plus it's simple to replace a manual hook with a Sea hook, usually just a couple of lines. In the rare case that a manual hook calls the orig function in the middle you can usually split it into a "before" and "after" hook and make life easier for everyone. This standardized hooking is cleaner to code with, simpler to read and understand, flexible enough to handle any hook type and now doesn't require your users to download a dependency! If you can think of ANY reason why it would be better to use another hooking method please let us know. We'd love to make SeaHooks the primere method preferred by addon developers.

• Sea.util.debugHooks( enable , "verboseFunctionName" ) - Enable standard or verbose error logging. (Prints to the default chat frame)

Examples:

• On: Sea.util.debugHooks(1);
• Verbose: Sea.util.debugHooks(1, "ChatFrame_OnLoad");
• Off: Sea.util.debugHooks();