ParserLib

From WowAce Wiki
Jump to: navigation, search
Summary
Lib: ParserLib-1.1
Combat log parsing library
TOC 2.3 (20300)
Category Libraries
Author Rophy
Details
Version 1.1
OptionalDeps FixLogStrings, Parser-3.0, SW_Stats
Links
Releases WoWI
Betas Ace SVN Zip
Changelog FishEye

ParserLib is a combat log parser library.

For a list of supported Blizzard events, check Supported Events.

A table containing parsed information will be passed to your event handler, for detailed information about the table fields, check Message Types.

See also: ParserLib API Documentation

Combat Log Parsing

What is combat log parsing?

The WoW combat log events (those with the name starts as CHAT_MSG_ ) give us the combat log strings which we read in the standard combat log frame, lots of useful information can be extracted from those strings. For example:

event: CHAT_MSG_COMBAT_CREATURE_VS_SELF_HITS
string: Irondeep Shaman crits you for 68. (17 absorbed)

Given the string, we know that someone with the name "Irondeep Shaman" hit you with melee attack, which caused 68 damage, absorbed 17 damage, and is a critical hit.

Looking at the event name, we can know that this event is about creatures (NPC) hitting you, and so "Irondeep Shaman" should be the name of an enemy NPC. Note that the informations suggested from the event names aren't always accurate though.

Since all we have from the event is an event name and a combat log string, we need to parse the strings to obtain the information we need. Read HOWTO: Parse Event Messages for some basic description about how to parse combat logs.

Why a combat log parser?

First, combat log parsing requires parsing a string with multiple possible regular expressions, which is slow. Traditionally all addons do their own combat log parsing, which duplicates such slow process. Obviously a centralized approach here will benefit your CPU greatly.

Second, if you want your addon to work across WoW localizations, the complexity is much higher than what you read in the wowwiki mentioned above. I will not describe the exact details here, but having a library greatly simplifies such process and let developers focus on providing the features they want.

ParserLib

ParserLib is a combat log parser which extracts meaningful informations out of combat log strings.

To use ParserLib, your addon register events to ParserLib like this:

local parser = ParserLib:GetInstance("1.1')
parser:RegisterEvent("MyAddon", "CHAT_MSG_COMBAT_SELF_HIT", "MyAddonEventHandler")

Very similar to what you do to frame:RegisterEvent(), when the registered event is fired, ParserLib will call your registered handler, but instead of the combat log string (arg1), it passes a table as the second parameter:

function MyAddonEventHandler(event, info)
  if info.type == "hit" then
    ChatFrame1:AddMessage( info.source .. " hit " .. info.victim .. " for " .. info.amount ) 
  end
end

Usage

1. Obtain an instance of ParserLib by calling the ParserLib:GetInstance() method.

local parser = ParserLib:GetInstance("1.1")

2. To register for a Blizzard event from ParserLib, do this:

parser:RegisterEvent("MyAddOn", "CHAT_MSG_COMBAT_SELF_HITS", MyAddOn_OnParserEvent)

or, if your event handler is a method in an object:

parser:RegisterEvent(MyAddOnObject, "CHAT_MSG_COMBAT_SELF_HITS", "OnParserEvent" )

3. Now define your call back function, ParserLib will call it when the registered event occurs.

function MyAddOn_OnParserEvent(event, info)
  -- check info.type to know what's inside info.
  -- do whatever you want with the data.
end

function MyAddonObject:OnParserEvent(event, info)
  -- check info.type to know what's inside info.
  -- do whatever you want with the data.
end

4. info is a table which contains all parsed information. To know what information you can get from the table, check the info.type variable, detailed description for each type is here.

NOTE: the info table is a READ ONLY table, it will be passed to all clients and will be recycled, do not try to modify it.

Example

function MyAddOn_OnParserEvent(event, info)
  if info.type == "hit" then
    if info.source == ParserLib_SELF then info.source = "you" end
    if info.victim == ParserLib_SELF then info.source = "you" end
    if info.skill == ParserLib_MELEE then info.skill = "melee" end
    ChatFrame1:AddMessage(info.source .. " hits " .. info.victim .. " with " .. info.skill .. " for " .. info.amount)
  end
end

parser = ParserLib:GetInstance("1.1")
parser:AddEventHandler("MyAddOn", "CHAT_MSG_COMBAT_SELF_HITS", MyAddOn_OnParserEvent)	
parser:AddEventHandler("MyAddOn", "CHAT_MSG_COMBAT_PET_HITS", MyAddOn_OnParserEvent
parser:AddEventHandler("MyAddOn", "CHAT_MSG_SPELL_SELF_DAMAGE", MyAddOn_OnParserEvent)
parser:AddEventHandler("MyAddOn", "CHAT_MSG_SPELL_PET_DAMAGE", MyAddOn_OnParserEvent)
parser:AddEventHandler("MyAddOn", "CHAT_MSG_SPELL_PERIODIC_CREATURE_DAMAGE", MyAddOn_OnParserEvent)
parser:AddEventHandler("MyAddOn", "CHAT_MSG_SPELL_PERIODIC_HOSTILEPLAYER_DAMAGE", MyAddOn_OnParserEvent)

Now you got yourself an addon which reports melee and spell hits of you and your pet!