Bibliothèque base

La bibliothèque base regroupe les fonctions globales toujours disponibles dès que l'hôte a ouvert les bibliothèques standard (OpenLibs() ou, a minima, OpenBaseLib()) : elles vivent directement dans la table globale (_G), pas dans une sous-table — on écrit print(x), pas base.print(x).

print(type(42), tostring(42))
local ok, err = pcall(function() error("boom") end)
print(ok, err)

Vue d'ensemble

assert(v [, message])

Si v est vrai (ni nil ni false), retourne tous ses arguments tels quels. Sinon, lève une erreur avec message comme objet d'erreur — ou le message par défaut si message est absent.

assert(x > 0, "x doit être positif")
local a, b = assert(1, 2)   -- a = 1, b = 2

collectgarbage([opt [, arg]])

Contrôle et interroge le ramasse-miettes. opt (chaîne, défaut "collect") sélectionne l'opération : "collect" (cycle de collecte normal), "fullcollect", "nextstep", "stop", "start", "isrunning", "count" / "cyclecount" / "stepcount" (compteurs, retournent un entier), "mode" (retourne "fullcollect" ou "incremental"), "setmode" (change le mode, arg = "incremental" ou "fullcollect"), "pause" / "setpause" (lit/règle le paramètre de pause du GC, arg étant l'entier à appliquer pour "setpause").

collectgarbage("collect")
print(collectgarbage("count"))

dofile([filename])

Ouvre filename et exécute son contenu comme un script YScript, retournant toutes les valeurs renvoyées par le chunk. Sans argument, lit et exécute l'entrée standard. Contrairement à pcall, dofile ne s'exécute pas en mode protégé : une erreur dans le fichier se propage à l'appelant.

error(message [, level])

Lève une erreur avec message comme objet d'erreur ; cette fonction ne retourne jamais. Si message est une chaîne et level (entier, défaut 1) est strictement positif, error préfixe le message avec la position source correspondante : 1 (par défaut) désigne l'endroit où error a été appelé, 2 l'endroit où la fonction appelante a elle-même été appelée, etc. level = 0 n'ajoute aucune information de position.

local function check(x)
    if x < 0 then error("valeur négative", 2) end
end

getmetatable(object)

Retourne nil si object n'a pas de métatable. Sinon, si la métatable possède un champ __metatable, retourne la valeur de ce champ (mécanisme de protection). Sinon, retourne la métatable elle-même.

ipairs(t)

Retourne un triplet (fonction itératrice, t, 0) permettant d'écrire :

for i, v in ipairs(t) do
    print(i, v)
end

L'itération parcourt les paires (1, t[1]), (2, t[2]), ... et s'arrête au premier indice absent (première valeur nil rencontrée) — elle ne visite donc que la partie « tableau » séquentielle de t, pas les autres clés.

load(chunk [, chunkname [, mode [, env]]])

Compile du code YScript en une fonction, sans l'exécuter, et la retourne. chunk peut être :

• une chaîne : le code source directement ;
• une fonction : load l'appelle répétitivement (sans argument) pour obtenir des morceaux de code à concaténer ; chaque appel doit retourner une chaîne, une chaîne vide ou l'absence de valeur/nil signalant la fin du chunk.

chunkname (chaîne) sert de nom de source pour les messages d'erreur — par défaut le contenu de chunk lui-même si c'est une chaîne, ou "=(load)" si c'est une fonction. mode (chaîne, défaut "bt") restreint le format accepté : "t" (texte uniquement), "b" (bytecode précompilé uniquement), ou les deux. env, si fourni, devient l'environnement (première upvalue) de la fonction chargée.

En cas d'échec de compilation, load retourne fail (voir type) suivi du message d'erreur, au lieu de lever une erreur script — à la manière de io.open :

local f, err = load("return 1 +")
if not f then
    print("erreur de compilation : " .. err)
end

local ok = load("print('hello')")
ok()   --> hello

loadfile([filename [, mode [, env]]])

