Documentation non officielle sur la création de scripts pour X-Chat
Bonjour !
Le but de cette page est de donner aux gens une documentation rapide sur les
choses qu'ils pourront rencontrer lorsqu'ils essaieront de coder des scripts
pour X-Chat. Cela n'est pas destiné à etre un tutorial didactique sur la programmation.
Si c'est bien cela que vous cherchez, alors vous pouvez continuer à lire.
Si vous voulez écrire des scripts pour X-Chat, vous devez connaitre Perl. Avoir
eu une expérience d'écriture d'eggdrops ou de scripts pour ircII en Tcl n'est
pas nuisible non plus. Si tel n'est pas le cas, vous devrez faire très attention
à ne pas écrire des choses assez maladroites (comme les floods par exemple).
Heureusement, cela ne devrait pas prendre plus d'une semaine d'apprentissage
de Perl à des personnes intelligentes (au plus un mois) pour créer des scripts
intéressantes avec ce langage. Perl est ici avantageux car c'est un langage
très flexible.
Vous devriez également aller lire (ou au moins effleurer et bookmarquer avec
attention une copie de ce qui définit comment l'IRC fonctionne : RFC 1459 http://www.irchelp.org/irchelp/rfc1459.html.
Les autres documents que les codeurs de scripts pourraient trouver utiles sont
cette liste sympathique d'adresses de serveurs http://www.irchelp.org/irchelp/ircd/numerics.html,
et cette liste de changements pour hybrid 6 http://www.irchelp.org/irchelp/ircd/hybrid6.html
qui est un document que chacun sur EFnet devrait lire. En fait, je suggère fortement
de sauvegarder des copies de ces documents sur votre disque dur local, car vous
devrez y revenir prochainement.
Une dernière chose...Meme s'il est possible que vous entendiez dire que le RFC
1459 n'est pas suivi scrupuleusement, et ceci est partiellement vrai, faites
votre possible pour suivre les comportements compatibles avec le RFC car, autrement,
il y a de fortes chances pour que votre script n'interragisse jamais proprement
avec les autres, ou face au moins fuir beaucoup de gens. Attachez une
grande importance à la section 2.2 du RFC 1459.
X-Chat utilise Perl pour les scripts, et seulement Perl. Il est possible d'écrire
des modules, mais cela n'est vraiment pas aussi simple de créer un module en
C et le rendre stable comparé au temps de dévelopement d'un script écrit en
Perl. Pour ceux qui sont habitués au langage de script d'ircII ou à l'usage
d'eggdrop avec tcl, la seule chose qui vous manquera est que les expressions
rationelles sont très différentes, mais elle sont plus puissantes en Perl. Pour
ceux qui s'ennuient avec de faibles langages depuis trop longtemps, les ``expressions
rationelles'' permettent d'établir des correspondances entre un flux de caractères
et un modèle de flux (par exemple ``.*'' pour une suite de n'importe quels
caractères de longueur quelconque, y compris nulle).
Il y a (présentement) trois manières basiques de faire en sorte que les évènements
générés dans X-Chat appellent les sous-routines définies par vos scripts :
- Gestionnaires de message : ils gèrent les evènements déclenchés par des messages
envoyés par le serveur IRC au client.
- Gestionnaires de commande : ils gèrent les commandes entrées par l'utilisateur
(commande précédées d'un ``/'') grace au clavier.
- Gestionnaires de temps : ils gèrent les évènements décleclenchés par la bibliothèque
GTK+ (sur laquelle est batie l'interface graphique de X-Chat).
Ils sont très importants. Chaque fois que vous installez un gestionnaire, cela
lui donne une plus grande précédence par rapport aux fonctions et commandes
de X-Chat. C'est à dire que n'importe quel évènement qui aura déclenché votre
sous-routine sera gérée par votre code avant d'etre géré par le code de X-Chat
lui meme. De cette façon vous pouvez remplacer la plupart des fonctions standard
du client par vos propres sous routines. La chose à garder à l'esprit est que
si votre code sort parce qu'il a atteint la fin de votre sous routine, ou par
une instruction ``return'' explicite, le traitement de l'évènement se poursuivra
pour etre traité par n'importe quelle chose qui a définit un comportement pour
cet évènement, et puis (pourvu qu'aucune instruction ne provoque une sortie
avec le code de sortie 1) par X-Chat lui meme. IUn problème demeure cependant,
(qui est résolu par le gestionnaire de BROKERING que j'expliquerai plus tard)
et qui vient du fait que vous ne pouvez pas réellement dans quel ordre les routines
personalisées sont appelées. Normalement elles s'éxécuteront dans l'ordre dans
lesquelles elles ont été installées, mais un simple script n'a aucun moyen de
connaitre cela. Faites donc attention.
Si vous n'avez jamais entendu parlé de ``@_'' avant, alors vous n'avez évidemment
jamais programmé en Perl. Lorsqu'un gestionnaire de message se déclenche, la
ligne venant du serveur IRC est passée telle qu'elle à la routine que vous spécifiez
par l'intermédiaire de ``@_''. Lorsqu'un gestionnaire de commande est déclenché,
suels les arguments sont passés à la sous routine à travers ``@_'' et ne
sont pas séparés pour former une liste, mais conservés comme une seule chaine
de caractères. Vous devrez les analyser vous-meme avec la fonction split (je
vous conseille d'utiliser s/\s+/ /g pour réduire les espaces
multiples à un seul espace). Lorsqu'un gestionnaire de temps est déclenché,
je pense que rien n'est passé dans @_, mais ce n'est pas comme si quelque
chose de terriblement important pouvait y etre passé de toute façon. Soyez particulièrement
vigilents lorsque vous placez des gestionnaires de message pour les changements
de mode, étant donné que les modes ne sont pas divisés en événements individuels
comme pour eggdrop. La UPSIDE de cela est que X-Chat n'a pas de mode HOOKS par
lui meme, vous n'avez donc pas à vous en préocuper trop (cela n'est cependant
pas le cas avec les BROKERING handler, cependant).
Une note sur les gestionnaires de délai mérite l'attention des gens qui ont
l'habitude de programmer des scripts pour ircII/EPIC/BitchX/etc. Ils ne fonctionnent
pas de la meme façon dans X-Chat. Les gestionnaires de délai sont déclenchés
répétitivement, et (pour le moment) il n'y a aucun moyen de les supprimer une
fois qu'ils sont mis en place. Si vous insérez un gestionnaire de délai avec
un intervalle de 1000, alors votre sous routine sera déclenchée une fois toutes
les secondes indéfiniment. Prenez garde de ne pas un délai exceptionellement
cours, sous peine de faire grimper la charge du CPU anormalement.
La programmation de scripts pour X-Chat recèle de bonnes choses, et la plus
importante est que l'on arrive très bien à déterminer le contexte dans lequel
on se trouve. Si un serveur envoie quelque chose qui déclenche une gestionnaire
de message, alors vous pouvez etre sur qu'à moins de spécifier autre chose volontairement,
votre fonction IRC::print our IRC::command répondra à ce serveur et seulement
à ce serveur. Si vous avez vraiment besoin de connaitre le contexte dans lequel
vous vous trouvez, utilisez la fonction d'information IRC::get_info comme précisé
en-dessous.
-
- IRC::register(nom_de_mon_script, version, routine_arret, inutilisé);
Ceci est la première fonction que votre script devrait appeller, par exemple
:
-
- IRC::register(``mon script'', ``1.0'', ``'' , ``'');
La routine ``routine_arret'' est une fonction qui sera appelée lorsque
vous quitterez X-Chat, de façon à avoir une chance de sauver des fichiers de
configuration etc. Vous pouvez ignorer cet argument, il est optionel. L'argument
``inutilisé'' est réservé à un usage futur, pour le moment fournissez
lui ``'''''' (deux doubles apostrophes). Cette fonction retourne également
le numéro de version de X-Chat.
-
- IRC::add_message_handler(message, nom_sousroutine);
Cette fonction vous permet d'associer des sous routines à l'événement correspondant
à la réception d'un message venant du serveur auquel vous etes connectés. L'argument
``message'' correspond au deuxième TOKEN du message tel qu'il vous a été envoyé
par le serveur, et X-Chat ne sait pas que certains messages numériques sont
associés à des messages textuels, ce qui vous contraint pour le moment à mettre
en place un gestionnaire pour les deux cas si vous voulez etre surs que les
serveurs non standards ne mettent pas en défaut le résultat que vous attendez
(comprennez ici : craignez IRCNet). La ligne entière qui est envoyée par le
serveur sera passée à votre sous routie par @_. Pour le non initié, les messages
peuvent etre des choses comme ``PRIVMSG'', ``NOTICE'', ``372'', etc.
-
- IRC::::add_command_handler(commande, nom_sousroutine);
Cette fonction vous permet de lier des commandes que l'utilisateur peut entrer
à des sous routines. Les arguments y sont passés via @_, et arrivent comme
une seule chaine de caractères. @_ sera non défini si aucun argument n'est
fourni. Il est recommandé que vous vous assuriez que @_ n'est pas indéfini
et de réduire les excés d'espaces avec s/\s+/ /g avant de tenter
de découper la ligne avec la fonction split. Comme mentionné plus haut, sortir
de la sous routine en ranvoyant une valeur indéfini (ou en ne renvoyant aucune
valeur) permettra aux autres gestionnaires de commandes d'analyser la commande,
tandis que retourner une valeur égale à 1 signalera à X-Chat qu'aucune autre
analyse de la commande ne doit etre réalisée.
-
- IRC::add_timeout_handler(interval, nom_sousroutine);
Cette fonction est l'une des fonctions auxquelles il faut préter une attention
particulière lors de son utilisation. L'intervalle est mesurée en millisecondes,
vous ne devez donc pas utiliser de valeurs particulièrement petites à moins
de vouloir charger considérablement l'unité centrale. 1000 millisecondes valent
une seconde. Aucune valeur ne sera passée à la routine ``nom_sousroutine''
et les valeurs de retour n'affectent rien.
-
- IRC::add_print_handler(message, nom_sousroutine);
Cette fonction vous permet d'intercepter les messages systemes (ceux qui débutent
généralement par trois étoiles) et d'éxécuter une fonction à chaque fois qu'un
événement apparait. Les événements sont ceux que vous pouvez voir dans ``Configuration
-> Editer les événements textuels''. ``message'' est le nom de l'événement
qui génère le message que vous voulez gérer personellement (vous pouvez le trouvez
dans la boite d'édition d'événements, à la colonne ``événements''), ``nom_sousroutine''
est le nom de la sous routine qui récupérera les messages. Faites attention
: tous les arguments sont envoyés à la sosu routine à travers $_[0], séparés
par des espaces.
-
- IRC::print(texte);
C'est une fonction très simple. La seule chose faite est l'impression de la
chaine de caractère ``texte'' sur la fenetre courante. La fenetre courante
est n'importe quelle fenetre dans laquelle une commande à été entrée dans le
cas de l'appel à partir d'un gestionnaire de commande, ou dans n'importe laquelle
des fentres concernées par le message dans le cas d'un appel à partir d'un gestionnaire
de message. Comme pour de nombreux scripts perl, les nouvelles lignes ne sont
pas supposées, n'oubliez donc pas de terminer la ligne avec un \n
si vous ne voulez pas que la sortie soit ``tordue''.
-
- IRC::send_raw(texte);
Cette routine est très utile dans le sens où elle vous permet d'envoyer une
chaine de caractère au serveur IRC auquel vous etes connecté. Il est supposé
que le serveur en question est celui auquel vous vous etes connecté en premier
si le contexte n'est pas clair, sinon la chaine sera envoyée au serveur qui
aura déclenché le gestionnaire de message ou le gestionnaire de commande qui
appellé la fonction IRC::send_raw. Vous devez toujours spécifier les caractères
de nouvelle ligne ('\n') ou vous pouvez etre sur que des choses
étranges se produiront. Le message de texte que vous spécifiez doit etre un
message IRC RAW conforme (consultez le RCF 1459 pour plus de renseigenements),
n'utilisez donc pas cet outil si vous ne connaissez pas son fonctionement. De
plus, tandis que les caractères de nouvelle ligne ne sont pas supposé comme
pour la fonction IRC::print, le RFC 1459 spécifie que les caractères nouvelle
ligne sont ici la paire CR LF (carriage return et line feed), meme si la majorité
des serveurs accèpteront l'autre forme ('\n'). Il vaut mieux
employer la manière sure et utiliser ``\r\n''
plutot que '\n'.
-
- IRC::command(texte);
Cette routine vous permet d'éxécuter des commandes dans le contexte courant.
La chaine de caractere donnée par l'argument ``texte'' sera analysée par tout
ce qui analyserait une commande en temps normal, y compris vos propres gestionnaires
de commandes, faites donc attention. Les caractères de nouvelle ligne sont gérés
automatiquement.
-
- IRC::command_with_server(texte, nom_serveur);
Cette routine vous permet de spécifier le contexte de la commande qui era éxécutée
en ce qui concerne le serveur. Ce n'est pas particulièrement utile à moins que
vous gériez une connexion manuellement, mais la commande existe toujours car
elle est très utilie pour faire des choses comme gérer une connexion bnc, etc.
Les caractères de nouvelle ligne sont gérés ici également.
-
- IRC::channel_list();
Cette commande retourne une liste plate qui contient le salon courant, le serveur,
et le pseudonyme pour tous les salons dans lequel se trouve le client à un moment
donné. Vous devrez diviser la liste en groupes de trois vous meme. Aucun argument
n'est nécessaire ou utilisé (pour le moment).
-
- IRC::server_list();
Cette commande renvoie une liste plate des serveurs auxquels vous etes connectés.
-
- IRC::user_list(salon, serveur);
Cette fonction ressemble beaucoup à la commande dcc_list ci-dessous, excepté
qu'elle retourne de l'information à propos des utilisateurs qui se trouvent
dans le salon fourni en tant que premier argument (``salon''). Le second argument
est le serveur sur lequel se situe le salon donné en premier argument et est
optionel. Voici un extrait venant du fichier source de X-Chat perl.c :
XST_mPV(i, user->user); i++;
if(user->hostname)
XST_mPV(i, user->hostname);
else
XST_mPV(i, "FETCHING");
i++;
XST_mIV(i, user->op); i++;
XST_mIV(i, user->voice); i++;
XST_mPV(i, ":"); i++;
Chaque utilisateur est séparé par le caractère ``:``. Si le nom d'hote est
inconnu, la chaine de caractère ``FETCHING'' sera renvoyée.
-
- IRC::dcc_list();
Cette commande effectue sensiblement la meme chose que ``channel_list'',
en vous donnant le détail de chaque connexion DCC en cours. Je n'ai aucune idée
de ce qui est retourné car je n'ai pas eu l'occasion de trop y mettre mon nez
dedans, mais il est suffisant de dire que c'est une liste plate, et la première
fois que vous l'emploierez la signification des valeurs de cette liste plate
devrait etre assez évidente (Envoyez moi un e-mail si vous décidez de vous plonger
dans cette commande, merci !). Voici un fragment de code venant du fichier perl.c
du code source de X-Chat qui devrait vous éclairer à propos de la nature de
svaleurs retournées par cette fonction :
-
- if(dcc->nick[0])
{
XST_mPV(i, dcc->nick);
i++;
XST_mPV(i, dcc->file);
i++;
XST_mIV(i, dcc->type);
i++;
XST_mIV(i, dcc->stat);
i++;
XST_mIV(i, dcc->cps);
i++;
XST_mIV(i, dcc->size);
i++;
XST_mIV(i, dcc->resumable);
i++;
XST_mIV(i, dcc->addr);
i++;
XST_mPV(i, dcc->destfile);
i++;
}
Heureusement, cela sera suffisant pour s'apercevoir de ce qui se passe, mais
juste au cas où, jetez un coup d'oeil au fichier dp_misc.pl qui rendra le fonctionement
de ceci bien plus comprehensible dans un contexte orienté objet.
-
- IRC::get_info(entier);
Cette fonction renvoie une partie d'informations sélectionnées suivant l'entier
``entier'' passé à la commande. Voici une liste des valeurs supportées actuellement
:
- 0 - La version e X-Chat que vous utilisez.
- 1 - Le pseudonyme que vous utilisez dans le contexte serveur courant, ou le
pseudonyme par défaut si vous n'etes connecté à aucun serveur.
- 2 - Le contexte de salon courant si vous etes présent dans un salon, ou ``null''
si vous n'etes pas dans un salon ou qu'il n'existe pas de contexte de salon.
- 3 - Le nom du serveur IRC auquel vous etes actuellement connecté, ou ``null''
si vous n'etes connecté à aucun serveur.
Rien à ajouter - Zilch.
Documentation non officielle sur la création de scripts pour X-Chat
This document was generated using the
LaTeX2HTML translator Version 99.2beta6 (1.42)
Copyright © 1993, 1994, 1995, 1996,
Nikos Drakos,
Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999,
Ross Moore,
Mathematics Department, Macquarie University, Sydney.
The command line arguments were:
latex2html -no_subdir -split 0 -show_section_numbers /home/darktigrou/perl-scripting-pages.tex
The translation was initiated by Tigrou's debian attitude on 2000-11-19
Tigrou's debian attitude
2000-11-19