]>

# Le manuel de KSirc

Andrew
Stanley-Jones

    asj@chowtown.cban.com

    Ksirc/Sirc Homepage

Cette documentation décrit KSirc 0.9

KDE
KMail
mél
messagerie électronique

## Installation

Installation des fichiers binaires

- SI VOUS N'AVEZ PAS INSTALLE KDE

      	cd /usr/local/
      	tar -zxvf <ksirc>
      	tar -zxvf kdehelp-netscape.tgz

  Vous pouvez ensuite lancer ksirc en tapant "ksirc". Rappelez-vous qu'il faut avoir installé perl5 sur votre machine.

  Si vous voulez une aide en ligne et si vous n'avez pas installé KDE, avec netscape vous obtenir kdehelp-netscape.tgz depuis ksirc.org/pub/ksirc

- Pour ceux qui ont installé KDE

      	cd $KDEDIR/..
      	tar -zxvf <ksirc>

  Vous pouvez ensuite lancer ksirc en tapant "ksirc".

## Couleurs de ksirc

KSirc suit le modèle des couleurs utilisées par mIrc avec une légère modification, pour une utilisation personnelle plus performante.

    <fg> == avant-plan
    <bg> == arrière-plan
    &lsqb;&rsqb; == options

### Compatibilité avec mIrc

Format:

- 0x03<fg>&lsqb;,<bg>&rsqb; définit l'avant-plan et l'arrière-plan

- 0x03 effectue une réinitialisation avec les valeurs par défaut pour CETTE ligne

### KSirc natif

Format:

- ˜<fg>&lsqb;,<bg>&rsqb; définit l'avant-plan et l'arrière-plan

- ˜c réinitialise tp par défaut

- ˜b définit les polices en gras

- ˜u définit le soulignement

- ˜i définit les italiques

- ˜r définit le soulignement

Pourquoi ai-je modifié ksirc pour utiliser ˜ au lieu de 0x03 (ˆC)? Eh bien il est difficile d'utiliser 0x03 dans les scripts et toutes les fonctions en langage C ne semblent pas lui convenir. L'expression <letter> permet également davantage de commandes sans écraser les changements ultérieurs.

### Liste des Couleurs

1. blanc

2. noir

3. bleu marine

4. vert

5. rouge

6. marron

7. violet

8. orange

9. jaune

10. vert clair

11. cyan

12. cyan clair

13. bleu outremer

14. rose

15. gris

16. gris clair

### Envoi du Gras, Souligné, Inversé et Couleur

Vous pouvez utiliser les combinaisons de touches suivantes pour insérer des codes de contrôle dans du texte.

- Control-B pour le texte en gras

- Control-U pour le texte souligné

- Control-R pour le texte inversé

- Control-K pour le texte coloré

- Control-O pour le texte en clair

### Exemples

Pour souligner un seul mot dans une phrase :

1. Taper Control-U

2. Taper le mot

3. Taper Control-U à nouveau

Seul le texte qui est entouré par les codes de début et de fin sera affecté. Vous pouvez utiliser cette méthode avec tous les autres codes de contrôle.

Le code de contrôle Control-K est légèrement différent car il vous autorise à spécifier un numéro de couleur. Pour colorer un seul mot dans une phrase :

1. Taper Control-K

2. Taper un nombre entre 0 et 15

3. Taper le mot

4. Taper Control-K à nouveau

Si vous voulez également changer la couleur d'arrière-plan d'un mot, vous devez taper deux nombres séparés par une virgule, au lieu d'un seul nombre. Le premier nombre représente la couleur du texte, le second la couleur de l'arrière-plan. Les couleurs sont classées de 0 à 15, l'index est décrit dans la précédente section.

Vous pouvez entourer du texte dans de multiples codes de contrôle, vous pourrez donc par exemple avoir un mot en gras, souligné et coloré.

## Les Filtres

### Les règles de filtre et comment les créer

Si vous n'arrivez même pas à comprendre, attendez. J'ai l'intention de construire un "générateur de filtre" pratique où vous n'aurez qu'à cliquer directement. Cependant, cela demandera un peu de temps.

Le filtre tente de trouver la chaîne de caractères "correspondante" puis d'utiliser les équivalences "depuis" et "jusqu'à" à la place. Vous pourrez effectuer les deux opérations, avec uniquement ce sous-programme qui autorise un meilleur contrôle des chaînes de caractères sur lesquelles vous effectuez la substitution. Les correspondances, "depuis" et "jusqu'à" sont toutes des expressions rationnelles perl. Les règles sont numérotées par ordre décroissant. La règle du sommet est numérotée en premier lieu, puis la deuxième à partir du sommet, etc. Toutes les chaînes de caractères sont numérotées ainsi :

$<namem> est étendue à la variable d'environnement <name>. Ceci est effectué immédiatement lorsque vous insérez la règle, et ne sera pas modifié ensuite. Par conséquent, c'est vraisemblablement un nombre de valeur limitée).

$$<name> est remplacée par la variable $<name> pendant la correspondance. Il peut s'agir de sous-chaînes de caractères comme $1, $2 dans la substitution, ou de variables normales disponibles sous sirc (comme $nick, $channel, etc).

˜<name>˜ PREDETERMINEE UNE FOIS POUR TOUTES) à la ligne, enverra la ligne de texte à la fenêtre appelée <name>. Si la fenêtre n'existe pas, elle ira à la dernière fenêtre qui avait le focus. Il y a plusieurs fenêtres spéciales, qui portent toutes un seul préfixe "!" :

!par défaut

  la fenêtre par défaut. Vous êtes certain de la trouver.

!toutes

  Envoi à chaque fenêtre. Cela pourrait ne pas s'afficher sur toutes les fenêtres, en fonction de l'analyse du texte. Par exemple, les fenêtres de canaux s'afficheront/quitteront à moins que le pseudonyme soit sur le canal.

!suppression

  supprime le texte

Le reste de l'expression est traité comme une expression rationnelle perl normale. Une bonne compréhension de la page de manuel perlref sera d'une aide appréciable, mais un minimum de connaissances de base des expressions rationnelles est obligatoire.

### Exemples :