Identique à load, mais le code est lu depuis le fichier filename (ou l'entrée standard si absent) plutôt que d'une chaîne ou d'une fonction.

next(table [, index])

Permet de parcourir tous les champs de table. Appelé avec index = nil (ou omis), retourne le premier indice de la table et sa valeur associée. Appelé avec un indice existant, retourne l'indice suivant et sa valeur. Retourne nil (seul) quand index était le dernier indice, ou pour une table vide — next(t) seul permet donc de tester si t est vide. L'ordre de parcours n'est pas spécifié, y compris pour les indices numériques.

Ne pas assigner de valeur à un champ absent pendant un parcours ; modifier des champs existants (y compris les mettre à nil) est en revanche permis.

pairs(t)

Si la métatable de t définit __pairs, l'appelle avec t et retourne ses trois premiers résultats. Sinon, retourne le triplet (next, t, nil), permettant :

for k, v in pairs(t) do
    print(k, v)
end

qui parcourt toutes les paires clé/valeur de t (contrairement à ipairs, qui ne parcourt que la séquence 1..n).

pcall(f [, arg1, ···])

Appelle f(arg1, ···) en mode protégé : une erreur levée pendant l'appel n'est pas propagée à l'appelant. Premier résultat : un booléen, true si l'appel s'est terminé sans erreur — dans ce cas, tous les résultats de l'appel suivent ce booléen. En cas d'erreur, pcall retourne false suivi de l'objet d'erreur. Les erreurs interceptées par pcall ne déclenchent pas de gestionnaire de message.

local ok, result = pcall(function() return 10 / 0 end)
local ok2, err2 = pcall(error, "échec voulu")
print(ok2, err2)   --> false   échec voulu

print(···)

Affiche tous ses arguments sur la sortie standard, convertis en chaîne comme tostring, séparés par une tabulation, suivis d'un saut de ligne. Prévu pour un affichage rapide/du débogage — pour un formatage précis, utiliser string.format (et io.write pour écrire sans saut de ligne implicite).

rawequal(v1, v2)

Compare v1 et v2 sans invoquer la métaméthode __eq. Retourne un booléen.

rawget(table, index) / rawset(table, index, value)

rawget lit table[index] sans passer par __index. rawset écrit table[index] = value sans passer par __newindex, et retourne table.

rawlen(v)

Retourne la longueur de v (qui doit être une table ou une chaîne) sans invoquer la métaméthode __len. Erreur si v n'est ni l'un ni l'autre.

select(index, ···)

Si index vaut la chaîne "#", retourne le nombre d'arguments supplémentaires reçus (hors index lui-même). Sinon index doit être un nombre : select retourne tous les arguments à partir de la position index ; un index négatif compte depuis la fin (-1 désigne le dernier argument).

print(select("#", "a", "b", "c"))   --> 3
print(select(2, "a", "b", "c"))     --> b   c

setmetatable(table, metatable)

Définit la métatable de table. Si metatable est nil, retire la métatable existante. Retourne table. Si la métatable actuelle possède un champ __metatable, lève une erreur (protection contre le changement de métatable). Pour changer la métatable d'un type autre qu'une table, voir la bibliothèque debug.

tonumber(e [, base])

Sans base : tente de convertir e en nombre. Si e est déjà un nombre, ou une chaîne convertible (avec espaces et signe en tête/en fin tolérés), retourne ce nombre (entier ou flottant selon la syntaxe) ; sinon retourne fail.

Avec base (entier entre 2 et 36 inclus) : e doit être une chaîne représentant un entier dans cette base ('A'-'Z'/'a'-'z' valant 10 à 35 au-delà de la base 10). Retourne fail si e n'est pas un numéral valide dans cette base.

print(tonumber("42"))        --> 42
print(tonumber("3.14"))      --> 3.14
print(tonumber("ff", 16))    --> 255
print(tonumber("xyz"))       --> nil (fail)

tostring(v)

Convertit v, quel que soit son type, en une chaîne lisible. Si la métatable de v définit __tostring, tostring appelle cette fonction avec v en argument et retourne son résultat. Sinon, si la métatable définit un champ __name (chaîne), ce nom peut apparaître dans le résultat par défaut. Pour un contrôle précis du formatage des nombres, utiliser string.format.

type(v)

Retourne le type de v sous forme de chaîne : "nil", "number", "string", "boolean", "table", "function", "thread" ou "userdata". Lève une erreur si aucun argument n'est fourni.

warn(msg1, ···)

Émet un avertissement composé de la concaténation de tous ses arguments (qui doivent tous être des chaînes). Par convention, un message à un seul élément commençant par @ est un message de contrôle destiné au système d'avertissement lui-même : "@off" coupe l'émission des avertissements, "@on" la réactive ; tout autre message de contrôle inconnu est ignoré.

xpcall(f, msgh [, arg1, ···])

Identique à pcall, mais installe msgh comme gestionnaire de message : si f lève une erreur, msgh est appelé (avec l'objet d'erreur) avant que la pile ne soit dépilée, ce qui permet par exemple d'y récupérer une trace d'appel.

_G

La table globale elle-même — _G.x et x désignent la même variable globale.

_VERSION

Chaîne indiquant la version du moteur YScript.