Editing WoWBench/Documentation

{{tocright}}

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

== File invocation order ==

* [[#wowbench.lua|wowbench.lua]]
:* [[#config.lua|config.lua]]
:* [[#utils.lua|utils.lua]]
:* [[#debugger.lua|debugger.lua]]
:* [[#api.lua|api.lua]]
:* [[#xmlparse.lua|xmlparse.lua]]
:* [[#cmdline.lua|cmdline.lua]]
:* [[#classops.lua|classops.lua]]
:* [[#world.toc|world.toc]]
::* [[#world.lua|world.lua]]
::* [[#worldxml.lua|worldxml.lua]]
::* [[#world.xml|world.xml]]
::* [[#worldcmds.lua|worldcmds.lua]]
:* [[#blizzardui.toc|blizzardui.toc]]
::* [[#uixml.lua|uixml.lua]]
::* [[#widgets.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|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|cmdline.lua]].

=== worldxml.lua ===
* Define WOWB_XMLTagInfo[] and WOWB_ROOTXMLTAG for parsing [[#world.xml|world.xml]].
* See also [[#uixml.lua|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 [[User:Mikk|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]]

[[Category:WoWBench]]