Commandes avancées

Les commandes avancées sont un nouveau type de commandes introduites dans la version 2 d'Escaline. Ce type de commande permet d'aller encore plus loin dans l'élaboration de commandes pour Escaline, en autorisant les utilisateurs à les programmer avec un vrai langage de programmation. Le langage choisit pour cette tâche fût le Lua, en raison de sa simplicité, de sa légèreté, et de sa facilité à être embarqué.

Tout le monde peut créer une commande avancée, il suffit pour cela de choisir « Commande avancée » dans le formulaire de création d'une commande, et d'avoir quelque notions de programmation.

D'autre part, il faut savoir que les commandes avancées ne sont pas directement publiées sur Escaline afin que l'équipe puisse effectuer un contrôle de qualité du code, et des corrections le cas échéant. Ceci vous autorise à soumettre des commandes inachevées (parce que vous n'arrivez pas à la terminer par exemple) que l'équipe d'Escaline tentera de corriger dès qu'elle en a le temps.

Enfin, sachez que le code des commandes avancées d'Escaline est visible sur le manuel de la commande. Vous pouvez donc utiliser les commandes existantes pour vous inspirer...

Tous les liens vers la documentation de Lua, ainsi que la documentation des fonctions spécifiques à Escaline sont disponibles sur la page Référence Lua.

Récupération des arguments

Les arguments de la commande sont disponible dans le tableau argv. Le langage Lua permet de regrouper au sein d'un même tableau des valeurs indexées par des clés numériques et des chaines, cela a permis de regrouper les arguments nommés et non nommés dans la même structure.

Par exemple, pour la commande gg langue:fr site:"google image" vaches lait "prairie verte", voici comment accéder aux arguments en Lua :

argv.langue --> "fr"
argv.site --> "google image"
argv[1] --> "vaches"
argv[3] --> "pairie verte"

Autre exemple, parcourir tous les arguments non nommés :

function show(k, v)
    print(v)
end
table.foreachi(argv, show)
--> vaches
--> lait
--> pairie verte

Concaténer tous les arguments non nommés dans une chaine (peut être utile pour regrouper tous les arguments non nommés comme un seul, pour les moteurs de recherche notamment) :

termes = table.concat(argv, ' ')
print(termes) --> "vaches lait prairie verte"

Il est aussi possible d'obtenir la commande envoyée par l'utilisateur sous sa forme brute (sans aucun traitement sur les arguments) en utilisant la variable rawstring :

print(rawstring) --> 'gg langue:fr site:"google image" vaches lait "prairie verte"'

Retourner une URL ou un message

Les commandes avancées d'Escaline permettent en plus des URLs, de retourner un message d'information ou d'erreur à l'utilisateur.

Tous les retours se font à l'aide des fonctions escaline.return_url(string), escaline.return_error(string) et escaline.return_msg(string) qui retournent respectivement une URL, un message d'erreur, et un message d'information.

A noter que ces fonctions stoppent l'exécution d'une commande, vous ne pouvez donc retourner qu'une seule URL/un seul message à la fois dans une commande.

Exemples

La commande suivant est une calculatrice très simple : elle utilise l'opérateur passé en argument nommé "op" sur chaque argument non nommé.

know_ops = {'+', '-', '*'}
op = args.op

-- Valeur par défaut de op
if op == nil then
    op = '+'
end

-- op est il un opérateur connu ?
if not table.into(op, know_ops) then
    escaline.return_error('Opérateur inconnu')
end

-- Calculs
total = nil
for k, v in ipairs(args) do
    local v = tonumber(v)
    if v == nil then
        escaline.return_error('Opérande non-numérique')
    end
    if total == nil then
        total = v
    else
        if op == '+' then
            total = total + v
        elseif op == '-' then
            total = total - v
        elseif op == '*' then
            total = total * v
        end
    end
end

-- On retourne le résultat
escaline.return_message(table.concat(args, op)..' = '..total)

Un autre exemple intéressant est celui de la commande gg.