Skip to main content

metatables

Library

Provides a wide range of APIs to interact with metatables in a myriad of ways.

Types​

metafield​

Type
</>
type metafield = "__index" | "__newindex" | "__mode" | "__namecall" | "__call" | "__iter" | "__len" | "__eq" | "__add" | "__sub" | "__mul" | "__div" | "__idiv" | "__mod" | "__pow" | "__unm" | "__lt" | "__le" | "__concat" | "__type"

All possible metafields in Luau.

Functions​

getrawmetatable​

</>
metatables.getrawmetatable(
object: T--

The object to get the metatable of.

) → {[metafield]: any} | nil--

The metatable of the object.

Returns the metatable of the given object, even if the __metatable metafield is set.

Hooking

This function should never be used to perform metatable hooks. Use metatables.hookmetamethod instead.

setrawmetatable​

</>
metatables.setrawmetatable(
object: T,--

The object to get the metatable of.

metatable: {[metafield]: any} | nil--

The metatable to set.

) → {[metafield]: any} | nil--

The previous metatable of the object (if it had any).

Sets the metatable of object and returns the previous metatable of it..

getmetafield​

</>
metatables.getmetafield(
object: T,--

The object with a metatable to get the metafield of.

metafield: metafield--

The metafield to get.

) → U--

The metafield of the object.

Returns the metafield (if existing) of the metatable the object has.

Errors

TypeDescription
invalid metafieldThe metatable is invalid (bad metafield name)
no metatable foundNo metatable was found on the given object.
no metafield foundNo metafield was found on the given object's metatable.

hasmetafield​

</>
metatables.hasmetafield(
object: T,--

The object to check.

metafield: metafield--

The metafield to check.

) → boolean--

If true, the object has the metafield.

Checks if the given object has a specific metafield.

Errors

TypeDescription
invalid metafieldThe metatable is invalid (bad metafield name)
no metatable foundNo metatable was found on the given object.

hasmetatable​

</>
metatables.hasmetatable(
object: T--

The object to check.

) → boolean--

If true, the object has a metatable.

Checks if the given object has a metatable.

isreadonly​

</>
metatables.isreadonly(
object: {[any]: any}--

The table to check.

) → boolean--

If true, the table is read-only.

Checks if the the given table is marked as read-only.

Usage

Normally used on metatables to allow modifying the table, but works on any table, regardless if they're a metatable or not,

hookmetamethod​

</>
metatables.hookmetamethod(
object: T,--

The object to hook.

metamethod: metafield,--

The metamethod to hook.

callback: (U...) → O...--

The callback to hook the metamethod with.

) → (U...) → O...--

The original metamethod

Hooks the given object's metatable metamethod with the provided callback.

Implementation

This function must contain an argument guard which controls that the function is given the correct number of arguments. This function should use a form of hookfunction to hook, and most NOT replace the metatable's metamethods directly.

Argument Guard

You may disable the integrated argument guard by using a vararg function. This dismisses stack size checks (it is up to you to make sure the correct number of arguments are obtained).

Hookfunction

This function may inherit errors and warnings from hookfunction.

Errors

TypeDescription
invalid metafieldThe metatable is invalid (bad metafield name)
no metatable foundNo metatable was found on the given object.
no metafield foundNo metafield was found on the given object's metatable.
metafield is not a functionThe metafield is not implemented as a function, but as a property.

restoremetamethod​

</>
metatables.restoremetamethod(
object: T,--

The object with the metatable and metamethod to restore.

metamethod: metafield--

The name of the metamethod to restore.

) → ()

Restores a metamethod hooked with hookmetamethod.

restorefunction

This function may inherit errors and warnings from restorefunction!

Errors

