4. Decorators

Decorators attach behavior or metadata to declarations. There are three kinds:

4.1 Syntax

@name@name(args)@name "string"          -- Lua call sugar@name { key = value }   -- Lua call sugar@a.b.c(args)            -- dotted path

• A decorator is @ followed by a dotted name and optional call arguments. The arguments use the same forms as a Lua call ((…), a string literal, a table constructor), and they must start on the same line as the name.
• Any number of decorators may precede a declaration, on separate lines or the same line. On exported declarations, decorators come before export (@profile export function f() … end).
• @ is not a Lua token, so decorators never conflict with Lua code.

Decorators may be applied to:

A decorator that is not applicable to its target is error E3021. User decorators on enums are not allowed because enum members are inlined at compile time, so a replacement value could never take effect. Interfaces and aliases have no runtime value.

4.2 Name resolution

A decorator name is resolved as follows (decision L22):

1. If the path is a single name that names a core decorator, the core decorator is used, always, regardless of lexical bindings.
2. If the first segment is _G, the rest of the path is looked up in the global environment at load time (@_G.MyLib.memoize).
3. Otherwise, if the first segment is a binding in lexical scope (local, import, parameter), the decorator refers to that binding.
4. Otherwise it is an error (E3020). Decorators never resolve to globals implicitly.

A user function whose name equals a core decorator can only be used as a decorator through an alias (import profile as myProfile from "./perf"). Warning W3021 is reported when a lexical binding with a core decorator's name is a function that is not a re-export of that core decorator, because the binding is ignored in decorator position. Re-exports such as import profile from "wowlua:debug" and namespace imports such as import * as reflect from "wowlua:reflect" produce no warning.

4.3 Core decorators

Always available without import.

4.4 Framework decorators

Framework decorators are exports of standard-library modules and require an import, for example:

import event from "wowlua:events"import slash from "wowlua:slash"import outOfCombat from "wowlua:combat" @outOfCombatlocal function applyPendingLayout() … end @event("PLAYER_REGEN_ENABLED")local function onCombatEnd()    applyPendingLayout()end @slash("/mya", "/myaddon")local function onCommand(msg: string) … end

They are declared with @intrinsic in the module's declaration file, so the compiler can check their arguments (for example, the event name exists and the handler's parameters match EventArgs<E>) and generate code. There are two groups:

At run time, a framework decorator is a function exported by its module, with the calling convention of user decorators. Wrapping decorators are applied like user decorators; registering decorators are called as decorator(final, ctx) after every transformation, in source order, and their results are ignored (__wl.register, decision T79).

The full list is in the Standard library.

4.5 User decorators

A user decorator is any function with a decorator signature. It runs once, at load time, when the decorated declaration is evaluated.

type DecoratorContext = {    kind: "function" | "method" | "constructor" | "getter" | "setter" | "class" | "field",    name: string,    static: boolean,              -- methods, accessors and fields    class: table?,                -- class members: the class table    file: string,                 -- source path, e.g. "src/core/cache.wowlua"    line: number,} type FunctionDecorator<F> = (fn: F, ctx: DecoratorContext) -> F?type ClassDecorator<C>    = (cls: C, ctx: DecoratorContext) -> C?type FieldDecorator       = (target: nil, ctx: DecoratorContext) -> any

• Function, method, constructor and accessor decorators receive the function and return a replacement, or nil to keep the original.
• Class decorators run after the class is finalized and its static fields are initialized, and may return a replacement class table.
• Field decorators receive (nil, ctx), because a field has no value at decoration time. Their return value is ignored (decision L8). They are for registration and metadata, e.g. registering serializable fields.
• Decorator factories are functions that return a decorator. @cached(64) calls cached(64) and applies the result.

local function memoize<A, R>(fn: (A) -> R, ctx: DecoratorContext): (A) -> R    local cache = setmetatable({}, { __mode = "k" })    return function(a: A): R        local v = cache[a]        if v == nil then v = fn(a); cache[a] = v end        return v    endend local function cached(size: number): FunctionDecorator<(number) -> ItemInfo>    return function(fn, ctx) … end            -- LRU cache with `size` entriesend @memoizelocal function heavyLookup(id: number): ItemInfo … end @cached(64)local function itemInfo(id: number): ItemInfo … end

4.5.1 Typing

The checker verifies that a user decorator's parameter types accept the target and the context (E3022). When the decorator returns a function, the declared name gets the return type of the decorator, which allows decorators that change signatures.

4.5.2 Evaluation order

Decorators of one declaration are applied in this order (decision L26):

1. @if is evaluated first. If its condition is false, the declaration and all its other decorators disappear.
2. Transforming core decorators (@profile, @trace, @inline, @checked, @unchecked, @nocheck, @debugOnly) apply innermost, directly to the function as written, regardless of their position.
3. User decorators and wrapping framework decorators are applied bottom to top, the one nearest the declaration first. Their expressions, including arguments, are evaluated top to bottom in source order before any of them is applied.
4. Registering decorators (@global, registering framework decorators) and the export assignment receive the final value, after every transformation.

@event("BAG_UPDATE")      -- 4: registers the memoized, profiled function@memoize                  -- 3: wraps the profiled function@profile                  -- 2: wraps the raw function firstlocal function onBags() … end

Within a class, member decorators run in member order, before __wl.finalize and before the class decorators (see Classes §3.1.9).

4.5.3 Lowering

@memoize@logCalls("cache")local function lookup(id: number) … end

local lookup; lookup = function(id) … enddo local __wl_d1, __wl_d2 = memoize, logCalls("cache"); local __wl_c = { kind = "function", name = "lookup", static = false, file = "src/a.wowlua", line = 3 }   lookup = __wl_d2(lookup, __wl_c) or lookup; lookup = __wl_d1(lookup, __wl_c) or lookup end

• A local function becomes local f; f = function … end, so recursive calls inside the body go through the decorated value (this matters for @memoize).
• One context table is created per decorated declaration and passed to all of its user decorators.
• The emitter places the application code on the declaration's end line to keep line numbers stable.