WoWBench/Documentation: Difference between revisions

From AddOn Studio
Jump to navigation Jump to search
(Safety save.)
 
mNo edit summary
 
(One intermediate revision by one other user not shown)
Line 3: Line 3:
''Can you think of something you'd like to see? Anything that stumped '''you''' at first? Comment at the ''{{discussiontab}}'' page!''
''Can you think of something you'd like to see? Anything that stumped '''you''' at first? Comment at the ''{{discussiontab}}'' page!''


 
== File invocation order ==
= File invocation order =
<div style="margin-left: 3%;">


* [[#wowbench.lua|wowbench.lua]]
* [[#wowbench.lua|wowbench.lua]]
:* [[#config.lua|config.lua]]
:* [[#config.lua|config.lua]]
:* [[#utils.lua|utils.lua]]
:* [[#utils.lua|utils.lua]]
:* [[#debugger.lua|debugger.lua]]
:* [[#debugger.lua|debugger.lua]]
Line 17: Line 13:
:* [[#cmdline.lua|cmdline.lua]]
:* [[#cmdline.lua|cmdline.lua]]
:* [[#classops.lua|classops.lua]]
:* [[#classops.lua|classops.lua]]
{{spc}}
:* [[#world.toc|world.toc]]
:* [[#world.toc|world.toc]]
::* [[#world.lua|world.lua]]
::* [[#world.lua|world.lua]]
Line 23: Line 18:
::* [[#world.xml|world.xml]]
::* [[#world.xml|world.xml]]
::* [[#worldcmds.lua|worldcmds.lua]]
::* [[#worldcmds.lua|worldcmds.lua]]
{{spc}}
:* [[#blizzardui.toc|blizzardui.toc]]
:* [[#blizzardui.toc|blizzardui.toc]]
::* [[#uixml.lua|uixml.lua]]
::* [[#uixml.lua|uixml.lua]]
::* [[#widgets.lua|widgets.lua]]
::* [[#widgets.lua|widgets.lua]]
{{spc}}
:* framexml.toc
:* framexml.toc
:* addon .toc:s
:* addon .toc:s


 
== Brief file descriptions ==
</div>
 
= Brief file descriptions =
<div style="margin-left: 3%;">
 
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.
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 ===
== api.lua ==
<div style="margin: 0em 0em 1em 2%;">
* Defines the [[World of Warcraft API]] emulation. Large.
* Defines the [[World of Warcraft API]] emulation. Large.


</div>
=== blizzardui.toc ===
 
== blizzardui.toc ==
<div style="margin: 0em 0em 1em 2%;">
* Pull in files that prepare WoWBench to load Blizzard UI files (FrameXML, AddOns...)
* Pull in files that prepare WoWBench to load Blizzard UI files (FrameXML, AddOns...)


</div>
=== classops.lua ===
 
== classops.lua ==
<div style="margin: 0em 0em 1em 2%;">
* Basic object class operations: constructing, inheriting...
* Basic object class operations: constructing, inheriting...
* Also defines WBClass_Base
* Also defines WBClass_Base


</div>
=== cmdline.lua ===
 
== cmdline.lua ==
<div style="margin: 0em 0em 1em 2%;">
 
* 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)
* 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
* Defines a few commands that are always there - quit, exit, direct Lua execution


</div>
=== config.lua ===
 
== config.lua ==
<div style="margin: 0em 0em 1em 2%;">
 
Configures WoWBench:
Configures WoWBench:
* Path to WoW
* Path to WoW
Line 79: Line 51:
* ...
* ...


</div>
=== debugger.lua ===
 
== debugger.lua ==
<div style="margin: 0em 0em 1em 2%;">
 
* Command line debugger
* Command line debugger
* Debug related utility functions
* Debug related utility functions
* Functions to register extra information about references (for use in stack/variable dumping)
* Functions to register extra information about references (for use in stack/variable dumping)


</div>
=== uixml.lua ===
 
== uixml.lua ==
<div style="margin: 0em 0em 1em 2%;">
 
* Define WOWB_XMLTagInfo[] and WOWB_ROOTXMLTAG for parsing World of Warcraft XML files
* 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.
: 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.


</div>
=== utils.lua ===
 
== utils.lua ==
<div style="margin: 0em 0em 1em 2%;">
 
* Lots of non-WoW-specific utility functions
* Lots of non-WoW-specific utility functions


</div>
=== widgets.lua ===
 
== widgets.lua ==
<div style="margin: 0em 0em 1em 2%;">
 
* Defines the objects and methods of the [[Widget API]]. Large.
* Defines the objects and methods of the [[Widget API]]. Large.


</div>
=== world.lua ===
 
== world.lua ==
<div style="margin: 0em 0em 1em 2%;">
 
* Low level functions for interacting with the world (targetting object/units by name, mousing over units/objects, etc)
* 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_WorldThing - the base class for everything in [[#world.xml|world.xml]].
* Defines WBClass_Unit, WBClass_Player, WBClass_NPC, WBClass_Object, WBClass_Item
* Defines WBClass_Unit, WBClass_Player, WBClass_NPC, WBClass_Object, WBClass_Item


</div>
=== world.toc ===
 
== world.toc ==
<div style="margin: 0em 0em 1em 2%;">
 
* Pulls in game world related files. (See the load order graph above).
* Pulls in game world related files. (See the load order graph above).


</div>
=== world.xml ===
 
== world.xml ==
<div style="margin: 0em 0em 1em 2%;">
 
* Defines all characters, npcs, objects and items available in the world.
* 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
* Also defines a large chunk of the "game engine" functionality for different types of things via the event handlers in the objects


</div>
=== worldcmds.lua ===
 
== worldcmds.lua ==
<div style="margin: 0em 0em 1em 2%;">
 
* 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]].
* 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]].


</div>
=== worldxml.lua ===
 
== worldxml.lua ==
<div style="margin: 0em 0em 1em 2%;">
 
* Define WOWB_XMLTagInfo[] and WOWB_ROOTXMLTAG for parsing [[#world.xml|world.xml]].
* Define WOWB_XMLTagInfo[] and WOWB_ROOTXMLTAG for parsing [[#world.xml|world.xml]].
* See also [[#uixml.lua|uixml.lua]].
* See also [[#uixml.lua|uixml.lua]].


</div>
=== wowbench.lua ===
 
== wowbench.lua ==
<div style="margin: 0em 0em 1em 2%;">
 
* The head honcho, the big one, the man with the mojo, the .... erhm, where was I...
* 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.
* 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.


</div>
=== xmlparse.lua ===
 
== xmlparse.lua ==
<div style="margin: 0em 0em 1em 2%;">
 
* Defines a slightly quirky XML parser:
* 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
:* It operates by translating XML to Lua, to avoid several layers of work that magically get handled by the Lua interpreter in the end
Line 167: Line 95:
:* Bastard mutant brainchild of [[User:Mikk|Mikk]]. Blame him. :-)
:* Bastard mutant brainchild of [[User:Mikk|Mikk]]. Blame him. :-)


 
== Function documentation ==
</div>
</div>
 
= Function documentation =
<div style="margin-left: 3%;">
 
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:
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:


<div style="float: left; clear: left;">
  ---------------------------------------------------------------------
  ---------------------------------------------------------------------
  -- function WOWB_DumpVar(var,maxdepth,ind)
  -- function WOWB_DumpVar(var,maxdepth,ind)
Line 190: Line 111:
  -- ind: initial indent string, can be nil or e.g. "    "
  -- ind: initial indent string, can be nil or e.g. "    "
  --
  --
</div><div style="clear:left;"></div>
</div>
= See also =
<div style="margin-left: 3%;">


== See also ==
* [[WoWBench/FAQ]]
* [[WoWBench/FAQ]]
* [[WoWBench/Extending]]
* [[WoWBench/Extending]]
* Back to [[WoWBench]]
* Back to [[WoWBench]]
</div>


[[Category:WoWBench]]
[[Category:WoWBench]]

Latest revision as of 19:26, 18 December 2008

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

File invocation order[edit]

  • framexml.toc
  • addon .toc:s

Brief file descriptions[edit]

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[edit]

blizzardui.toc[edit]

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

classops.lua[edit]

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

cmdline.lua[edit]

  • 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[edit]

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[edit]

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

uixml.lua[edit]

  • 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[edit]

  • Lots of non-WoW-specific utility functions

widgets.lua[edit]

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

world.lua[edit]

  • 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[edit]

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

world.xml[edit]

  • 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[edit]

  • 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[edit]

wowbench.lua[edit]

  • 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[edit]

  • 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[edit]

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[edit]