Editing WoW:Identifying buffs using textures

In some circumstances, it may be benefecial to use spell textures, rather than names, to identify buff and debuff effects - textures require no additional localization, while buff names will require to be localized for every language your addon should support. This HOWTO describes an easy mechanism to find out if a certain unit is affected by a specific buff or debuff.

== Iterating buff / debuffs ==
While we could write separate functions for buffs and debuffs, it's easier to write a single ''iterator'' function and pass the desired spell effect type as an argument - effectively cutting down the amount of code required for the whole routine. We can get the buff's texture from [[API UnitBuff|UnitBuff]] and debuffs from [[API UnitDebuff|UnitDebuff]]:
 name, rank, iconTexture, count, duration, timeLeft =  UnitBuff(unit, buffIndex [, castable]);
 name, rank, texture, count, debuffType, duration, timeLeft  =  UnitDebuff(unitID, debuffIndex [, removable]);
The effect's texture is the third return value of both functions, but UnitDebuff has one more return value - which means that we'll need to store all seven return values in order to return them. ''Castable'' and ''removable'' arguments allow us to save iterations of the loop if we're only interested in buffs/debuffs the player can cast/remove, so we should allow access to those from the iterator function. For both functions, index starts at 1 and goes up until the function returns nil -- while a while loop is ideal, we can use an infinite loop, and call break; when nil is encountered to save iterator calls. So far, our inner iterator loop would look something like:
 qFunc, unit, castable, id, match = UnitBuff, "player", 1, nil, "SomeEffectTexture"; --
 while true do
  local name, rank, texture, count, type, duration, timeleft = qFunc(unit, id, castable); -- note UnitDebuff returns; we simply don't care about the names at this point, but we need all seven.
  if not name then
   break; -- There are no more buffs / debuffs, exit infinite loop
  end
  if string.match(texture, match) then
   return name, rank, texture, count, type, duration, timeleft; -- We've found a match
  end
  i = i + 1; -- Go for the next index
 end
This would tell return the proper UnitBuff/UnitDebuff returns if the target is affected by a matching buff/debuff, or nil if it's not. Stopping here is good enough; we can, however, make things even better by allowing you to detect multiple textures with the same texture by using another index argument, and then decrementing it on matching effects until we hit zero, returning the found buff entry. Everything combined, the iterator function is:
 function iterateQueriableEffect(qFunc, unit, matchTexture, id, castable)
  id = id or 1; -- default value, making id optional;
  while true do
   local name, rank, texture, count, type, duration, timeleft = qFunc(unit, id, castable);
   if not name then
    break;
   end
   if string.match(texture, matchTexture) then
    id = id - 1;
    if id == 0 then
     return name, rank, texture, count, type, duration, timeleft;
    end
   end
  end
 end

==Using the iterator function to query effects==
With the background code written, we can now use it to query actual effects. WoWWiki has a list of [[Queriable buff effects|buff and debuff textures]] with associated names; suppose we wanted to know whether the player is buffed with Mark of the Wild: motw is a buff (so we need UnitBuff), player's unitid is "player":
 name, rank, texture, count, duration, timeLeft = iterateQueriableEffect(UnitBuff, "player", "Spell_Nature_Regeneration");
 if name then
  message("Player is buffed with " .. name .. " (" .. rank .. ")");
 else
  message("Player is not buffed with Mark of the Wild.");
 end
Or if we wanted to know whether the target is sapped(UnitDebuff, "target"):
 name, rank, texture, count, debuffType, duration, timeLeft = iterateQueriableEffect(UnitDebuff, "target", "Ability_Sap");
 message(name and "Target is sapped!" or "Target is not sapped"); -- shorthand if syntax -- if name is non-false and non-nil, the first message appears, otherwise, the second.
===Other interesting uses===
You can find out whether the unit is affected by a debuff you can remove (by using the castable argument, which doubles up as removable for debuffs):
 name, rank, texture, count, debuffType, duration, timeLeft = iterateQueriableEffect(UnitDebuff, unit, ".", 1, true); -- "." matches all textures, so we only have to get a return from UnitDebuff(unit, id, true) for this to return something.
You can also use the id argument to find all buffs/debuffs with the same texture on target; for example, "Spell_Fire_FireArmor" is used for almost all fire-shield effects - Fire Ward, greater protection potions, warlock imps' fire thorns spell... suppose you wanted to iterate through them:
 local i, out = 1, "";
 while true do
  local name, rank = iterateQueriableEffect(UnitBuff, unit, "Spell_Fire_FireArmor", i);
  if not name then break; end
  out = out .. (out == "" and "" or ", ") .. name;
 end
 message("Following debuffs on unit share Spell_Fire_FireArmor texture: " .. out);
Note that the last example is somewhat inefficient - you would be better off acquiring all the buff names in a single local loop rather than iterating through buffs multiple times to find all occurrences of a certain texture.

==See also==
* [[Queriable buff effects|List of buff and debuff textures]]
[[Category:HOWTOs|Identify Buffs Using Textures]]