Aliases

An alias rewrites what you type before it goes to the server. Two decisions define one: how it matches (a leading command phrase matched literally, or a regex over the whole line) and what it does (a string to send, or a Lua function to run).

The simplest form is a word that expands, with anything you typed after it carried along:

rune.alias.exact("gc", "get all from corpse")

Type gc and the server receives get all from corpse. Type gc bag and it receives get all from corpse bag. Arguments are appended.

When the alias needs logic, such as a target variable or a condition, the action is a function instead:

rune.alias.exact("heal", function(args)
    rune.send("cast 'heal' " .. (args ~= "" and args or "self"))
end)

Both forms register the same way and are managed the same way.

Literal aliases can contain more than one word. The phrase matches the leading words of the input, and anything after it remains available as arguments:

rune.alias.exact("chat off", "chatlog off")
-- "chat off now" -> chatlog off now

Creating

rune.alias.exact(phrase, action, opts?)   -- matches leading words literally
rune.alias.regex(pattern, action, opts?)  -- Go regexp against the whole line

Exact aliases match literal words at the start of what you type. If phrases overlap, the longest active phrase wins. Whitespace separates phrase words, so chat off also matches chat off. Regex aliases see the entire input line and can capture pieces of it. They run in priority order before exact aliases are tried.

Regex patterns are validated at registration: a bad pattern raises immediately instead of failing silently at match time.

Actions

A string is a plain expansion.

• For exact aliases, whatever you typed after the matched phrase is appended: rune.alias.exact("k", "kill") turns k rat into kill rat.
• For regex aliases, %1, %2, and so on are substituted from the pattern’s captures. This is how you reorder or reuse arguments:

rune.alias.regex("^gr (.+)$", "get %1;wear %1")
-- "gr helmet" -> get helmet;wear helmet

A function runs instead of sending anything. Send what you want with rune.send. Return a string to feed it back through expansion (so aliases can build on other aliases), or return nothing to consume the input entirely.

The function’s first argument depends on the match type:

-- exact: (args, ctx). args is the text after the matched phrase.
rune.alias.exact("heal", function(args, ctx)
    if args == "" then
        rune.echo(rune.style.yellow("heal who?"))
    else
        rune.send("cast 'heal' " .. args)
    end
end)

-- regex: (matches, ctx). matches is the array of captures.
rune.alias.regex("^kk (\\w+)$", function(matches, ctx)
    rune.send("kill " .. matches[1])
end)

ctx carries line (the full input), plus name, group, and type.

Start with a string. Switch to a function when you need state or a condition.

Options

Aliases take the common options: group, priority (order among regex aliases), and once. No alias-specific extras.

The two constructors are named differently. An exact alias is named for its phrase, so rune.alias.disable("gc") works without you naming anything, and a name in opts is ignored with a notice. A regex alias is a matcher rather than a phrase, and several can match one line, so it takes name like a trigger does.

rune.alias.exact and rune.trigger.exact do not mean the same thing here. An alias phrase is something you type, so it names the alias. A trigger’s exact line is something you match, and several triggers can match it, so a trigger still needs a name.

Examples

Name a command sequence, then repeat the alias:

rune.alias.exact("round", "kill rat;loot")
rune.alias.exact("farm", "#6 round") -- six kill/loot rounds

Captures beyond the first:

-- "g 20 bob" -> "give 20 gold bob"
rune.alias.regex("^g (\\d+) (\\w+)$", "give %1 gold %2")

State shared between two aliases:

local last_target
rune.alias.regex("^kk (\\w+)$", function(matches)
    last_target = matches[1]
    rune.send("kill " .. last_target)
end)
rune.alias.exact("again", function()
    if last_target then rune.send("kill " .. last_target) end
end)

Grouped, so a pack can be switched off mid-fight:

rune.alias.exact("n", "sneak north", { group = "sneaky" })
rune.alias.exact("s", "sneak south", { group = "sneaky" })
-- /group sneaky off  -> n and s pass through unchanged

Managing

Every constructor returns a handle:

local h = rune.alias.exact("k", "kill")
h:disable()  h:enable()  h:remove()

By name: rune.alias.disable/enable/remove(name). The full list is in the API reference. In the client, /aliases shows every alias with its state, group, and the file:line that registered it.

Gotchas

• %N capture substitution only works in regex aliases. An exact alias’s string action gets the arguments appended at the end; to place them in the middle, use regex or a function.
• Patterns are Go regexp (RE2), not Lua patterns: \\d and \\w work, backreferences do not. Test a pattern with /lua rune.echo(tostring(rune.regex.match("^k (.+)$", "k rat")[1])).
• An alias that errors three times in a row is quarantined.
• Alias expansion recurses (an alias can produce another alias’s input) with a depth limit of 100 to catch loops.

Related: rune.alias reference, Triggers, Groups