Vérification de type

Luau prend en charge un système de type progressif grâce à l'utilisation d'annotations de type et d'inférence de type. Ces types sont utilisés pour fournir de meilleures avertissements, erreurs et suggestions dans l'éditeur de script.

Définir un type

Utilisez le mot clé type pour définir vos propres types :

type Vector2 = {x: number, y: number}

Modes d'inférence

Il existe trois modes d'inférence de type Luau qui peuvent être définis sur la première ligne d'un Script :

• --!nocheck — Ne pas vérifier les types.
• --!nonstrict — N'affirme les types de variable que s'ils sont explicitement annotés.
• --!strict — Affirme tous les types sur la base du type inféré ou explicitement annoté.

Les modes --!nonstrict et --!strict contrôlent la rigueur du vérificateur de type en ce qui concerne l'inférence et la vérification des types pour les variables et les fonctions. Les incompatibilités de type dans les scripts sont mises en évidence dans l'éditeur de script et apparaissent sous forme d'avertissements dans la fenêtre Analyse de script.

Pour définir un mode par défaut pour tous les scripts que vous pouvez remplacer au besoin, voir Workspace.LuauTypeCheckMode.

Types

Une annotation de type peut être définie en utilisant l'opérateur : après une variable locale, suivie d'une définition de type. Par défaut, en mode nonstrict, toutes les variables se voient assigner le type any.

local foo: string = "bar"
local x: number = 5

Il existe quatre types primitifs qui peuvent être utilisés dans une annotation :

• nil - aucune valeur
• boolean - true ou false
• number - une valeur numérique
• string - texte

Au sein de Roblox, toutes les classes, types de données et énumérations ont leurs propres types que vous pouvez vérifier :

local somePart: Part = Instance.new("Part")
local brickColor: BrickColor = somePart.BrickColor
local material: Enum.Material = somePart.Material

Pour rendre un type optionnel, utilisez un ? à la fin de l'annotation :

local foo: string? = nil

Cela permettra à la variable d'être soit le type spécifié (dans ce cas string), soit nil.

Types littéraux

Vous pouvez également convertir des chaînes et des booléens en valeurs littérales au lieu d'utiliser string et boolean :

local alwaysHelloWorld: "Hello world!" = "Hello world!"
alwaysHelloWorld = "Just hello!"  -- Erreur de type : le type '"Just hello!"' ne peut pas être converti en '"Hello world!"'

local alwaysTrue: true = false  -- Erreur de type : le type 'false' ne peut pas être converti en 'true'

Conversion de type

Parfois, vous devrez peut-être aider le vérificateur de type en convertissant explicitement une valeur en un type différent avec l'opérateur :: :

local myNumber = 1
local myString: string

myString = myNumber  -- Pas OK ; erreur de conversion de type
myString = myNumber :: any  -- OK ; toutes les expressions peuvent être converties en 'any'
local myFlag = myNumber :: boolean  -- Pas OK ; les types ne sont pas liés

Typage de fonction

Considérez la fonction suivante :

local function add(x, y)
	return x + y
end

Cette fonction additionne x à y, mais génère une erreur si l'un ou l'autre est une chaîne. Luau ne sait pas que cette fonction ne peut utiliser que des nombres. Pour éviter ce type de problème, ajoutez des types aux paramètres :

local function add(x: number, y: number)
	return x + y
end

Luau sait maintenant que la fonction prend deux nombres et affiche un avertissement si vous essayez de passer quoi que ce soit qui ne soit pas un nombre dans la fonction :

add(5, 10)
add(5, "foo")  -- Erreur de type : la chaîne ne peut pas être convertie en nombre

Pour définir un type de retour, placez un opérateur : à la fin de la définition de la fonction :

local function add(x: number, y: number): number

Pour retourner plusieurs types, placez les types entre parenthèses :

local function FindSource(script: BaseScript, pattern: string): (string, number)
	return 42, true  -- Erreurs de type
end

Définir un type fonctionnel

Un type fonctionnel peut être défini en utilisant la syntaxe (in) -> out. En utilisant les fonctions des exemples précédents, les types des fonctions sont :

type add = (x: number, y: number) -> number
type FindSource = (script: BaseScript, pattern: string) -> (string, number)

Types de table

Luau n'a pas de type table ; au lieu de cela, les types de table sont définis en utilisant la syntaxe {}. Une façon de définir des tables est d'utiliser la syntaxe {type}, qui définit un type de liste.

local numbers: {number} = {1, 2, 3, 4, 5}
local characterParts: {Instance} = LocalPlayer.Character:GetChildren()

Définissez des types d'index en utilisant {[indexType]: valueType} :

local numberList: {[string]: number} = {
	Foo = 1,
	Baz = 10
}