1. Vous voulez convertir tous les "boren" depuis "boren" jusqu'à "BoreN"

       Correspondance : .*
       Depuis : boren
       Jusqu'à : BoreN

   Sans aucun doute, il y a une correspondance, ensuite modifiez "boren" en "BoreN".

2. Vous voulez tout faire correspondre avec "boren" et l'envoyer à la fenêtre appelée "boren"

       Correspondance : boren
       Depuis : ^
       To: ˜boren˜

   Cherche "boren", s'il le trouve, remplace le début de la chaîne de caractères (ˆ) par ˜boren˜.

3. Bien que l'exemple n°2 fonctionne, si la chaîne de caractères contient déjà `˜somewindow˜`, vous aurez maintenant deux `˜boren˜˜somewindow˜...`. Donc vous pouvez faire plutôt :

       Correspondance : boren
       Depuis :  ^(?:˜\S+˜)
       Jusqu'à : ˜boren˜

   D'accord, la ligne "depuis" est un tout petit peu plus compliquée. Elle signifie qu'il n'y a pas de correspondance ou qu'il y a une copie de `˜\S+˜`, qui est le premier tilde, une espace ou pas d'espace du tout, et ensuite un autre tilde. Les puristes feront `(*:˜\S+˜)` qui signifie correspondance 0 ou plusieurs instructions de canal, au cas où les règles précédentes ne fonctionneraient plus.

