WoWBench/Documentation

Can you think of something you'd like to see? Anything that stumped you at first? Comment at the discussion page!

File invocation order

• wowbench.lua

• config.lua
• utils.lua
• debugger.lua
• api.lua
• xmlparse.lua
• cmdline.lua
• classops.lua
• world.toc

• world.lua
• worldxml.lua
• world.xml
• worldcmds.lua

• blizzardui.toc

• uixml.lua
• widgets.lua

• framexml.toc
• addon .toc:s

Brief file descriptions

Since we're all programmers here, we know to go look in the headers in the files (yep, they're there!), but the below is a brief overview of what the WoWBench source files contain and what they're there for to get you started.

api.lua

• Defines the World of Warcraft API emulation. Large.

blizzardui.toc

• Pull in files that prepare WoWBench to load Blizzard UI files (FrameXML, AddOns...)

classops.lua

• Basic object class operations: constructing, inheriting...
• Also defines WBClass_Base

cmdline.lua

• Mostly just defines WOWB_CommandLine() - a general command line parser that can be called with command lists from elsewhere in the code (only really by the main prompt and the debgger)
• Defines a few commands that are always there - quit, exit, direct Lua execution

config.lua

Configures WoWBench:

• Path to WoW
• Path to FrameXML
• Account/Character name (for SavedVariables access)
• What Lua compiler to use
• What TOC files to always load
• Various debug settings
• ...

debugger.lua

• Command line debugger
• Debug related utility functions
• Functions to register extra information about references (for use in stack/variable dumping)

uixml.lua

• Define WOWB_XMLTagInfo[] and WOWB_ROOTXMLTAG for parsing World of Warcraft XML files

Before uixml.lua is pulled in, these are configured for parsing "world" files by worldxml.lua. In theory, it could all be parsed as arguments to the XML parser, but it gets somewhat clunky since they are used in several functions.

utils.lua

• Lots of non-WoW-specific utility functions

widgets.lua

• Defines the objects and methods of the Widget API. Large.

world.lua

• Low level functions for interacting with the world (targetting object/units by name, mousing over units/objects, etc)
• Defines WBClass_WorldThing - the base class for everything in world.xml.
• Defines WBClass_Unit, WBClass_Player, WBClass_NPC, WBClass_Object, WBClass_Item

world.toc

• Pulls in game world related files. (See the load order graph above).

world.xml

• Defines all characters, npcs, objects and items available in the world.
• Also defines a large chunk of the "game engine" functionality for different types of things via the event handlers in the objects

worldcmds.lua

• Defines commands available in the main commandline (click, fire, say, etc..). The command structures are used by the command line driver in cmdline.lua.

worldxml.lua

• Define WOWB_XMLTagInfo[] and WOWB_ROOTXMLTAG for parsing world.xml.
• See also uixml.lua.

wowbench.lua

• The head honcho, the big one, the man with the mojo, the .... erhm, where was I...
• The file that calls everything else. Basically does not have a lot of functionality itself; mostly related to getting files loaded. See the load order graph above.

xmlparse.lua

• Defines a slightly quirky XML parser:

• It operates by translating XML to Lua, to avoid several layers of work that magically get handled by the Lua interpreter in the end
• In the end, the TOC parser function will compile the generated Lua files into a single chunk of compiled Lua, which loads fiendlishly fast.
• Bastard mutant brainchild of Mikk. Blame him. :-)

Function documentation

All nontrivial functions should have in-source function headers that briefly describes what the function does. Preferably it will also mention when it is getting called if it is a special-purpose function. Example:

---------------------------------------------------------------------
-- function WOWB_DumpVar(var,maxdepth,ind)
--
-- Return contents of a variable  as an ascii dump. Will recurse into tables.
-- Will attempt to avoid recursion to back references
-- Will never follow names in config.lua:_DUMPDONTFOLLOW[]
-- Uses plenty of magic set up elsewhere in the code to make more sense of 
-- table and function references.
--
-- var: the variable to be dumped
-- maxdepth: maximum recursion depth
-- ind: initial indent string, can be nil or e.g. "    "
--

See also

• WoWBench/FAQ
• WoWBench/Extending
• Back to WoWBench