Files
ClassicAPI/AddOns/!!!ClassicAPI/Util/MacroOptions.lua
T
Brues a33146241e feat(macro): make [button:N] read the click it is running inside
The condition existed but was a stub: it matched only "1" / "leftbutton"
and always passed, because nothing on this client could say which mouse
button had driven the current click. GetMouseButtonClicked can now answer
that, so the condition asks it.

Numbers use the modern API order -- 1 left, 2 RIGHT, 3 middle, 4, 5 --
which is deliberately NOT the order of the engine's internal click
bitmask (where 2 is the middle button); that mask never reaches Lua. A
name is matched as written, so [button:rightbutton] and [button:2] are
the same test, case-insensitively.

Outside a click the answer stays "left button". That is not a cosmetic
default: Macro::ShowTooltip re-evaluates conditional directives off the
world tick with no click in progress, so a nil-means-no-match rule would
change which icon a `/cast [button:2] X; Y` macro displays at rest. The
engine's own no-argument Button:Click() means the left button, so it is
also the honest resting answer for a state-driver poll.

Verified in-game with all five buttons, both directly from OnClick and
through a real macro body -- click -> attribute macro ->
EXECUTE_CHAT_LINE -> SlashCmdList -> SecureCmdOptionParse, which
confirms the click context survives the whole chain -- plus the name
form, the btn alias, and the no-click resting answer.
2026-09-15 01:38:38 -05:00

621 lines
21 KiB
Lua