TypeDescription
invalid metafieldThe metatable is invalid (bad metafield name)
no metatable foundNo metatable was found on the given object.
no metafield foundNo metafield was found on the given object's metatable.
metafield is not a functionThe metafield is not implemented as a function, but as a property.
Show raw api
{
    "functions": [
        {
            "name": "getrawmetatable",
            "desc": "Returns the metatable of the given object, even if the `__metatable` metafield is set.\n\n\n:::danger Hooking\nThis function should never be used to perform metatable hooks. Use `metatables.hookmetamethod` instead.\n:::",
            "params": [
                {
                    "name": "object",
                    "desc": "The object to get the metatable of.",
                    "lua_type": "T"
                }
            ],
            "returns": [
                {
                    "desc": "The metatable of the object.",
                    "lua_type": "{ [metafield]: any } | nil"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 50,
                "path": "impl/Libraries/metatables.luau"
            }
        },
        {
            "name": "setrawmetatable",
            "desc": "Sets the metatable of `object` and returns the previous metatable of it..",
            "params": [
                {
                    "name": "object",
                    "desc": "The object to get the metatable of.",
                    "lua_type": "T"
                },
                {
                    "name": "metatable",
                    "desc": "The metatable to set.",
                    "lua_type": "{ [metafield]: any } | nil"
                }
            ],
            "returns": [
                {
                    "desc": "The previous metatable of the object (if it had any).",
                    "lua_type": "{ [metafield]: any } | nil"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 62,
                "path": "impl/Libraries/metatables.luau"
            }
        },
        {
            "name": "getmetafield",
            "desc": "Returns the metafield (if existing) of the metatable the object has.",
            "params": [
                {
                    "name": "object",
                    "desc": "The object with a metatable to get the metafield of.",
                    "lua_type": "T"
                },
                {
                    "name": "metafield",
                    "desc": "The metafield to get.",
                    "lua_type": "metafield"
                }
            ],
            "returns": [
                {
                    "desc": "The metafield of the object.",
                    "lua_type": "U"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "invalid metafield",
                    "desc": "The metatable is invalid (bad metafield name)"
                },
                {
                    "lua_type": "no metatable found",
                    "desc": "No metatable was found on the given object."
                },
                {
                    "lua_type": "no metafield found",
                    "desc": "No metafield was found on the given object's metatable."
                }
            ],
            "source": {
                "line": 78,
                "path": "impl/Libraries/metatables.luau"
            }
        },
        {
            "name": "hasmetafield",
            "desc": "Checks if the given object has a specific metafield.",
            "params": [
                {
                    "name": "object",
                    "desc": "The object to check.",
                    "lua_type": "T"
                },
                {
                    "name": "metafield",
                    "desc": "The metafield to check.",
                    "lua_type": "metafield"
                }
            ],
            "returns": [
                {
                    "desc": "If true, the object has the metafield.",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "invalid metafield",
                    "desc": "The metatable is invalid (bad metafield name)"
                },
                {
                    "lua_type": "no metatable found",
                    "desc": "No metatable was found on the given object."
                }
            ],
            "source": {
                "line": 92,
                "path": "impl/Libraries/metatables.luau"
            }
        },
        {
            "name": "hasmetatable",
            "desc": "Checks if the given object has a metatable.",
            "params": [
                {
                    "name": "object",
                    "desc": "The object to check.",
                    "lua_type": "T"
                }
            ],
            "returns": [
                {
                    "desc": "If true, the object has a metatable.",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 103,
                "path": "impl/Libraries/metatables.luau"
            }
        },
        {
            "name": "isreadonly",
            "desc": "Checks if the the given table is marked as read-only.\n\n\n:::tip Usage\nNormally used on metatables to allow modifying the table, but works on any table, regardless if they're a metatable or not,\n:::",
            "params": [
                {
                    "name": "object",
                    "desc": "The table to check.",
                    "lua_type": "{ [any]: any }"
                }
            ],
            "returns": [
                {
                    "desc": "If true, the table is read-only.",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 118,
                "path": "impl/Libraries/metatables.luau"
            }
        },
        {
            "name": "hookmetamethod",
            "desc": "Hooks the given object's metatable metamethod with the provided callback.\n\n\n:::danger Implementation\nThis function must contain an argument guard which controls that the function is given the correct number of arguments. This function should use a form of [`hookfunction`](/api/closures#hookfunction) to hook, and most NOT replace the metatable's metamethods directly.\n:::\n\n:::danger Argument Guard\nYou may disable the integrated argument guard by using a `vararg` function. This dismisses stack size checks (it is up to you to make sure the correct number of arguments are obtained).\n:::\n\n:::info Hookfunction\nThis function may inherit errors and warnings from [`hookfunction`](/api/closures#hookfunction).\n:::",
            "params": [
                {
                    "name": "object",
                    "desc": "The object to hook.",
                    "lua_type": "T"
                },
                {
                    "name": "metamethod",
                    "desc": "The metamethod to hook.",
                    "lua_type": "metafield"
                },
                {
                    "name": "callback",
                    "desc": "The callback to hook the metamethod with.",
                    "lua_type": "(U...) -> O..."
                }
            ],
            "returns": [
                {
                    "desc": "The original metamethod",
                    "lua_type": "(U...) -> O..."
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "invalid metafield",
                    "desc": "The metatable is invalid (bad metafield name)"
                },
                {
                    "lua_type": "no metatable found",
                    "desc": "No metatable was found on the given object."
                },
                {
                    "lua_type": "no metafield found",
                    "desc": "No metafield was found on the given object's metatable."
                },
                {
                    "lua_type": "metafield is not a function",
                    "desc": "The metafield is not implemented as a function, but as a property."
                }
            ],
            "source": {
                "line": 147,
                "path": "impl/Libraries/metatables.luau"
            }
        },
        {
            "name": "restoremetamethod",
            "desc": "Restores a metamethod hooked with `hookmetamethod`.\n\n\n:::info restorefunction\nThis function may inherit errors and warnings from [`restorefunction`](/api/closures#restorefunction)!\n:::",
            "params": [
                {
                    "name": "object",
                    "desc": "The object with the metatable and metamethod to restore.",
                    "lua_type": "T"
                },
                {
                    "name": "metamethod",
                    "desc": "The name of the metamethod to restore.",
                    "lua_type": "metafield"
                }
            ],
            "returns": [],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "invalid metafield",
                    "desc": "The metatable is invalid (bad metafield name)"
                },
                {
                    "lua_type": "no metatable found",
                    "desc": "No metatable was found on the given object."
                },
                {
                    "lua_type": "no metafield found",
                    "desc": "No metafield was found on the given object's metatable."
                },
                {
                    "lua_type": "metafield is not a function",
                    "desc": "The metafield is not implemented as a function, but as a property."
                }
            ],
            "source": {
                "line": 166,
                "path": "impl/Libraries/metatables.luau"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "metafield",
            "desc": "All possible metafields in Luau.",
            "lua_type": "\"__index\" | \"__newindex\" | \"__mode\" | \"__namecall\" | \"__call\" | \"__iter\" | \"__len\" | \"__eq\" | \"__add\" | \"__sub\" | \"__mul\" | \"__div\" | \"__idiv\" | \"__mod\" | \"__pow\" | \"__unm\" | \"__lt\" | \"__le\" | \"__concat\" | \"__type\"",
            "tags": [
                "Type"
            ],
            "source": {
                "line": 16,
                "path": "impl/Libraries/metatables.luau"
            }
        }
    ],
    "name": "metatables",
    "desc": "Provides a wide range of APIs to interact with metatables in a myriad of ways.",
    "tags": [
        "Library"
    ],
    "source": {
        "line": 7,
        "path": "impl/Libraries/metatables.luau"
    }
}