Fonctions standards de base.
Lua fournit tout une gamme de fonctions standards de base.
Pour obtenir plus de précisions sur une des fonctions présentes ci-desous, cliquez sur celle de votre choix.
Variable globale de la table d'environnement.
_G n'est pas une fonction, mais une variable globale qui contient l'environ-
nement global de LUA.
Lua n'utilise pas cette variable pour lui-même.
L'utilisation des fonctions setfenv( ) et getfenv( ) est déconseillée.
Pour définir l'environnement d'une fonction Lua, utilisez la nouvelle
fonction loadin( ).
Vous pouvez aussi utiliser les fonctions équivalentes de la bibliothèque
de débogage.
Affiche la version courante de Lua.
_VERSION n'est pas une fonction, mais une variable globale qui affiche
la version en cours de Lua.
Teste la bonne exécution d'une fonction.
assert( test, " ici le message d'erreur " )
Cette fonction est semblable à celle utilisée en C.
Si la condition test est false ou nil, alors une erreur est retournée.
Dans le cas contraire le traitement est effectué.
Un message facultatif peut être retourné en plus du message système.
Voir à ce sujet la fonction error( ) pour plus de détails.
Un exemple concret d'utilisation avec io.open().
Le code suivant ouvre filename en lecture et l'assigne à la variable
file, ou retourne un message d'erreur.
file = assert( io.open( filename ))
Nettoie la mémoire. (Ramasse-miettes)
collectgarbage( opt, args )
Cette fonction est une interface générique pour le garbage collector
qui remplit des fonctions différentes selon la valeur de opt:
stop Arrête le garbage collector.
restart Redémarre le garbage collector.
collect Effectue une pleine collecte.
count Retourne la mémoire totale utilisée par Lua (en ko).
step Effectue une collecte par pas.
La taille du pas est contrôlée par arg.
setpause Définit arg comme la nouvelle valeur pour la pause du
garbage collector.
setstepmul Définit arg comme la nouvelle valeur du multiplicateur
d'étape du garbage collector.
isrunning Retourne un booléen qui indique si le collecteur est
opérationnel.
Appelle un fichier LUA externe et exécute son contenu.
dofile( " ici le nom du fichier " )
Ouvre le fichier nommé et exécute son contenu comme un morceau de Lua.
Lorsqu'elle est appelée sans arguments, dofile( ) exécute le contenu
de l'entrée standard (stdin).
Retourne au programme appelant toutes les valeurs retournées par le
programme appelé.
En cas d'erreurs, dofile( ) retourne l'erreur au programme appelant.
Cette fonction ne peut être utilisée en mode protégé.
Affiche les erreurs d'une fonction.
error( " ici le message ", niveau )
Termine la dernière fonction protégée appelée et renvoie
" ici le message " comme message d'erreur.
La fonction error( ) n'a pas de retour.
L'argument " niveau " indique où obtenir la position du message d'erreur.
Avec le niveau 1 (par défaut), la position de la fonction error( ) est la
position où l'erreur sera appelée.
Le niveau 2, pointe sur la fonction qui a appelé error( ) . . . et ainsi
de suite.
Le niveau 0, évite l'ajout de la position des messages d'erreur.
Recherche l'existence d'une métatable.
getmetatable( objet )
Cette fonction retourne nil si l'objet n'a pas de métatable.
Ou la valeur associée au champ de la métatable, si cette dernière existe.
Ou la métatable de l'objet.
Itération d'une table.
ipairs( t )
Cette fonction retourne 3 valeurs:
1- une fonction d'itération.
2- la table t.
3- nil.
de sorte que la construction:
for i, v in ipairs(t) do ...body... end
parcourt l'ensemble de la table (t) de la façon suivante:
t[1], t[2], ... etc.
Charge un morceau (chunk) d'un programme Lua.
load( id, source, mode )
Si id est une fonction, load l'appellera à plusieurs reprises afin
d'obtenir tous les morceaux. Un retour sur une chaîne vide ou nil
signalera la fin du morceau.
Si id est une chaîne de caractères, alors le morceau sera cette chaîne.
S'il n'y a pas d'erreur, le morceau sera compilé comme une fonction.
S'il y a une erreur load retournera nil plus le message d'erreur.
source : est utilisé comme la source du morceau pour les messages d'erreur
et les informations de débogage.
mode : indique s'il s'agit de texte ou du binaire.
t : signifie qu'il s'agit de texte. Le morceau sera alors précompilé.
b : signifie qu'il s'agit d'un morceau en binaire.
La valeur par défaut est: bt.
Charge un "morceau" en définissant son environnement.
loadin( env, ... )
Cette fonction est similaire à load(), sauf que env définie
l'environnement de la fonction créée.
Les paramètres après env sont similaires à ceux de load().
Charge un fichier dont le nom est connu.
loadfile( "nom du fichier" )
Semblable à la load, mais charge le fichier nom du fichier comme chaîne
de caractères.
S'il n'y a aucune erreur, le retour peut être une fonction.
S'il y a une erreur, la fonction retourne nil avec un message d'erreur.
L'environnement de la fonction retourné est l'environnement global.
Charge une chaîne de caractères à partir d'un fichier.
loadstring( string, chunkname )
Semblable à load, mais charge le morceau de la chaîne donnée.
Pour charger et exécuter une chaîne donnée:
assert( loadstring( string))
Le paramètre "chunkname" est facultatif et sert à mentionner
un message en cas d'erreur de chargement.
Permet de parcourir tous les champs d'une table.
next( table, index )
Le premier argument est une table et le deuxième un index dans la table.
La fonction retourne le prochain index de la table et la valeur liée à
cet index.
Si le deuxième argument est nil, alors la fonction retournera le premier
index de la table et sa valeur associée.
Si la fonction est appelée avec le dernier index, ou avec nil dans une
table vide, alors la fonction retournera nil.
Si le deuxième argument est absent, alors il est interprété comme nil.
Lua n'a aucune déclaration de champs. Il n'y a donc aucune différence
entre un champ non existant et un champ avec une valeur nil.
Par conséquent, la fonction considère seulement les champs avec des
valeurs non nil. L'ordre dans lequel les index sont énumérés n'est pas
indiqué, même pour les index numériques.
Pour parcourir une table dans l'ordre numérique, utiliser un index
numérique pour la fonction ipairs().
Obtient une paire clé - valeur
pairs( t )
Cette fonction retourne 3 valeurs:
1- la fonction suivante.
2- la table t.
3- nil.
de sorte que la construction:
for k, v in pairs(t) do ...body... end
parcourt l'ensemble de toutes les clés-valeur de la table (t).
Appel d'une fonction en mode protégé.
pcall( f, arg1, ... )
Cette fonction appelle la fonction f avec les arguments fournis en mode
protégé. Cela signifie que toute erreur à l'intérieur de f n'est pas
propagée. pcall attrape l'erreur et renvoie un code d'état.
Son premier résultat est le code d'état (un booléen):
-true si l'appel réussit sans erreur plus tous les résultats de l'appel.
-false en cas d'erreur, plus le message d'erreur.
Imprime les valeurs contenues entre parenthèses.
print( e1, e2, e3, ... )
print( ) imprime les valeurs séparées par des virgules vers la sortie
standard.
Cette fonction n'est pas prévue pour effectuer une sortie formatée, mais
seulement comme un moyen rapide d'afficher une valeur.
Pour une sortie formatée, utilisez la fonction string.format().
print(string.format( "Pi est approximativement %.4f", 22/7 ) )
Test d'égalité.
rawequal( v1, v2 )
Vérifie si v1 est égal à v2, sans appeler de métaméthode.
Cette fonction retourne un booléen.
Obtient la valeur brute d'un champ de table.
rawget( table, index )
Obtient la valeur réelle de table[index], sans appeler de métaméthode.
table doit être une table et index peut avoir n'importe quelle
valeur différente de zéro.
Définit la valeur brute d'un champ de table.
rawset( table, index, valeur )
Place valeur dans table[index], sans appeler de métaméthode.
-table doit être une table.
-index peut avoir n'importe quelle valeur différente de zéro.
-valeur n'importe quelle valeur de Lua.
Cette fonction retourne table.
Charge un module.
require( " nom du module " )
Charge le module donné.
La fonction commence par regarder dans la table _LOADED pour déterminer
si le module a déjà été chargé.
Si il l'est, il demande en retour la valeur que le module a renvoyée
quand il a été chargé la première fois.
Sinon, il recherche un chemin pour le charger.
Un message d'erreur sera retourné en cas de problème de chargement ou
d'exécution du module, ou si require() ne peut pas trouver de chargeur.
Sélectionne les arguments.
select( index, ... )
Si index est un nombre, la fonction retourne tous les arguments après
le numéro de l'index.
Si ce nombre est négatif, la fonction retournera tous les arguments à
partir de la fin (-1 étant le dernier argument).
Sinon, index doit être une chaîne "#", et alors select() retournera le
nombre total des arguments supplémentaires qu'il a reçu.
Définit une métatable associée à une table.
setmetatable( table, metatable )
Définit une métatable pour la table donnée.
Vous ne pouvez pas changer la métatable des autres types de Lua.
Cela peut se faire uniquement à partir de C.
Si metatable est nil, alors la métatable existante sera supprimée.
Si la métatable originale possède un champ "__metatable", alors une
erreur sera générée.
Cette fonction retourne une table.
Conversion en valeur numérique.
tonumber( e, base )
tonumber( ) essaie de convertir l'argument e en nombre.
Si l'argument est déjà un nombre ou une chaîne de caractères représentant
un nombre, alors la fonction tonumber() renvoie ce nombre; autrement,
elle renvoie nil.
Un argument facultatif indique la base pour interpréter le numéro.
La base peut être n'importe quel nombre entier entre 2 et 36, inclus.
Dans les bases au-dessus de 10:
-la lettre A (en majuscule ou minuscule) représente 10,
-la lettre B représente 11, et ainsi de suite,
-ainsi la lettre Z représentant 35.
Dans la base 10 (par défaut), le nombre peut avoir une partie décimale,
ainsi qu'un exposant.
Dans d'autres bases, seuls les nombres entiers non signés sont acceptés.
tonumber("10",2) --> 2
tonumber("F",16) --> 15
tonumber("01010111",2) --> 87
Conversion en chaîne de caractères.
tostring( e )
tostring( ) reçoit un argument de n'importe quel type et le convertit
en une chaîne de caractères dans un format raisonnable.
Pour un contrôle complet de la conversion de nombre en chaîne de carac-
tères, se référer à la fonction string.format().
Si la metatable de e a un champ "__tostring", alors tostring appelle la
valeur correspondante avec e comme argument, et emploie le résultat de
l'appel en tant que résultat.
tostring convertit son argument en chaîne de caractères.
(juste son premier argument, s'il y a en plus d'un)
Indique le type d'une variable.
type( v )
Retourne le type de son seul argument, codé comme une chaîne.
Les résultats possibles de cette fonction sont "nil" (une chaîne, et
non pasla valeur nil), "number", "string", "booléen", "table",
"function","thread" et "userdata".
Appel d'une fonction avec définition du message d'erreur.
xpcall( f, err, arg1, ... )
Cette fonction est semblable à pcall(), sauf que vous pouvez définir
une nouvelle fonction de traitement des erreurs en mode protégé: err.
Aucune erreur à l'intérieur de f n'est propagée. Au lieu de cela, xpcall()
décèle l'erreur, appelle la fonction d'exception avec l'erreur d'origine,
et renvoie une chaîne de caractères comme message d'erreur (err).
Son premier résultat est le code d'état (un booléen):
-true si l'appel réussit sans erreur plus tous les résultats de l'appel.
-false en cas d'erreur, plus le message d'erreur: err.