-- SecureCmdOptionParse(options) -> value[, target]
--
-- Backports the macro-conditional parser (added in 2.0) so a modern option
-- string like "[combat,@focus] Foo; [nostealth] Bar; Baz" resolves to the
-- value of the first matching clause. Used by Util/SecureStateDriver.lua and
-- callable by any macro / click-verb system that wants Blizzard's grammar.
--
-- Grammar reverse-engineered from the 3.3.5 Wow.exe (functions 0x005f0df0
-- clause splitter, 0x005f0bb0 group parser, 0x005f0040 condition parser,
-- 0x005ef5c0 evaluator), so it matches Blizzard's own precedence exactly:
-- * clauses are split on ';' at bracket depth 0;
-- * a clause is zero or more [group] blocks followed by a value (the text
-- after the last ']', edge-trimmed -- may be empty);
-- * a clause with NO groups always matches; groups are OR'd (first pass
-- wins); conditions inside a group are comma-split and AND'd;
-- * an '@unit' or 'target=unit' piece (case-insensitive) sets the group's
-- target; every other piece is a condition, optionally negated by a 'no'
-- prefix (stripped only when the piece is >= 3 chars) and optionally
-- carrying ':a/b/c' args (each trimmed, multiple args OR'd);
-- * the match returns the clause value plus the passing group's target
-- token (nil when the passing group set none).
--
-- The 33 condition keywords are the 3.3.5 set, matched case-sensitively, plus
-- one ClassicAPI extension: [known:spellID] / [known:name].
-- Where a keyword's underlying state does not exist on 1.12 (flying, flyable,
-- vehicleui, unithasvehicleui) the condition is a constant false; where 1.12
-- only has a partial answer (spec is always primary; actionbar defaults to the
-- resting state, as does button when no click is running) the closest honest
-- mapping is used. An UNKNOWN keyword
-- is a hard false with a one-time warning -- never a silent pass -- so a typo
-- can't wrongly show a frame. See docs/API.md for the full contract.
--
-- Each unique options string is parsed ONCE into a clause structure and cached
-- (a plain table, matching the 3.3.5 C hash -- entries are never evicted, and
-- the set is bounded by the strings addons actually register). Evaluation then
-- just walks the structure calling predicate functions, so the 0.2s driver
-- poll re-parses nothing.
local type = type;
local tonumber = tonumber;
local strlen = string.len;
local strsub = string.sub;
local strlower = string.lower;
local strmatch = string.match;
local gmatch = string.gmatch;
local function Trim(s)
return strmatch(s, "^%s*(.-)%s*$") or "";
end
local function AlwaysTrue()
return true;
end
local function AlwaysFalse()
return false;
end
-- ---------------------------------------------------------------------------
-- Query helpers used by more than one predicate
-- ---------------------------------------------------------------------------
-- The shapeshift-BAR index of the active form (1-based), or 0 when formless.
-- [stance:N] / [form:N] number by this bar order (druid 1 = Bear, 3 = Cat),
-- which is NOT the DBC form id GetShapeshiftFormID() returns -- so the ':N'
-- form deliberately does not use that faster reader.
local function GetCurrentFormIndex()
for i = 1, GetNumShapeshiftForms() do
local _, _, active = GetShapeshiftFormInfo(i);
if active then
return i;
end
end
return 0;
end
-- True when any equipped item (slots 1..19) matches `want` by localized item
-- type, subtype, or equip-location slot name. C_Item.GetItemInfoInstant is
-- synchronous and link-accepting; worn gear is always cached, and a nil field
-- simply fails the match (fail-safe).
local function IsEquippedTypeMatch(want)
want = strlower(want);
for slot = 1, 19 do
local link = GetInventoryItemLink("player", slot);
if link then
local _, itemType, itemSubType, equipLoc = C_Item.GetItemInfoInstant(link);
if (itemType and strlower(itemType) == want)
or (itemSubType and strlower(itemSubType) == want) then
return true;
end
if equipLoc and equipLoc ~= "" then
local slotName = _G[equipLoc];
if slotName and strlower(slotName) == want then
return true;
end
end
end
end
return false;
end
-- True when a spell named `want` (case-insensitive) is in the player's
-- spellbook. This is the name form of [known:...]. There is no name -> id
-- resolver, so a name can only resolve against castable spellbook entries;
-- talents / passives / profession recipes that IsPlayerSpell reports for a
-- spell id are not found by name.
local function IsSpellNameKnown(want)
want = strlower(want);
local i = 1;
while true do
local name = GetSpellName(i, "spell");
if not name then
return false;
end
if strlower(name) == want then
return true;
end
i = i + 1;
end
end
-- ---------------------------------------------------------------------------
-- Condition predicates -- signature f(target, args) -> truthy.
-- `args` is nil for a bare condition, else { n = <count>, [i] = <trimmed> };
-- multiple args are OR'd.
-- ---------------------------------------------------------------------------
local CONDITIONS = {};
CONDITIONS[""] = AlwaysTrue; -- empty keyword ([] / [ ]) always matches
CONDITIONS.combat = function()
return UnitAffectingCombat("player");
end
CONDITIONS.exists = function(target)
return UnitExists(target);
end
CONDITIONS.dead = function(target)
return UnitIsDeadOrGhost(target);
end
CONDITIONS.help = function(target)
return UnitCanAssist("player", target);
end
CONDITIONS.harm = function(target)
return UnitCanAttack("player", target);
end
CONDITIONS.party = function(target)
return UnitPlayerOrPetInParty(target);
end
CONDITIONS.raid = function(target)
return UnitInRaid(target);
end
-- [group] = in any group; [group:party] true in a party OR raid (raid members
-- occupy party subgroups, matching retail); [group:raid] true only in a raid.
CONDITIONS.group = function(target, args)
local inParty = GetNumPartyMembers() > 0;
local inRaid = GetNumRaidMembers() > 0;
if args then
for i = 1, args.n do
local a = strlower(args[i]);
if a == "raid" then
if inRaid then return true; end
elseif a == "party" then
if inParty or inRaid then return true; end
end
end
return false;
end
return inParty or inRaid;
end
CONDITIONS.stance = function(target, args)
if args then
local cur = GetCurrentFormIndex();
for i = 1, args.n do
if tonumber(args[i]) == cur then return true; end
end
return false;
end
return GetShapeshiftFormID() ~= 0;
end
CONDITIONS.stealth = function()
return IsStealthed();
end
CONDITIONS.mounted = function()
return IsMounted();
end
CONDITIONS.swimming = function()
return IsSwimming();
end
CONDITIONS.indoors = function()
return IsIndoors();
end
CONDITIONS.outdoors = function()
return IsOutdoors();
end
-- Vanilla has one permanent spec: [spec] and [spec:1] pass, higher indices fail.
CONDITIONS.spec = function(target, args)
if args then
for i = 1, args.n do
if args[i] == "1" then return true; end
end
return false;
end
return true;
end
CONDITIONS.modifier = function(target, args)
if args then
for i = 1, args.n do
local a = strlower(args[i]);
if a == "shift" then
if IsShiftKeyDown() then return true; end
elseif a == "ctrl" then
if IsControlKeyDown() then return true; end
elseif a == "alt" then
if IsAltKeyDown() then return true; end
end
end
return false;
end
return IsShiftKeyDown() or IsControlKeyDown() or IsAltKeyDown();
end
-- [button:N] numbers the mouse buttons the way the rest of the modern API
-- does -- 1 left, 2 RIGHT, 3 middle, 4, 5. That is deliberately not the order
-- of the engine's internal click bitmask (where 2 is the middle button), which
-- never reaches Lua. A name is matched as written, so a button clicked with an
-- explicit name (`someButton:Click("LeftButton")`) answers [button:leftbutton]
-- as well as [button:1].
local BUTTON_NUMBER_NAMES = {
["1"] = "leftbutton",
["2"] = "rightbutton",
["3"] = "middlebutton",
["4"] = "button4",
["5"] = "button5",
};
CONDITIONS.button = function(target, args)
if args then
-- GetMouseButtonClicked() is the button of the click this macro is
-- running inside. It reads nil when no click is running -- a state
-- driver poll, or the re-evaluation behind a macro's #showtooltip
-- display -- and the engine's own no-argument Button:Click() means the
-- left button, so that is the resting answer.
local current = strlower(GetMouseButtonClicked() or "LeftButton");
for i = 1, args.n do
local a = strlower(args[i]);
if (BUTTON_NUMBER_NAMES[a] or a) == current then return true; end
end
return false;
end
return true;
end
CONDITIONS.actionbar = function(target, args)
if args then
local page = CURRENT_ACTIONBAR_PAGE or 1;
for i = 1, args.n do
if tonumber(args[i]) == page then return true; end
end
return false;
end
return true;
end
CONDITIONS.bonusbar = function(target, args)
local offset = GetBonusBarOffset();
if args then
for i = 1, args.n do
if tonumber(args[i]) == offset then return true; end
end
return false;
end
return offset > 0;
end
CONDITIONS.pet = function(target, args)
if args then
local petName = UnitName("pet");
local petFamily = UnitCreatureFamily("pet");
petName = petName and strlower(petName);
petFamily = petFamily and strlower(petFamily);
for i = 1, args.n do
local a = strlower(args[i]);
if a == petName or a == petFamily then return true; end
end
return false;
end
return UnitExists("pet");
end
-- ClassicAPI cedes the global name UnitChannelInfo/ChannelInfo to addons, so the
-- player's channel state is read through the namespaced C_Spell.ChannelInfo().
CONDITIONS.channeling = function(target, args)
local name = C_Spell.ChannelInfo();
if args then
if not name then return false; end
name = strlower(name);
for i = 1, args.n do
if strlower(args[i]) == name then return true; end
end
return false;
end
return name ~= nil;
end
CONDITIONS.equipped = function(target, args)
if not args then return false; end -- [equipped] with no type never matches
for i = 1, args.n do
if IsEquippedTypeMatch(args[i]) then return true; end
end
return false;
end
CONDITIONS.cursor = function()
return GetCursorInfo() ~= nil;
end
-- ClassicAPI extension (not a 3.3.5 conditional). [known:spellID] uses
-- IsPlayerSpell (broad knowledge -- spellbook, talents, recipes, racials);
-- [known:name] falls back to a spellbook name scan (see IsSpellNameKnown).
CONDITIONS.known = function(target, args)
if not args then return false; end
for i = 1, args.n do
local a = args[i];
local id = tonumber(a);
if id then
if IsPlayerSpell(id) then return true; end
elseif IsSpellNameKnown(a) then
return true;
end
end
return false;
end
-- No such state on 1.12.
CONDITIONS.flying = AlwaysFalse;
CONDITIONS.flyable = AlwaysFalse;
CONDITIONS.vehicleui = AlwaysFalse;
CONDITIONS.unithasvehicleui = AlwaysFalse;
-- Aliases (share the function reference).
CONDITIONS.form = CONDITIONS.stance;
CONDITIONS.mod = CONDITIONS.modifier;
CONDITIONS.btn = CONDITIONS.button;
CONDITIONS.bar = CONDITIONS.actionbar;
CONDITIONS.worn = CONDITIONS.equipped;
-- ---------------------------------------------------------------------------
-- Parser
-- ---------------------------------------------------------------------------
local warned = {};
-- Keywords met during the current `ParseOptions` run that this parser does
-- not own. A condition we cannot evaluate means the options were written for
-- another macro parser's dialect, so the fact is recorded on the parsed
-- clause set rather than reported here. The caller decides what to do with
-- it: a command the player ran names the keyword, and the macro-display scan
-- leaves the macro alone.
local parseUnknowns;
-- piece -> { pred = fn, neg = bool, args = { n, [i] } or nil }
local function ParseCondition(piece)
local neg = false;
if strlen(piece) >= 3 and strsub(piece, 1, 2) == "no" then
neg = true;
piece = strsub(piece, 3);
end
local keyword, argstr = strmatch(piece, "^([^:]*):?(.*)$");
keyword = Trim(keyword);
local args;
if argstr ~= "" then
args = { n = 0 };
for a in gmatch(argstr .. "/", "([^/]*)/") do
args.n = args.n + 1;
args[args.n] = Trim(a);
end
end
local pred = CONDITIONS[keyword];
if not pred then
if not parseUnknowns then
parseUnknowns = { n = 0 };
end
parseUnknowns.n = parseUnknowns.n + 1;
parseUnknowns[parseUnknowns.n] = keyword;
pred = AlwaysFalse;
neg = false; -- an unknown keyword is a hard false
end
return { pred = pred, neg = neg, args = args };
end
-- group body -> { target = str or nil, n, [i] = cond }
local function ParseGroup(body)
local group = { n = 0 };
-- Sentinel comma so a run ending at end-of-body (and an empty body) yields
-- a piece; each piece is (non-comma)* up to a comma.
for piece in gmatch(body .. ",", "([^,]*),") do
piece = Trim(piece);
if strsub(piece, 1, 1) == "@" then
group.target = Trim(strsub(piece, 2));
elseif strlower(strsub(piece, 1, 7)) == "target=" then
group.target = Trim(strsub(piece, 8));
else
group.n = group.n + 1;
group[group.n] = ParseCondition(piece);
end
end
return group;
end
-- clause text -> { value = str, groups = { n, [i] = group } }
local function ParseClause(text)
local groups = { n = 0 };
-- Greedy up to the LAST ']' splits the [group] blocks from the value.
local body, value = strmatch(text, "^%s*(.*%])(.*)$");
if not body then
return { value = Trim(text), groups = groups };
end
for groupBody in gmatch(body, "%[([^%]]*)%]") do
groups.n = groups.n + 1;
groups[groups.n] = ParseGroup(groupBody);
end
return { value = Trim(value), groups = groups };
end
-- options -> { n, [i] = clause, unknown = { n, [i] = keyword } or nil }.
-- Splits on ';' at bracket depth 0.
local function ParseOptions(options)
parseUnknowns = nil;
local clauses = { n = 0 };
local len = strlen(options);
local pos = 1;
while pos <= len + 1 do
local i = pos;
local depth = 0;
while i <= len do
local c = strsub(options, i, i);
if c == "[" then
depth = 1;
elseif c == "]" then
depth = 0;
elseif c == ";" and depth == 0 then
break;
end
i = i + 1;
end
clauses.n = clauses.n + 1;
clauses[clauses.n] = ParseClause(strsub(options, pos, i - 1));
pos = i + 1;
end
clauses.unknown = parseUnknowns;
parseUnknowns = nil;
return clauses;
end
-- ---------------------------------------------------------------------------
-- Evaluation
-- ---------------------------------------------------------------------------
local cache = {};
-- `@unit` takes a character name as well as a token (`[target=Feral]`), and a
-- name has to be searched for in the object manager. That search is the one
-- expensive step here, so a pass remembers what it already found. The table
-- is only built once a pass meets a name, and the next pass drops it: a token
-- kept across passes could name a different unit by then.
local passNames;
local function TokenForName(name)
if passNames then
local cached = passNames[name];
if cached ~= nil then
return cached or nil; -- false records "nobody there"
end
else
passNames = {};
end
local token = UnitTokenFromName(name);
passNames[name] = token or false;
return token;
end
-- A `@unit` piece as something the engine's unit functions accept, with no
-- question asked about whether a unit is there. `IsUnitToken` tells a token
-- from a name by asking the engine's own resolver, and it does not go looking
-- for the unit -- which is what the conditions do next anyway.
local function TokenForTarget(target)
if IsUnitToken(target) then
return target;
end
return TokenForName(target);
end
-- Whether a `@unit` piece has a unit behind it right now. The pcall tells a
-- token from a name in one step: the engine raises for a string that names no
-- token, which is exactly the case to hand to the by-name search. That also
-- keeps a typo failing the group instead of the caller.
local function TargetExists(target)
local ok, exists = pcall(UnitExists, target);
if ok then
return exists and true or false;
end
local token = TokenForName(target);
return token ~= nil and UnitExists(token) and true or false;
end
-- Targets that do not name a unit. `none` clears the target and `cursor`
-- names a world position, so neither can be tested with UnitExists and both
-- always pass the existence gate below.
local NON_UNIT_TARGETS = { none = true, cursor = true };
local function GroupPasses(group)
local target = group.target;
local named = target and not NON_UNIT_TARGETS[strlower(target)];
if group.n == 0 then
-- A group that only names a unit (`[@mouseover]`) passes only while
-- that unit exists, so `[@mouseover][] Spell` falls through to the
-- next group when nothing is moused over. A bare `[]` and the
-- non-unit targets always pass. Groups with conditions leave
-- existence to them (`[@focus,noexists]` still works).
if not named then
return true;
end
return TargetExists(target);
end
if named then
-- The conditions ask the engine about this unit, so a name has to
-- become a token first. Existence is theirs to test, so it is not
-- asked for here.
target = TokenForTarget(target);
if not target then
return false;
end
end
target = target or "target";
for i = 1, group.n do
local cond = group[i];
local ok = cond.pred(target, cond.args);
if cond.neg then
ok = not ok;
end
if not ok then
return false;
end
end
return true;
end
-- Returns the matched value, the passing group's target, and the name of the
-- first condition the options use that this parser does not own.
--
-- That third value marks the options as another macro parser's dialect. A
-- caller that scans macro bodies it did not write passes `quiet` and reads it,
-- so it can leave such a macro alone instead of naming a keyword the player
-- has no reason to fix.
function SecureCmdOptionParse(options, quiet)
if type(options) ~= "string" then
error("Usage: SecureCmdOptionParse(\"options\")");
return nil; -- WoW's error() may not unwind
end
-- Start of a pass: drop what the last one resolved by name. Nothing is
-- allocated unless a name was actually met, so the all-token case (the
-- common one, polled several times a second) costs nothing here.
if passNames then
passNames = nil;
end
local clauses = cache[options];
if not clauses then
clauses = ParseOptions(options);
cache[options] = clauses;
end
-- Name each keyword once, for a caller that wants to hear about it.
local unknown = clauses.unknown;
if unknown and not quiet then
for i = 1, unknown.n do
local keyword = unknown[i];
if not warned[keyword] then
warned[keyword] = true;
print("SecureCmdOptionParse: unknown condition '" .. keyword .. "'");
end
end
end
local foreign = unknown and unknown[1] or nil;
for i = 1, clauses.n do
local clause = clauses[i];
local groups = clause.groups;
if groups.n == 0 then
return clause.value, nil, foreign;
end
for j = 1, groups.n do
if GroupPasses(groups[j]) then
return clause.value, groups[j].target, foreign;
end
end
end
return nil, nil, foreign;
end