4. Les messages d'arrêt du serveur sont alors longs, laids, ennuyeux, etc. Un message typique sur réseau de dialogue ressemble à :

       *** Notice -- Received KILL message for BOBO!ANDY@line82-basel.datacomm.ch
       from NickServ Path: empire.ny.us.dal.net[209.51.168.14]!trapdoor.ca.us.dal
       .net[206.86.127.252]!caris.ca.us.dal.net[208.1.222.221]!services.dal.net[2
       008.1.222.222]!services.dal.net (NickServ Enforcement)

   Lorsque vous êtes `+s`, vous avez des tas de messages, et vous ne voulez pas en voir partout sur votre écran. Je vais créer 3 règles pour les traiter morceau par morceau. Vous pourrez le faire avec moins de règles, mais cela vous montrera la structure de base d'une règle, avec des étapes faciles, et comment utiliser les multiples règles pour analyser un message. La première étape consiste à supprimer le Path: (chemin) du message, et ce sera l'exemple 4.

       Correspondance : ^\*\*\*.* KILL message for .* (message d'ARRET pour .*)
       Depuis : Path: \S+
       Jusqu'à: .

   La correspondance cherche le message débutant avec `***`, les * doivent être mentionnées avec \ puisqu'elles signifient par elles-mêmes 0 ou supérieur au caractère précédent. Le `.*` signifie correspondance quelconque jusqu'à ce que vous trouviez `KILL message for` . Cela nous permet d'éviter de taper `-- Received...` etc. La fin `.*` indique une correspondance quelconque jusqu'à la fin de la ligne. (inutile je pense)

   La ligne "Depuis" indique de remplacer l'espace "Path: espace" et tout caractère autre qu'une espace par "Jusqu'à". "Jusqu'à" est un `"."`, par conséquent le chemin entier se transforme en un point uniquement. ().

   Le message ressemble maintenant à :

       *** Notice -- Received KILL message for BOBO!ANDY@line82-basel.datacomm.ch
       from NickServ. (NickServ Enforcement)

   Vous remarquez le nouveau `"."` après `NickServ`?

5. D'accord, le message est beaucoup plus net, mais les messages d'arrêt depuis le serveur de pseudonymes ne sont pas vraiment importants, donc laissons-les dans la fenêtre `!supprimer`.

       Correspondance : ^\*\*\*.*KILL message .*\(NickServ Enforcement\)
       Depuis: ^(?:˜\S+˜)
       Jusqu'à :  ˜!discard˜

   La règle de correspondance recherche le message d'ARRET et s'assure qu'il vient de NickServ (serveur de pseudonymes). Vous remarquez les `\(` et `\)`, les deux `()` utilisés dans les expressions rationnelles, par conséquent nous devons les mentionner. Ceci est très similaire à l'exemple 3.

6. Nous avons maintenant éliminé tous les messages d'arrêt du serveur de pseudonymes, mais le message est encore assez difficile à lire d'un simple coup d'oeil. Remettons-le donc en ordre comme ceci :

       *** [KILL] <KILLER> arrêté <KILLED> (motif)
       Correspondance: \*\*\*.*message d'ARRET
       Depuis: \*\*\*.*for (.*?) from (.*?)\. \((.*?)\).*
       Jusqu'à:  *** [KILL] $$2 killed $$1 ($$3)

   D'accord, la correspondance cherche le message d'ARRET `***<something>`. Nous ne pouvons utiliser `ˆ` puisque nous venons d'ajouter `˜<fenêtre>˜`.

   La ligne "Depuis" devient un peu plus intéressante. L'expression `"for (.*?) "` cherche le mot pour la suite du texte. `.*?` correspond à zéro ou plusieurs occurences de n'importe quel caractère, excepté une nouvelle ligne, mais n'est pas absorbant. Arrêtons lorsque la première condition de terminaison est trouvée, mais non la dernière. En d'autres termes, il cherche une correspondance quelconque jusqu'à ce qu'il trouve une espace. La zone entourée de `()` indique de sauvegarder le contenu. Chaque () sauvegarde les données correspondantes dans `$&num;` où `&num;` commence à 1 pour la première sous-chaîne de caractères, etc. Dans ce cas, `$1` obtient l'information-utilisateur/pseudonyme de la personne "tuée". `$2` est ensuite complétée avec le nom du "tueur". Entre les `()`, nous avons le motif de l'arrêt. Ici les `(` et `\(` prêtent un peu à confusion. Rappelez-vous, `\(` correspond au caractère réel `'('`.

7. Comment colorer votre vie. D'accord, vous voulez ajouter de la couleur à ksirc. Voyez la section section Couleurs pour une information sur la couleur, mais il y a une règle de filtre pour mettre en surbrillance le pseudonyme entre `<NICK>` sur chaque ligne :

       Correspondance: ^(?:˜\S+˜)<\S+>
       Depuis: <(\S+)>
       Jusqu'à: <˜4$$1˜c>

   Prend le pseudonyme et ajoute la couleur n°4 entre les deux `<> ˜c` éclaircit la couleur

## Touches

Voici une liste des raccourcis et des touches de commande sous Ksirc.

- Alt-F Menu Fichier

- Alt-E Menu Editer

- Ctrl-N Nouveau canal/Fenêtre de requête

- Ctrl-T Mode Terminal

- Ctrl-Q Quitter

- Ctrl-X Fenêtre Couper

- Ctrl-V Coller

- Ctrl-Enter Interlocuteur précédent

- Ctrl-Shift-Enter Interlocuteur suivant

- Ctrl-K Code de couleur de début

- Ctrl-U Soulignement Début/Fin

- Ctrl-I Italique Début/Fin

- Ctrl-B Gras Début/Fin

- Ctrl-R Inversé Début/Fin

- Tab Complétement du pseudonyme

## Programmation de votre Client Sirc

Attention : pour comprendre ceci, vous avez besoin de connaître perl (le langage de programmation; lisez les pages de manuel pour plus d'informations), et d'avoir lu soigneusement le README.

Pour un exemple de script sirc vraiment utile, regardez le fichier `n0thing.pl`; si vous vous demandez comment vous y prendre avec un script sirc, essayez de comprendre les fonctions qui y sont définies.

### Commandes

Depuis les scripts `/loaded/tt>` (chargés) et `.sircrc.pl`, vous pouvez définir de nouvelles commmandes et donner leur exécution en perl.

Ces scripts sont en fait des fichiers en code perl, et ils sont chargés de façon correcte dans le contexte de sirc.

Pour définir une nouvelle commande, vous n'avez qu'à définir un sous-programme avec le nom `cmd&lowbar;yourcommandname` (nomdevotrecommande) qui agit dans tous les cas, et appeller `&addcmd("yourcommandname");`

Vous pouvez également définir une aide pour la commande en appelant `&addhelp("yourcommandname", "Première ligne d'aide\nSeconde ligne d'aide...")`;

Votre sous-progamme prend tous ses arguments dans la variable globale `$args` (non analysée), son nom véritable dans `$cmd`, et la ligne entière de commande dans `$line`.

Il peut aussi utiliser un numéro de routine depuis le client sirc.

&load("file");

  charge un script sirc, vérifie dans @loadpath. que l'extension ".pl" est optionelle.

&dosplat;

  change une * dans le nom du canal courant, si elle est le premier mot de `$args`

&getarg;

  pour obtenir le premier mot de `$args` dans $newarg et le reste dans `$args`

&yetonearg;

  même chose, supprime une fin de ligne : dans `$args` s'il y en a une

&eq("txt1", "txt2");

  vérifie une égalité qui ignore la casse

&sl("text");

  pour envoyer une ligne de texte au serveur (la fin `"\n"` est ajoutée automatiquement)

&tell("txt");

  envoie du texte à l'écran, ajoute un `"\n"`, et uniquement s'il n'est pas en mode silencieux

&print("txt");

  envoie du texte à l'écran, ajoute un `"\n"`, sans tenir compte du mode silencieux

&getuserline("str", "prompt");

  édite "str" sur l'écran, place "prompt" comme invite temporaire s'il utilise ssfe, et guide les utilisateurs pour envoyer une ligne, la renvoie dans `$&lowbar;`

&getuserpass("str", "prompt");

  même chose pour les mots de passe d'invite; ssfe ne répétera pas le mot de passe

&dostatus;

  affiche de nouveau la ligne d'état

&msg("nck", "msg");

  envoie un message, l'édite. La destination peut être un pseudonyme, un canal, ou un =nick (DCC CHAT)

&notice("nck", "msg");

  envoie une remarque, l'édite. La destination peut être un canal ou un pseudonyme

&say("msg");

  signale quelque chose sur le canal courant, l'édite

&describe("nck", "msg");

  envoie un `/describe`, l'édite

&me("msg");

  effectue une action sur le canal courant, l'édite.

&connect($fh, "host", port);

  ouvre une connexion tcp avec l'hôte et donne le port. Le premier argument`($fh)` doit être une variable et `&connect` la définit à la valeur du gestionnaire de fichiers associé à la connexion. `&tell's` nous indique un message et renvoie 0 s'il y a une erreur, sinon 1.

&listen($fh, port);

  ouvre un support d'écoute limité au port donné; laisse le système désigner un port si le port spécifié est 0 (ou si le second argument n'a pas disparu en totalité). Le premier argument doit être une variable et `&listen` la définit à la valeur du gestionnaire de fichiers associé au support d'écoute. & nous signale un message et renvoie 0 s'il y a une erreur, sinon retourne au port sur lequel le support est en attente.

&accept($nfh, $ofh);

  admet une connexion sur le gestionnaire de fichiers `$ofh` (qui doit se reporter à un support d'écoute), et le renvoie dans `$nfh`; `$nfh` doit être une variable, et sera modifée par `&accept`. `$ofh` automatiquement fermée par `&accept` renvoie une valeur booléenne, mais n'édite en aucun cas de message d'erreur.

&resolve("address");

  définit un nom d'hôte dans un fichier groupé (c'est-à-dire une chaîne de caractères de 4 bits représentant l'adresse IP). L'argument peut être un nom d'hôte, une adresse IP écrite en notation à quatre séries de chiffres, ou un (grand) nombre représentant l'adresse "lue" comme un nombre 32 bits dans une instruction réseau. Si la définition échoue, un résultat faux est renvoyé ("" ou 0 ou indéterminé).

  pour obtenir un système à quatre séries de chiffres, à partir duquel `&resolve` est renvoyé, utilisez `join(".", unpack("C4", &resolve("whatever")))`

&newfh;

  renvoie un nouveau nom à utiliser comme gestionnaire de fichiers

&doset("variable", "value");

  définit une valeur à une variable SET, la valeur est validée, et cela n'a pas d'effet si la valeur est incorrecte ou si la variable n'existe pas. C'est la seule façon pour que les scripts modifient les valeurs des variables SET, sauf éventuellement celles qu'ils définissent eux-mêmes.

&docommand("command");

  interprète une ligne de commande comme si elle était tapée au clavier. Un *seul* interligne "/" désactivera l'extension alias/fonction sur la commande.

  *attention* cette routine appelle de façon récurrente le répartiteur de commandes pour elle-même, ce qui est assez gênant. C'est une vérification à l'encontre des boucles (récursion limitée à 20), mais c'est amplement suffisant pour que *vous* soyez sûr que vos scripts fonctionnent. Perl étant un langage doté de structures puissantes et performantes (au contraire de ircII ...), la récursion à ce niveau est à éviter autant que possible. descrip>

  Vous avez accès à un nombre de variables globales; notez que certaines ont été supprimées car elles ont été modifiées en variables SET, pour être lues dans &percnt;set et écrites avec &doset.

  A moins qu'autre chose ne soit spécifié, ces variables seront traitées en lecture seule par les scripts..

$version

  version de sirc's - doit toujours être un nombre, et ne doit jamais être modifiée par une fonction utilisateur

$add&lowbar;ons

  chargement de modules supplémentaires; des scripts peuvent y ajouter un *nomdescript"

$restrict

  définie comme vraie si sirc tourne en mode restreint (sécurisé), qui interdit l'accès à l'interpréteur de commandes et au système de fichiers

$maxrecursion

  number of times &docommand : peut être appelée de façon récurrente avant de donner un message d'erreur "taux maximum de récursion dépassé" (vous pouvez modifier celle-ci, mais il n'est pas sûr qu'elle fonctionne sur des versions ultérieures où elle pourrait devenir une variable SET)

$nick

  votre pseudonyme courant

$server

  votre serveur courant

@channels

  liste des canaux sur lesquels vous êtes connecté

$talkchannel

  votre canal courant (ou '' s'il n'y en pas)

&percnt;mode

  tableau réunissant les modes des différents canaux sur lesquels nous sommes connectés. Les noms de canaux sont tous dans la case inférieure, et le mode est une chaîne de caractères sans +' ni -', et sans 'k' ou 'l' puisque ceux-ci sont traités séparément. La valeur des canaux sans aucun mode est '', tandis que la valeur pour les canaux sur lesquels nous ne sommes pas connectés est indéterminée.

&percnt;chankey

  touches des canaux, indéfini s'il n'y en a aucun ou si nous ne sommes pas connectés sur le canal. Les noms de canaux sont dans la case inférieure.

&percnt;limit

  limites des canaux, indéfini s'il n'y en aucun ou si nous ne sommes pas connectés sur le canal. Les noms de canaux sont dans la case inférieure.

&percnt;haveops

  tableau réunissant les variables booléennes, vrai si nous avons des opérations sur le canal. Les noms de canaux sont... vous le savez

$umode

  mode utilisateur, chaîne de caractères sans +' ni -'

$query

  tout interlocuteur que vous demandez, ou '' s'il n'y a personne

&percnt;aliases

  tableau réunissant les alias de substitution définis; le nom d'alias est en capitales

&percnt;set

  tableau réunissant les valeurs des variables SET; le nom de variable est également en capitales

&percnt;notify

  tableau réunissant la liste de notification; la valeur pour un pseudonyme donné est 0 pour un "absent", ou le moment de la plus récente notification pour ce pseudonyme

$bindaddr

  c'est l'adresse IP de la machine à laquelle les connexions de sortie sont limitées, jusqu'à ce que sirc puisse le signaler. Elle change lorsque la variable SET de "l'hôte local" change, et elle est déterminée à l'adresse IP de la machine proxy lorsque sirc tourne avec les supports de communication chargés. `$bindaddr` est une chaîne de caractères de 4 bits représentant un groupe `in&lowbar;addr;` que vous obtenez en entier (comme il est d'usage dans DCC CHAT/SEND) avec `unpack("N", $binaddr);`, et un système à quatre séries de chiffres avec `join(".", unpack("C4", $bindaddr));`

A moins qu'autre chose ne soit spécifié, commandes et points d'insertion ne devraient jamais modifier les paramètres qui leur ont été assignés (c'est-à-dire faire quelque chose comme `$&lowbar;[1]="some value"`. S'ils souhaitent en modifier des copies locales, ils commenceront avec `local(...)=@&lowbar;;`

Si votre script utlise des variables globales, veuillez vous assurer qu'elles ne vont pas s'opposer à celles de sirc (même problème pour les noms de description de fichiers, et de procédures). Une bonne convention serait de donner à toutes ces variables et procédures un nom qui commence par le nom du script, ou avec quelques lettres de celui-ci. Par exemple, dans `n0thing.pl` toutes les variables globales de script et les procédures internes ont des noms qui commencent par "n&lowbar;".

Exemple, que pourrait-on introduire directement dans un fichier `/load'ed`, une commande qui (cible?) un canal si vous en spécifiez un, et un pseudonyme si vous le mentionnez également :

    sub cmd_yeek {
      &dosplat;		# si le premier argument est *, remplacez-le avec $talkchannel
      &getarg;		# place le premier argument dans $newarg
      local($channel)=($talkchannel);	# par défaut, nous communiquons avec le canal $talkchannel
      if ($newarg =˜ /^[\#\&]/) {		# si le premier argument commence avec # or &
        $channel=$newarg;			# communiquez plutôt ici
        &getarg;				# et placez un argument supplémentaire
      }
      if ($newarg) {	# regardez si nous avons spécifié que nous (ciblons?)
        &describe($channel, "look at $newarg and *yeeeks*"); ("regardez $newarg et (*ciblez*")?)
      } else {		# or not (ou non)
        &describe($channel, "*yeeks* at the crowd"); ((*ciblez*?) le groupe*);
    }

    # \cb est la manière de spécifier ^B en perl
    &addcmd("yeek");
    &addhelp("yeek", "Usage: \cbYEEK\cb [<channel>] [<nick>]
    Cible sur le pseudonyme ou sur le canal entier
    Examples: /yeek someone ((cible?) un interlocuteur)
              /yeek * someone
     	  /yeek #channel  ((cible?) un canal)
     	  /yeek #channel someone"); ((cible?)à un interlocuteur sur le canal)

### Points d'insertion

Depuis les scripts `loaded`, aussi bien que depuis `.sircrc.pl`, vous avez la possibilité de définir des routines à appeler lorsque des événements particuliers se produisent. C'est l'équivalent de ircII `/on's`.

Pour déclarer un point d'insertion, vous devez définir une sous-routine appelée `"hook&lowbar;somename"` qui agit quoi que vous vouliez faire lorsqu'un point d'insertion de type `"hook&lowbar;type"` est (déclenché), et ensuite appelle `&addhook("hook&lowbar;type", "somename");`

Pour supprimer un point d'insertion, vous appelez `&remhook("hook&lowbar;type", "somename");`

Les points d'insertion numériques son également disponibles, pour chaque nombre à 3 caractères; pour déclarer l'un d'eux, définissez une sous-routine appelée `"hook&lowbar;somename"` qui agit comme vous le voulez, et appelez `&addhook("xxx", "somename")`, où xxx est le nombre représentant la réponse numérique. Pour supprimer l'un d'eux, appelez `&remhook("xxx", "somename");`

Les sous-programmes appelés à partir des points d'insertion ont accès aux mêmes fonctions et variables listées plus haut pour les fonctions, plus quelques-unes plus spécifiques (partout où c'est applicable) :

    $who		est le pseudonyme qui a déclenché le point d'insertion
    $user           est le nom d'utilisateur correspondant
    $host		est le nom d'hôte correspondant

Les points d'insertion peuvent également définir la variable `$silent` s'ils veulent assurer l'affichage pour l'éventualité (à travers `&print`) et bloquer les valeurs par défaut. C'est l'équivalent direct de la connexion `"ˆ"` sur ircII `/on's`, excepté `"raw&lowbar;irc"`.

Les points d'insertion marqués avec une `*` peuvent aussi définir la variable spéciale `$skip` et la ligne sera ignorée par le client). Ceci est en général une mauvaise idée, utilisez `$silent` autant que possible. Seuls les points d'insertion où ce procédé fournit une fonctionnalité supplémentaire réelle ont cette possibilité. Pour `"raw&lowbar;irc"` c'eest l'aquivalent de la connexion `"ˆ"` sur ircII `/on raw&lowbar;irc`.

Les points d'insertion suivants sont disponibles, et sont appelés avec les arguments suivants :

    action		activée par une action ctcp;
    		le 1er argument est le pseudonyme ou le canal auquel il est envoyé
    		le 2e argument est le message

    commande      *	activée par l'utilisateur tapant une commande (sans tenir compte
                    si c'est une /commande ou seulement une ligne de texte)
                    le 1er argument est la ligne de l'utilisateur
                    ce point d'insertion est spécial (comme "print" et "status"), en ce
                    sens qu'il est clairement autorisé à modifier son argument ($_[0]) pour
                    modifier toute commande pouvant être interprétée.
    		la définition $skip=1 dans le point d'insertion obligera sirc à
                    ignorer la commande

    chat_disconnect activée lorqu'une discussion en ligne est perdue (mais non lorsque
                    l'utilisateur la clôture lui-même avec DCC CLOSE CHAT)
                    le 1er argument est le pseudonyme associé à la discussion en ligne

    ctcp	     *	activée par tout ctcp, AVANT que le client n'effectue l'analyse
                    et éventuellement réponde au ctcp.
    		le 1er argument est le nom ou le canal auquel il a été émis
                    le 2e argument est la commande ctcp
                    les 3e arguments sont les arguments eux-mêmes

    ctcp_reply	activée par les réponses ctcp;
                    le 1er argument est le pseudonyme ou le canal sur lequel il a été émis
                    le 2e argument est la commande ctcp
                    les 3e arguments sont les arguments eux-mêmes

    dcc_chat	activée par le texte reçu pendant une discussion en ligne dcc
    		le 1er argument est le pseudonyme
    		le 2e argument est le texte

    dcc_disconnect  activée lorsqu'une lecture ou une émission dcc est terminée ou fermée
                    (même lorsque l'utilisateur en clôture une avec DCC CLOSE GET/SEND)
                    le 1er argument est le pseudonyme associé à la discussion en ligne
                    le 2e argument est le nom de fichier
                    le 3e argument est le nombre de bytes transférés
                    le 4e argument est nombre de secondes nécessaires au transfert

    dcc_request	activée par la réception d'une discussion en ligne ou d'une demande
                    d'émission; Ceci est le point d'insertion à utiliser si vous voulez
                    mettre en oeuvre toute discussion auto-dcc.
                    le 1er argument est le type "(DISCUSSION" ou "EMISSION")
                    le 2e argument est l'adresse de la machine (un nombre entier 32 bits)
                    le 3e argument est le port
                    pour une proposition DCC SEND (émission DCC) :
                      le 4e argument est le nom de fichier
                      le 5e argument est la longueur du fichier

    disconnect      activée par la perte de la connexion au serveur, ou l'interruption
                    avec /déconnexion (mais pas avec le serveur).
                    il n'y a pas d'arguments

    input	     *	activée chaque fois que le client veut demander à l'utilisateur une
                    ligne par &getuserline (c'est-à-dire lorsque vous avez été
                    déconnecté, ou que vous avez besoin d'un nouveau pseudonyme,
                    ou d'un script appelé &getuserline).
                    le 1er argument est l'"invite" longue
                    le 2e argument est l'"invite" courte
                    si le point d'insertion définit $skip, &getuserline ne demandera
                    ensuite rien à l'utilisateur, et le contenu de  $_ will  sera renvoyé

    invite		activée par les invites;
                    le 1er argument est le canal que vous avez invité

    join		activée par les jonctions
                    le 1er argument est le canal que joint $who (qui)

    kick		activée par les ();
                    le 1er argument est le pseudonyme ou la personne qui a été ()
                    le 2e argument est le canal d'où ils ont été (virés)
                    le 3e argument est le motif

    leave		activée par les (partants);
                    le 1er argument est le canal que $who abandonne

    mode		activée par les changements de modes;
                    le 1er argument est le canal ou l'utilisateur auquel s'applique le changement
                    le 2e argument est le changement de mode lui-même

    msg		activée par les messages;
    		le 1er argument est le message

    nick		activée par les changements de pseudonymes
                    le 1er argument est le nouveau pseudonyme de $who (qui)

    notice		activée par les remarques
                    le 1er argument est le pseudonyme ou le canal sur lequel il a été émis
                    le 2e argument est le message

    server_notice	activée par les remarques depuis les serveurs
                    le 1er argument est le pseudonyme ou le canal sur lequel il a été émis
                    le 2e argument est le message

    notify_signon	activée par une ouverture de session
    		le 1er argument est le pseudonyme
                    $user et $host (utilisateur et hôte) ne sont *pas* définis
                    de façon significative

    notify_signoff	activée par une fermeture de session
                    le 1er argument est le pseudonyme
                    $user et $host ne sont *pas* définis de façon significative

    print	     *	activée par l'édition d'une ligne quelconque à l'écran
                    le 1er argument est la ligne à éditer
                    ce point d'insertion est spécial (comme "état" et "commande"),
                    en ce sens qu'il elle est clairement autorise à modifier
                    son argument ($_[0]) pour changer la ligne à éditer
                    la définitiion de $skip=1 dans le point d'insertion empêchera la ligne
                    d'être réellement éditée

    public		activée par les messages non-ctcp à un canal;
                    le 1er argument est le canal
                    le 2e argument est le message

    raw_irc      *	activée par une ligne du serveur
    	        $who    est l'initiateur (utilisateur ou serveur)
    		$user   est sont nom d'utilisateur ('' s'il vient d'un serveur)
    		$host   est son nom d'hôte (même commentaire)
                    le 1er argument est la commande
                    les seconds arguments sont les arguments eux-mêmes

    send_action	activée à l'émission  d'un /me ou d'un /de
    		($who, $user et $host ne s'appliquent pas ici)
                    le 1er argument est le pseudonyme/canal

    send_ctcp	activée à l'émission d'un ctcp
                    le 1er argument est le pseudonyme ou le canal sur lequel il a été émis
                    le second argument est le texte complet ctcp (type et arguments)

    send_dcc_chat	activée à l'émission du texte pendant une discussion en ligne dcc
                    ($who, $user et $host ne s'appliquent pas ici)
                    le 1er argument est le pseudonyme auquel nous émettons un message
                    le second argument est le texte

    send_text	activée à l'émission d'un /msg ou d'une communication sur un canal
    		($who, $user et $host ne s'appliquent pas ici)
                    le 1er argument est le pseudonyme/canal
                    le second argument est le message

    send_notice	activée à l'émission d'une remarque
               	($who, $user et $host ne s'appliquent pas ici)
                    le 1er argument est le pseudonyme/canal
                    le second argument est la remarque

    signoff		activée lorsque quelqu'un ferme une session
                    le 1er argument est le commentaire de sortie

    status		activée lorsque sirc reconfigure la ligne d'état (comme
                    résultat de l'appel à &dostatus, soit de façon interne,
                    soit par un script).
    		le 1er argument est la ligne d'état proposée
                    ce point d'insertion est spécial (comme "édition" et "commande")en ce sens
                    qu'il est clairement autorisé à modifier son argument ($_[0]) pour changer
                    ce qui devrait figurer sur la ligne d'état

    topic		activée lorsque quelqu'un change de sujet
                    le 1er argument est le canal
                    le second argument est le nouveau sujet

    <3-digit nb>  * activée par cette réponse numérique spéciale du serveur
                    le 1er argument est tout ce que le serveur a émis après le nombre,et
                    non analysé (qui signifie qu'il y a encore un caractère ":"
                    devant le dernier argument

Exemple, qu'est ce qui pourrait être placé dans un fichier et chargé directement, d'un point d'insertion qui joindra un canal chaque fois que vous serez (viré?) :

    # auto-rejoin hook (point d'insertion (auto-jonction?))

    sub hook_kicked {
      local($kicked, $where_from, $reason)=@_;
      					# local vars with the args (variables locales avec les arguments)
      if (&eq($kicked, $nick)) {		# if *we* got kicked (si *nous* sommes (virés?))
        &sl("JOIN $where_from");		# send a JOIN to the server (envoie une jonction au serveur)
      }
    }
    &addhook("kick", "kicked");	  	# activate the hook (active le point d'insertion)

Un autre exemple, pour afficher le nom d'utilisateur et le nom d'hôte avec chaque message (opération mieux réalisé avec /set printuh)

    # userhost-on message (point d'insertion du message)

    sub hook_uhmsg {
      &tell("[\cb${who}!${user}\@${host}\cb] $_[0]");  # print everything  (édite tout)
      $silent=1;			# disable the default display (désactive la variable par défaut)
    }
    &addhook("msg", "uhmsg");	  	# activate the hook  (active le point d'insertion)

### Variables SET

Un script peut accéder à des variables SET;

- Pour les lire, vous n'avez besoin que de regarder `$set&lcub;"VARIABLE"&rcub;`, où le nom des variables est écrit en capitales

- Pour les définir, appelez `&doset("variable", "value");` où le nom des variables peut être dans les deux cas (un cas ne signifie rien) et la valeur en est contrôlée

Un script peut aussi ajouter ses propres variables SET, fournissant une valeur par défaut et un point d'insertion pour contrôler et définir une nouvelle valeur. Pour ce faire, le script doit :

- définir la variable à une valeur par défaut, avec `$set&lcub;"VAR"&rcub;="whatever";` sirc ne laissera pas l'utilisateur définir une variable `/set` si aucune valeur pour elle dans `&percnt;set` n'existe.

- définit un sous-programme `set&lowbar;somename`, et appelle `&addset("var", "somename");` &addset ("var", "somename");

Le nom des variables peut être omis dans les deux cas.

Les sous-programmes qui servent de point d'insertion pour les variables SET sont appelés avec la valeur proposée comme premier argument. Ils peuvent (on non) modifierr la valeur réelle dans `$set&lcub;"VAR"&rcub;` à la valeur donnée à une autre. Par convention, ils ne seront pas `&tell`, et ignoreront les valeurs des arguments invalides

Ce qui se passe dans `$set&lcub;"VAR"&rcub;` doit être lisible de façon (humaine?); par exemple, pour les les désactivations, il est suggéré que les valeurs dans `$set&lcub;"VAR"&rcub;` seront "on","out" ou similaire, et que `&doset` peut définir une variable (à l'intérieur du script) à 0 ou 1, qui sera la seule réellement contrôlée par le script.

### Demandes de l'hôte utilisateur

Quelquefois, dans une fonction vous avez besoin de savoir le nom complet de l'utilisateur et de l'hôte utilisateur pour chaque peudonyme. Si cela se produit dans un point d'insertion, et que le point d'insertion est le seul qui étatit actif, le pseudonyme est alors dans `$who` et les données de l'hôte utilisateur sont déjà dans `$user` et `$host`.

Cependant, vous devez appeler la fonction perl `&userhost` donnant ici trois arguments : le pseudonyme, ce que vous voulez voir évalué lorsque les données sont disponibles si le peudinyme n'est pas trouvé sur IRC; si le troisième argument est omis, sirc éditera le message par défaut `"*?* somenickname not found on IRC"` (pas de psedonyme trouvé sur IRC).

Au contraire des versions antérieures de sirc, il est possible de faire plus d'une demande d'hôte urilisateur dans un délai court avant d'obtenir les réponses du serveur.

Exemple : une fonction qui édite le code du pays d'un interlocuteur

p>

    # country code (code du pays)

    sub printcountry {		# prints $host's country code (édite le code du pays de l'hôte)

      if ($host =˜ /\.([^.]+)$/) {  # match the last part of the host (correspond à la dernière partie de l'hôte)
        local($c)=($1); 		# put it in local var $c  (placé dans une variable locale $c)
        $c="USA" if $c =˜ /^edu$/i;	# if it's a .edu, say it's USA (si c'est un .edu, il s'agit des USA)
        $c="USA (probably)" if $c =˜ /^com$/i || $c =˜ /^org$/i || $c =˜ /^net$/i;
    				# if it's a .org, .com or .net, it's (si c'est un .org; .com ou .net, il s'agit
    				# probably in the USA too             probablement des USA aussi)
        if ($c =˜ /^\d+$/) {	# if it's a number (si c'est un nombre)
          &tell("*** out of luck, $who has an IP address :p"); (pas de chance, $who a une adresse IP :p")
    				# complain, it's an IP (réclamation si c'est une adresse IP)
        } else {			# otherwise  (autrement)
          &tell("*** $who is in $c");
    				# announce the result  (annonce le résultat)
        }
      }
    }

    sub cmd_country {		# this is the command (voici la commande)

      &getarg;			# get the argument in $newarg (obtient l'argument dans $nearg)
      if ($newarg) {		# if it's there  (s'il y est)
        &userhost($newarg, "&printcountry;");
    				# request a userhost with &printcountry as (demande à un hôte
                                                                            utlisateur son code de pays)
    				# action to take (action à faire)

      } else {			# otherwise (autrement)
        &tell("*** Whose?");	# complain (réclamation)
      }
    }

    &addcmd("country");		# install the command  (installe la commande)

### Timers

Il est possible dans sirc de spécifier une action à faire de manière différée, un certain nombre de secondes plus tard, exactement comme avec la fonction de ircII La précsion est de l'ordre de la seconde.

Pour ce faire, vous appelez la fonction `&timer` avec le nombre de secondes à attendre comme premier argument, et la chaîne de caractères à évaluer comme second argument.

Un troisième argument peut être fourni, il doit être un nombre non-nul, et sera utilisé comme nombre de référence pour cette minuterie. La définition d'une minuterie lorsqu'un autre nombre de même référence existe, supprimera la première minuterie. Si aucun nombre n'est spécifié, la minuterie ne peut être supprimée.

Pour supprimer une minuterie avec un nombre de référence `$n`, appelez `&deltimer($n);`

Ceci est assez simple, mais vous si avez réellement besoin d'un exemple, en voici un : pour éditer "hello" dans 10 secondes vous devez faire `&timer(10, "& tell('hello')");`

Si vous voulez pouvoir l'annuler, vous ferez `&timer(10, "&tell('hello')", 6);` et ensuite pour l'annuler, vous ferez `& timer12, "('hello')");`. Il va sans dire que le '6' est arbitraire.

### Ajout des gestionnaires de fichiers à la principale boucle sélectionnée ()

Comme sur la version 2.2, des scripts peuvent ajouter des gestionnaires de fichiers à la boucle principale, et définir des points d'insertion dessus pour obtenir un contrôle lorsque les données sont disponibles.

Il (est assigné( au script d'ouvrir d'abord le gestionnaire de fichiers, qui peut se référer à une connexion réseau, un tty, un tube, comme dans `open (FH, "program &verbar;")`, etc.

Lors du traitement des supports de communication avec le réseau, il est fortement recommandé d'utiliser l'API fourni par sirc `&connect, &listen, &accept, &resolve, &newfh` et `$bindaddr`) plutôt que d'utiliser les fonctions perl brutes. Ceci aura pour effet de faire travailler ces scripts de façon transparente sur les proxies des supports de communication, lorsque le module de communication est chargé. Si vous avez besoin d'une fonctionnalité supplémentaire, bien que (comme le support de communication UDP, ou admettant des connexions multiples depuis le support d'écoute), vous puissiez utiliser les fonctions propres de perl.

Pour avoir de nouveau le contrôle lorsque les données sont disponibles sur un gestionnaire de fichiers, vous pouvez l'ajouter à la définition de fh sirc `select()s` (from), avec

`&addsel($fh, "somename", flag);` où sel&lowbar;name est le sous-programme qui prendra le contrôle à nouveau lorsqu'il y aura un message à lire, et l'indication 1 si vous voulez que sirc protége votre connexion et la fractionne en lignes, et 0 si vous ne voulez pas du tout que sirc touche à vos données..

La convention pour les sous-programmes `sel&lowbar;somename` est différente dans les deux cas suivants :

- Pour les gestionnaires de fichiers protégés, il est autorisé un seul argument contenant une ligne qui a été lue, incluant l'expression finale `\n`. Si la connexion est fermée ou interrompue, cet argument est `''` et le gestionnaire de fichiers a déjà été fermé et supprimé de l' ensemble de fh à `select()`. Si vous la fermez vous-même, vous devez utiliser `&remsel` pour indiquer à sirc de la supprimer de l'ensemble.

- Pour les gestionnaires de fichiers non protégés, aucun argument n'est autorisé; le point d'insertion est appelé lorsque `select()` indique que la fonction fh est prête pour la lecture, et il est impératif au point d'insertion de lire à partir de lui (en s'assurant de ne pas bloquer le point d'insertion, sysread devrait donc être utilisé et non <>), et éventuellement le fermer et le supprimer avec `&remsel`.

  Pour supprimer un gestionnaire de fichiers de l'ensemble de fh ()`select()ed`, appelez `&remsel($fh);` où `$fh` est le gestionnaire de fichiers.

  Remarquez que sirc n'effectue jamais de contrôle pour vérifier que le gestionnaire de fichiers donné est valide. Avoir un `fh` fermé ou invalide dans le jeu des `select()able`, ou ne pas réellement lire les donéées sur un `sel&lowbar;* hook` non protégé, obligera sirc à monopoliser l'unité centrale (CPU) en ne bloquant pas `select()`.

  Pour un exemple d'utilisation intensive de tout ceci, voyez le script ftp.pl qui met en application un client ftp à l'intérieur de sirc (vous pourrez le trouver sur la page internet de sirc à l'adresse http://www.eleves.ens.fr:8080/home/espel/sirc/sirc.html).

### Robots(?)

Il est possible de créer des robots dans un script sirc, exactement comme si vous le feriez dans ircII. Ce n'est sûrement pas une mauvaise idée, puique vous avez à votre disposition un langage de programmation (perl), débarrassé de toutes les tâches de programmation réseau ennuyeuses et de l'analyse des problèmes de réseau.

Toutefois, sirc n'a jamais été considéré comme un client robot, et je n'ai pas l'intention de le remplir de cloches et de sifflements pour les supports robots, j'ai donc fourni uniquement un support minimum pour cela, avec les options -l et -q.

L'idée est que vous programmez votre robot comme un ensemble de fonctions internes, de points d'insertion et d'appels à `&addhook` et à `& docommand`, et ensuite charger sirc de cette façon (évidemment sans ssfe) :

`nohup sirc -d -q -l <botfile> -i <bot's ircname> <nick> <server> >/dev/null &`

Tour ceci sans `<>'s`, bien sûr. `>/dev/null` supprime le résultat, puisque de toute façon vous ne le lirez pas sur l'écran..

Dans le robot, assurez-vous de saisir (avec un point d'insertion numérique) les lignes qui indiquent `"nick in use"` or `"invalid nick"`, (pseudonyme en cours) (pseudonyme incorrect) et envoyez les lignes au serveur avec un pseudnyme aléatoire, et omettez-les, sinon le robot s'arrêtera en tentant de demander un pseudonyme à l'utilisateur. Vous définirez également un point d'insertion sur `"disconnect"`, et lui ferez faire un `&docommand("server 0")` or `"server some.server"`.

Rappelez-vous aussi que le fichier est chargé avant même que la connexion au serveur soit effectuée, les appels à `&sl` and most `&docommand's` à ce moment échoueront..

Voici un exemple de robot qui effectue une connexion, joint un canal, refait une nouvelle connexion s'il est déconnecté, répond à quelques commandes, effectue ses opérations propres, et enregistre dans un fichier tout ce qu'il voit sauf l'encombrement général (du réseau); vous devriez charger ce fichier, en supposant que vous l'ayez sauvegardé dans un fichier appelé "mybot" (mon robot) et que vous vouliez l'appeler BubbleBot, avec :

`nohup sirc -d -q -l mybot -i "bot in sirc" BubbleBot some.server.edu >/dev/null`

    $botowner="espel\@clipper.ens.fr";	# change it to your address (le modifie à votre adresse)

    $logfile=$ENV{'HOME'}."/.botlog";
    &docommand("log on");

    sub hook_publicstuff {		# don't print the public chatter (so it       (n'édite pas la
                                                                       la discussion publique,( donc il

                           		# doesn't fill the logfile   (ne remplit pas le journal de bord)
    }
    &addhook("public", "publicstuff");

    sub hook_connected {
      &sl("JOIN #BotTub");
    }
    &addhook("376", "connected");   # join on the "end of MOTD" numeric (jonction à la "fin du
                                                                              MOTD" numérique)
    srand;				# init random number generator (nombre générateur d'init aléatoire)

    sub hook_badnick {
      local($n);
      $n="B".(int(rand(1000000))+4587454);  # send a garbage nick... (envoie un pseudonyme incorrect...)
      &sl("NICK $n");
      $skip=1;
    }
    &addhook("432", "badnick");             # if told that ours is taken (s'il est indiqué que le nôtre est pris)
    &addhook("433", "badnick");

    sub hook_disc {         # if we got disconnectedj (si nous sommes déconnectés)
      sleep(30);		# wait 30 seconds (so we don't bring the machine (attendez 30 secondes (donc
                                                                     nous ne malmenons pas la machine si
    			# down to a crawl if the server is down) le serveur est figé)
      &docommand("server 1"); # reconnect to the same server (réeffectue une connexion au même serveur)
    }
    &addhook("disconnect", "disc");

    sub hook_joined {	# whenever someone joins (au cas où un interlocuteur ())
      local($ch)=($_[0]);
      $ch =˜ tr/A-Z/a-z/;	# put channel in lowercase (place le canal dans la case inférieure)
      if (&eq($botowner, "$user\@$host") && $haveops{$ch}) {
        &sl("MODE $ch +o $who");	# op if that's the owner and we have ops (opération si c'est celle
      }                                                     du propriétaire et que nous avons des opérations)
    }
    &addhook("join", "joined");

    sub hook_message {
      if (&eq($botowner, "$user\@$host")) {  # if it's a msg from the owner
        if ($_[0] =˜ /^die$/i) {             # die -> die
          &docommand("quit");
        } elsif ($_[0] =˜ /^say /i) {        # say <something> -> say it
          &say($');
        } elsif ($_[0] =˜ /^nick /i) {       # nick <nick> -> change nicks
          &sl("NICK $'");
        }
    # add more commands here
      }
    }
    &addhook("msg", "message");