Projet:Scribunto/Guide/Return

Introduction

Le mot-clé return sert en deux occasions :

• à la fin d'un module, pour retourner la table qui constitue le corps du module lui-même (en pratique c'est une table contenant toutes les fonctions utilisables, dont la ou les fonctions appelables par #invoke)
• pour qu'une fonction retourne le résultat de son travail à celle qui l'a appelé

Dans ce dernier cas il y a un cas particulier : une fonction destinée à être appelée depuis un modèle (la ou les fonctions « principales », celles qui sont appelées dans les #invoke) doit retourner du texte (du wikitexte), qui sera le contenu remplaçant l'appel du modèle.

Dans tous les autres cas une fonction peut retourner diverses choses :

• du texte
• des nombres
• des tables
• la valeur nil
• des fonctions
• …

Ce qui est retourné est une convention de celui qui écrit la fonction, à charge de celui qui l'utilise de savoir de quoi il retourne (c'est le cas de le dire ).

Place du return

Le return ne peut être utilisé qu'à la fin d'un bloc. Un bloc est l'ensemble de code qui va de l'élément qui l'ouvre jusqu'au end final. Ainsi une fonction est un bloc (jusqu'à son end final).
(Mais un if est aussi un bloc jusqu'à son end, ou encore aussi un while, ou bien un for et il ne faut surtout pas utiliser un return pour en sortir…)

Lorsqu'un return est rencontré la fonction dans laquelle on se trouve se termine immédiatement et l'exécution du code revient directement à l'endroit où l'appel à la fonction a eu lieu.

Utilisation avancée

Une fonction peut retourner plusieurs valeurs. Pour cela deux solutions :

• construire une table où on va ranger les différentes valeurs à retourner, et retourner cette table
• retourner plusieurs valeurs d'un coup

Contruire une table à retourner

Ceci ce fait très simplement. Dans l'exemple qui suit la fonction Toto prend en paramètre val qui doit être un nombre (entier). La fonction va construire une table résultat contenant les éléments suivants :

• suivant : le nombre augmenté de 1
• précédent : le nombre diminué de 1
• positif : un booléen valant true si val est positif ou nul et false sinon
• erreur : cet élément existe (non nil) si val est plus grand que 100 en valeur absolue

Cet exemple n'a aucune utilité pratique, on est bien d'accord…

function z.Toto(val)
  local resultat = {}  -- on crée une table vide

  -- on teste si > 100
  if (val > 100 or val < -100) then
    -- on fixe "erreur". Si on ne le fixe pas il n'existe pas et donc
    -- il vaut 'nil' si on y accède
    resultat.erreur = true -- note : identique à resultat["erreur"] = true
  end

  -- on teste si positif
  if (val >= 0) then
    resultat.positif = true
  else
    resultat.positif = false
  end
  -- on fixe suivant et précédent 
  resultat.suivant = val+1
  -- ici on ne peut faire resultat.précédent à cause de l'accent "é"
  resultat["précédent"] = val-1

  -- on retourne la table résultat avec un nil qui se balade si on prend Toto évaluant le nombre 12 
  return resultat 
end

À l'utilisation on reçoit en retour une table, dans laquelle on lira les éléments qui nous intéressent. Exemple :

(…)
  -- appel de la fonction
  local res = z.Toto(12)
  -- est-il positif
  if (res.positif) then
    -- code traitant ce cas…
  end
(…)

Retourner plusieurs valeurs

On reprend le même exemple, mais on va utiliser la possibilité de retourner plusieurs valeurs d'un coup.

function z.Toto(val)
  -- on crée des variables pour les différents éléments à retourner
  local erreur = nil -- par défaut je choisis que la variable "erreur" vaut nil
  local suivant, precedent -- ces variables valent nil mais est-ce un choix?
  local positif

  -- on teste si > 100
  if (val > 100 or val < -100) then
    erreur = true
  else --[[ j'ai choisi de retourner  nil et pour bien faire comprendre ici 
          que j'ai choisi de renvoyer nil  je mets "else" et une ligne vide ]]--
  end

  -- on teste si positif
  if (val >= 0) then
    positif = true
  else
    positif = false
  end
  -- on fixe suivant et précédent
  suivant = val+1
  -- precedent et non précédent, c'est une variable.
  precedent = val-1

  -- on retourne les éléments d'un coup en séquence
  -- note : il faut être d'accord sur l'ordre dans lequel on les retourne
  return erreur, suivant, precedent, positif
end

À l'utilisation il faut « récupérer » toutes les valeurs retournées :

(…)
  local err, suiv, prec, positif = z.Toto(12)
(…)

Notez ici qu'on déclare les variables en même temps qu'on leur affecte le retour de la fonction. On peut bien sûr utiliser des variables déjà déclarées.