Skip to main content

Match

A match expression branches on a pattern.

Match expressions must be exhaustive, meaning that every possible pattern must be matched, i.e., have an arm handling it. The catch all arm (_), which matches any value, can be used to do this.

Match expressions also ensure that all of the left-sided arms match the same type of the scrutinee expression, and the right-sided arms are all of the same type. 

local word = match "hello" {
	["hello"] = "hi",
	["bonjour"] = "salut",
	["hola"] = "hola",
	_ = "<unknown>",
}

assert(word == "hi")

Functions​

match​

</>
Match.match(
value: T--

The value to match on

) → matcherArms<T,U>--

A matcher function to call with the match arms

A match expression branches on a pattern. A match expression has a scrutinee expression (the value to match on) and a list of patterns.

NOTE

Currently, most traditional pattern matching is not supported, with the exception of the catch all pattern (_).

A common use-case of match is to prevent repetitive if statements, when checking against various possible values of a variable: 

local function getGreetingNumber(greeting: string): number
	return match(greeting) {
		["hello, world"] = 1,
		["hello, mom"] = 2,
		_ = function(val)
			return #val
		end,
	}
end

assert(getGreetingNumber("hello, world") == 1)
assert(getGreetingNumber("hello, mom") == 2)
assert(getGreetingNumber("hello, john") == 11)
Show raw api
{
    "functions": [
        {
            "name": "match",
            "desc": "A match expression branches on a pattern. A match expression has a \nscrutinee expression (the value to match on) and a list of patterns.\n\n:::note\nCurrently, most traditional pattern matching is not supported, with \nthe exception of the catch all pattern (`_`).\n:::\n\nA common use-case of match is to prevent repetitive `if` statements, when\nchecking against various possible values of a variable:\n\n```lua\nlocal function getGreetingNumber(greeting: string): number\n\treturn match(greeting) {\n\t\t[\"hello, world\"] = 1,\n\t\t[\"hello, mom\"] = 2,\n\t\t_ = function(val)\n\t\t\treturn #val\n\t\tend,\n\t}\nend\n\nassert(getGreetingNumber(\"hello, world\") == 1)\nassert(getGreetingNumber(\"hello, mom\") == 2)\nassert(getGreetingNumber(\"hello, john\") == 11)\n\n```",
            "params": [
                {
                    "name": "value",
                    "desc": "The value to match on",
                    "lua_type": "T"
                }
            ],
            "returns": [
                {
                    "desc": "A matcher function to call with the match arms",
                    "lua_type": "matcher Arms<T, U>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 87,
                "path": "lib/match.luau"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "Arm<L, R>",
            "desc": "Represents an arm (right-side) of a match expression.",
            "lua_type": "L -- The type of the scrutinee expression or the left side of the arm",
            "fields": [
                {
                    "name": "result",
                    "lua_type": "R",
                    "desc": "The resolved value of the match expression or the right side of the arm"
                }
            ],
            "private": true,
            "source": {
                "line": 38,
                "path": "lib/match.luau"
            }
        },
        {
            "name": "Arms<T, U>",
            "desc": "Represents a constructed matcher.",
            "lua_type": "T -- The type of the scrutinee expression or the left side of the arm",
            "fields": [
                {
                    "name": "result",
                    "lua_type": "U",
                    "desc": "The resolved value of the match expression or the right side of the arm"
                }
            ],
            "private": true,
            "source": {
                "line": 51,
                "path": "lib/match.luau"
            }
        }
    ],
    "name": "Match",
    "desc": "A match expression branches on a pattern. \n\nMatch expressions must be exhaustive, meaning that every possible \npattern must be matched, i.e., have an arm handling it. The catch all \narm (`_`), which matches any value, can be used to do this.\n\nMatch expressions also ensure that all of the left-sided arms match the \nsame type of the scrutinee expression, and the right-sided arms are all\nof the same type.\n\n```lua\nlocal word = match \"hello\" {\n\t[\"hello\"] = \"hi\",\n\t[\"bonjour\"] = \"salut\",\n\t[\"hola\"] = \"hola\",\n\t_ = \"<unknown>\",\n}\n\nassert(word == \"hi\")\n```",
    "source": {
        "line": 25,
        "path": "lib/match.luau"
    }
}