numberList["bar"] = true  -- Erreur de type : le booléen ne peut pas être converti en nombre

Les tables peuvent également avoir des indices de chaîne explicites définis dans un type.

type Car = {
	Speed: number,
	Drive: (Car) -> ()
}

local function drive(car)
	-- Toujours respecter la limite de vitesse
end

local taxi: Car = {Speed = 30, Drive = drive}

Variadiques

Voici une fonction qui calcule la somme d'une quantité arbitraire de nombres :

local function addLotsOfNumbers(...)
	local sum = 0

	for _, v in {...} do
		sum += v
	end

	return sum
end

Comme prévu, cette fonction peut prendre n'importe quelle valeur, et le vérificateur de type ne soulèvera pas d'avertissement si vous fournissez un type invalide, tel qu'une string.

print(addLotsOfNumbers(1, 2, 3, 4, 5))  -- 15
print(addLotsOfNumbers(1, 2, "car", 4, 5))  -- Tentative d'ajouter une chaîne à un nombre

Au lieu de cela, assignez un type à ..., tout comme vous assignez n'importe quel autre type :

local function addLotsOfNumbers(...: number)

Et maintenant, la deuxième ligne soulève une erreur de type.

print(addLotsOfNumbers(1, 2, 3, 4, 5))
print(addLotsOfNumbers(1, 2, "car", 4, 5))  -- Erreur de type : la chaîne ne peut pas être convertie en nombre

Cependant, cela ne fonctionne pas lors de l'écriture d'une définition de type fonctionnel :

type addLotsOfNumbers = (...: number) -> number  -- Type attendu, obtenu ':'

Au lieu de cela, utilisez la syntaxe ...type pour définir un type variadique.

type addLotsOfNumbers = (...number) -> number

Unions et intersections

Vous pouvez même définir un type comme deux ou plusieurs types en utilisant une union ou une intersection :

type numberOrString = number | string
type type1 = {foo: string}
type type2 = {bar: number}
type type1and2 = type1 & type2  -- {foo: string} & {bar: number}

local numString1: numberOrString = true  -- Erreur de type
local numString2: type1and2 = {foo = "hello", bar = 1}

Définir un type inféré

Vous pouvez utiliser la fonction typeof dans une définition de type pour les types inférés :

type Car = typeof({
	Speed = 0,
	Wheels = 4
})  --> Car: {Speed: number, Wheels: number}

Une façon d'utiliser typeof est de définir un type de métatable en utilisant setmetatable à l'intérieur de la fonction typeof :

type Vector = typeof(setmetatable({}::{
	x: number,
	y: number
}, {}::{
	__add: (Vector, Vector|number) -> Vector
}))

-- Vector + Vector renverrait un type Vector

Génériques

Les génériques sont à un niveau de base des paramètres pour les types. Considérez l'objet State suivant :

local State = {
	Key = "TimesClicked",
	Value = 0
}

Sans génériques, le type de cet objet serait le suivant :

type State = {
	Key: string,
	Value: number
}

Cependant, vous pourriez vouloir que le type de Value soit basé sur la valeur entrante, ce qui est là où les génériques entrent en jeu :

type GenericType<T> = T

Le <T> désigne un type qui peut être défini sur n'importe quoi. La meilleure façon de visualiser cela est comme un type de substitution.

type List<T> = {T}

local Names: List<string> = {"Bob", "Dan", "Mary"}  -- Le type devient {string}
local Fibonacci: List<number> = {1, 1, 2, 3, 5, 8, 13}  -- Le type devient {number}

Les génériques peuvent également avoir plusieurs substitutions à l'intérieur des crochets.

type Map<K, V> = {[K]: V}

Pour retravailler l'objet State d'auparavant pour utiliser un type générique :

type State<T> = {
	Key: string,
	Value: T
}

Génériques de fonction

Les fonctions peuvent également utiliser des génériques. L'exemple de State infère la valeur de T des arguments entrants de la fonction.

Pour définir une fonction générique, ajoutez un <> au nom de la fonction :

local function State<T>(key: string, value: T): State<T>
	return {
		Key = key,
		Value = value
	}
end

local Activated = State("Activated", false)  -- State<boolean>
local TimesClicked = State("TimesClicked", 0)  -- State<number>

Exportations de type

Pour permettre à un type d'être utilisé en dehors d'un ModuleScript, utilisez le mot clé export :

Types Module in ReplicatedStorage
export type Cat = {
	Name: string,
	Meow: (Cat) -> ()
}

Script Using the Types Module
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Types = require(ReplicatedStorage.Types)

local newCat: Types.Cat = {
	Name = "metatablecat",
	Meow = function(self)
		print(`{self.Name} a dit meow`)
	end
}

newCat:Meow()