next_inactive up previous


Documentation non officielle sur la création de scripts pour X-Chat


Contents

1 Introduction

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.

2 Concepts importants

2.1 Perl

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).

2.2 Gestionnaires

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 :

  1. Gestionnaires de message : ils gèrent les evènements déclenchés par des messages envoyés par le serveur IRC au client.
  2. Gestionnaires de commande : ils gèrent les commandes entrées par l'utilisateur (commande précédées d'un ``/'') grace au clavier.
  3. 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).

2.3 Codes de sortie

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.

2.4 @_

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).

2.5 Les gestionnaires de délai

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.

2.6 Les contextes

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.

3 Les fonctions elles memes

3.1 IRC::register

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.

3.2 IRC::add_message_handler

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.

3.3 IRC::add_command_handler

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.

3.4 IRC::add_timeout_handler(intervale, nom_sousroutine)

  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.

3.5 IRC::add_print_handler

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.

3.6 IRC::print

  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''.

3.7 IRC::send_raw

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'.

3.8 IRC::command

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.

3.9 IRC::command_with_server

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.

3.10 IRC::channel_list

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).

3.11 IRC::server_list

IRC::server_list();
Cette commande renvoie une liste plate des serveurs auxquels vous etes connectés.

3.12 IRC::user_list

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.

3.13 IRC::dcc_list

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.

3.14 IRC::get_info

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 :

Rien à ajouter - Zilch.

About this document ...

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


next_inactive up previous
Tigrou's debian attitude 2000-11-19