Projet:Scribunto/Guide

Cette page a pour but de présenter le langage Lua et surtout Scribunto, l'intégration de Lua dans MediaWiki.

Cette page n'est pas définitive. Il est probable que certains éléments soient faux ou incomplets. N'hésitez pas à compléter/corriger !

Présentation

Lua est un langage de programmation, destiné à compléter/remplacer les modèles. L'extension Scribunto permet d'exécuter du code Lua dans wikipédia.

Pour cela un espace de noms existe : Module:. Tout code Lua doit être écrit dans l'espace Module: pour pouvoir être utilisé.
Il est possible d'appeler un module directement, depuis un article ou tout autre espace de nom. Il semble toutefois qu'il soit conseillé de n'appeler des modules que depuis des modèles (note : par ailleurs la gestion des paramètres d'un module diffère selon qu'il est appelé directement ou via un modèle, il est donc plus cohérent d'uniformiser le mode d'appel).

Pourquoi un langage de programmation pour compléter voire remplacer les modèles ?

Les modèles – en tout cas certains modèles – sont complexes et utilisent de nombreux parser-functions pour adapter leur action aux paramètres (tous les {{#<mot-clé>:}}).
Les parser-functions rendent des services mais ont des défauts :

ils sont relativement limités dans leurs actions : on ne peut pas tout faire, et certaines choses sont mal faites
il posent des problèmes de performance, en particulier à cause des appels multiples que cela engendre
ils rendent la lecture des gros modèles très difficile par la densité des { } et l'aspect « tassé » du code correspondant
ils rendent par conséquent délicat la compréhension des modèles et donc leur modification (et leur maintenance)
il y a enfin des subtilités difficiles à gérer comme la répercussion (ou pas) des espaces et sauts de lignes ou encore la prise en compte (ou pas) des | (séparateurs de paramètres, qui peuvent être interprétés à différents niveaux quand il s'agit d'un modèle qui appelle un modèle qui…).

Ces raisons semblent avoir conduit à l'intégration d'un vrai langage de programmation. L'intérêt annoncé est multiple :

un vrai langage, ne dépendant pas d'un jeu réduit de fonctions de contrôle (les parser-functions)
une séparation nette de la logique de contrôle (le code) et du résultat (ce que génère le code)
un gain en lisibilité : structuration logique du code, absence de contrainte sur la mise en page, présence de commentaires…
un gain en performance (pour les serveurs)
des possibilités nouvelles, non limitées par les parser-functions actives sur fr: (par exemple les boucles)

Comment ça marche en pratique ?

La bonne pratique est d'appeler le module depuis un modèle. Cependant il est techniquement possible de l'appeler depuis un autre espace de nom, mais cette possibilité est déconseillée car :

ce n'est pas forcément très lisible pour les rédacteurs ;
les modèles sont maîtrisés par la plupart des rédacteurs, ainsi que par l'éditeur visuel ;
la gestion des paramètres n'est pas la même depuis un modèle et depuis un article, complexifiant le code des modules ;
l'impossibilité d'appeler un module depuis l'espace encyclopédique a été évoqué par les développeurs.

L'appel au modèle depuis les articles ou les autres espaces ne change pas. Dans un modèle on appelle un module avec la syntaxe suivante : {{#invoke:NomDuModule|FonctionDansLeModule|paramètres du modèle…}}
Les éléments de cet appel :

#invoke : le mot-clé indiquant un appel de module
NomDuModule : correspond à l'appel du module Module:NomDuModule
FonctionDansLeModule : le nom de la fonction du module à utiliser. Note : ceci permet d'avoir un module fournissant plusieurs fonctions différentes
paramètres : les paramètres passés par le modèle au module

Ce dernier point est important : les modules permettent de distinguer les paramètres venant du modèle de ceux venant de l'appel au modèle. Les seconds correspondent aux paramètres utilisateur, les premiers permettent − par exemple − de fixer des spécificités choisies par le modèle (la langue par exemple pour un module multilingue).

Quel type de langage est Lua ?

Note : cette section s'adresse plutôt aux personnes ayant une expérience de programmation, elle est donc rédigée en fonction de cela. Pour les autres pas d'inquiétude : ce qui suit n'est pas nécessaire pour comprendre/utiliser Lua.

Pour ceux qui sont déjà programmeurs, Lua est un langage impératif, orienté prototype. C'est une forme de programmation orientée objet dont la structuration ne déroutera pas ceux ayant l'habitude du C, du BASIC, du Pascal, du PHP, et autres langages du même style.

C'est un langage :

impératif : il décrit les actions dans l'ordre, en permettant du contrôle de flux d'exécution à partir des données existantes.
non objet : ce n'est pas un langage objet, même si la possibilité d'avoir des fonctions (y compris inline) dans des tables permet un comportement similaire. Il est même possible de créer une forme d'héritage et donc de construire une forme de classes. Presque toutes les variables sont considérées comme des objets, chercher "object" dans le manuel de référence de Mediawiki.
typé faible dynamiquement (voir Type (informatique)) : les variables ont le type de ce qu'on y met, la validation des types étant faite à l'exécution.

Il permet en outre une manipulation aisée des textes (comparaison, concaténation, sous-chaînes…), fonctionnalité nécessaire pour traiter et modifier des paramètres et pour générer le code wiki résultant.

La programmation en Lua

Quelques documents :

(fr) Lua & Scributo pour Wikimedia (sur Wikiversité)
(fr) v:Initiation au Lua avec Scribunto (sur Wikiversité, en construction)
(fr) Aide:Module (explications sommaires sur le module)
(fr) Manuel de référence de Lua sur Mediawiki (traduit de l’anglais).
(en) Manuel de référence de Lua en anglais, la référence des traductions sur Mediawiki.
(en) Lua scripting : Tutorial sur Mediawiki.
(en) Lua 5.1 Reference Manual sur le site lua.org.

Contraintes

Lua n'est pas UTF-8 en tant que langage. Cela veut dire en pratique que le langage lui-même n'accepte que des caractères ASCII.

Attention : il est possible de manipuler tous les caractères (accentués pour l'alphabet latin, mais également les symboles et caractères des autres langues), mais pas pour ce qui relève du code Lua lui-même. Ainsi les noms de fonctions et de variables ne peuvent contenir d'accents.

En pratique un nom de fonction ou de variable doit :

commencer par une lettre minuscule ou majuscule ou "_"
se continuer avec des lettres, des chiffres et le caractère "_"

Note : Lua fait la distinction minuscule/majuscule. La variable Toto est différente de la variable toto.

Note bis : la librairie ustring − qui est la librairie de manipulation de textes avec support UTF-8 − est intégrée à Scribunto. Cette librairie (accessible dans la table mw.ustring) comprend les mêmes fonctions − plus quelques autres − que la librairie string native de Lua, mais gère correctement les caractères UTF-8 (par exemple le fait que les caractères non ASCII occupent plusieurs octets, et donc que la position d'un caractères n'est pas systématiquement assimilable à la position de l'octet le représentant).

Bonnes pratiques de programmation

Note : ces bonnes pratiques ne sont pas forcément spécifiques à Lua. Il n'est toutefois pas inutile de les donner, tout le monde n'étant pas développeur.
Projet:Scribunto‎/Guide/Bonnes pratiques

Structure de base d'un code Lua

Éléments de base d'une création de module, qu'on retrouve dans tous les codes.
Projet:Scribunto‎/Guide/Structure Lua

Structuration du code (2)

Pour les utilisateurs non débutants

D'autres remarques sur la structuration générale du code.
Projet:Scribunto‎/Guide/Structure Lua 2

Traitement des paramètres, note sur la valeur nil

Les paramètres et leur gestion sont la base des modèles et des modules. Il est important de savoir comment les manipuler.
Projet:Scribunto‎/Guide/Les paramètres

La programmation, plus en détail

.

Cette section n'a pas pour vocation de ré-écrire le Lua reference manual, mais de donner un éclairage pragmatique sur certains éléments de Lua dans leur utilisation sur wikipédia.

Les variables

Le nerf de la guerre de la programmation : les variables permettent de stocker l'information en cours de traitement et donc de structurer à la fois les informations disponibles, le code (qui agit différemment en fonction des informations) et le résultat.
Projet:Scribunto‎/Guide/Les variables

Les tables

Les tables sont omniprésentes en Lua. Comprendre leur utilisation est nécessaire pour utiliser pleinement les fonctions existantes mais aussi pour bien exploiter ce langage pour créer des modules.
Projet:Scribunto‎/Guide/Les tables

Le mot-clé return

Élément indispensable en programmation impérative, le return structure l'agencement des différentes sous-parties qui composent un code.
Projet:Scribunto‎/Guide/Return

La gestion des erreurs

Parce que les utilisateurs ne sont pas des programmeurs, et que les programmeurs ne font que rarement des codes parfaits, il faut savoir gérer les problèmes.
Projet:Scribunto‎/Guide/Les erreurs

Fonctionnalités « wikipédiennes »

Certaines fonctionnalités sont fournies par mediawiki, comme par exemple obtenir le titre de l'article courant, connaître la date, tester l'existence d'un article… Il est donc nécessaire de pouvoir reproduire ces fonctionnalités dans un module.
Projet:Scribunto/Guide/Fonctionnalités wikipédiennes

Exemples de codes

Quelques exemples de modules (ou de portions de modules) réalisant quelques fonctionnalités simples.

Ces codes n'ont pas valeur de produits finis, ni parfaits. Ils illustrent certaines possibilités sur des exemples concrets et peuvent sans doute être corrigés, améliorés ou simplifiés.

Exemple et explication de l'utilisation des arguments

Module:BananesArgs

Choses en vrac

Diverses choses, en vrac, non classées, non commentées.
Projet:Scribunto‎/Guide/En vrac