<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook V3.1-Based Variant V1.0//EN" [
 <!ENTITY ksirc "<application>ksirc</application>">
]>
<book lang="en">

<bookinfo>
<title>The KSirc Handbook</title>
<authorgroup>
<author>
<firstname>Andrew</firstname>
<surname>Stanley-Jones</surname>
<affiliation>
<address><email>asj@chowtown.cban.com</email></address>
</affiliation>
</author>
</authorgroup>
<date>26/05/2000</date>
<releaseinfo>0.09.00</releaseinfo>
<abstract>
<para>This documentation describes KSirc 0.9</para>
</abstract>
<keywordset>
<keyword>KDE</keyword>
<keyword>KSirc</keyword>
<keyword>irc</keyword>
<keyword>Internet relay chat</keyword>
</keywordset>
</bookinfo>

<chapter id="installation">
<title>Installation</title>

<graphic fileref="ksirc.png"></graphic>

<para><emphasis remap="bf">Binary Install</emphasis>
<itemizedlist>
<listitem>
<para>IF YOU DO NOT HAVE THE KDE
<screen>	cd /usr/local/
	tar -zxvf &lt;ksirc file&gt;
	tar -zxvf kdehelp-netscape.tgz
</screen>
(See also <ulink url="http://www.eleves.ens.fr:8080/home/espel/sirc.html">Ksirc/Sirc Homepage</ulink>)
</para>

<para>You can then run ksirc by typing "ksirc".
Remember, you do need to have perl5 installed.</para>

<para>If you want online help, and don't have KDE you'll netscape and
get kdehelp-netscape.tgz from ksirc.org/pub/ksirc</para>

</listitem>
<listitem>
<para>For those with KDE</para>

<para><screen>	cd $KDEDIR/..
	tar -zxvf &lt;ksirc file&gt;
</screen>
</para>

<para>	You can then run ksirc by typeing "ksirc".</para>

</listitem>
</itemizedlist>
</para>
</chapter>

<chapter id="sectcolors">
<title>kSirc Colours</title>

<para>KSirc follows the colour scheme used by mIrc and a slight modification
for more powerful in house use.</para>

<para><screen>&lt;fg&gt; == foreground
&lt;bg&gt; == background
&lsqb;&rsqb; == optional
</screen>
</para>

<sect1 id="mirccompatibility">
<title>mIrc compatibility</title>

<para>Format:
<itemizedlist>
<listitem>
<para><emphasis remap="bf">0x03&lt;fg&gt;&lsqb;,&lt;bg&gt;&rsqb;</emphasis>
sets the foreground and background</para>
</listitem>
<listitem>
<para><emphasis remap="bf">0x03</emphasis>
resets to defaults for THAT line</para>
</listitem>
</itemizedlist>
</para>
</sect1>

<sect1 id="ksircnative">
<title>KSirc native</title>

<para>Format:
<itemizedlist>
<listitem>
<para><emphasis remap="bf">&tilde;&lt;fg&gt;&lsqb;,&lt;bg&gt;&rsqb;</emphasis>
sets the foreground and background</para>
</listitem>
<listitem>
<para><emphasis remap="bf">&tilde;c</emphasis>
resets tp defaults</para>
</listitem>
<listitem>
<para><emphasis remap="bf">&tilde;b</emphasis>
sets bold font</para>
</listitem>
<listitem>
<para><emphasis remap="bf">&tilde;u</emphasis>
sets underline</para>
</listitem>
<listitem>
<para><emphasis remap="bf">&tilde;i</emphasis>
sets italics</para>
</listitem>
<listitem>
<para><emphasis remap="bf">&tilde;r</emphasis>
sets underline</para>
</listitem>
</itemizedlist>
</para>

<para>Why did I change ksirc to use &tilde; instead of 0x03 (&circ;C)? Well, it's hard to
use 0x03 in scripts and not all C functions seem to like it.
&tilde;&lt;letter&gt; also alows more commands while not stomping on mirc's future
changes.</para>
</sect1>

<sect1 id="colournumbers">
<title>Colour Numbers</title>

<para><orderedlist><listitem>
<para> white</para>
</listitem>
<listitem>
<para> black</para>
</listitem>
<listitem>
<para> blue</para>
</listitem>
<listitem>
<para> green</para>
</listitem>
<listitem>
<para> red</para>
</listitem>
<listitem>
<para> brown</para>
</listitem>
<listitem>
<para> purple</para>
</listitem>
<listitem>
<para> orange</para>
</listitem>
<listitem>
<para> yellow</para>
</listitem>
<listitem>
<para> lightGreen</para>
</listitem>
<listitem>
<para> cyan</para>
</listitem>
<listitem>
<para> lightCyan</para>
</listitem>
<listitem>
<para> lightBlue</para>
</listitem>
<listitem>
<para> pink</para>
</listitem>
<listitem>
<para> gray</para>
</listitem>
<listitem>
<para> lightGray</para>
</listitem>
</orderedlist>
</para>
</sect1>

<sect1 id="sendingboldunderlinereverseandcolour">
<title>Sending Bold, Underline, Reverse, and Colour</title>

<para>You can use the following key combinations to insert control codes in text:
<itemizedlist>
<listitem>
<para>Control-B for bold text</para>
</listitem>
<listitem>
<para>Control-U for underlined text</para>
</listitem>
<listitem>
<para>Control-R for reverse text</para>
</listitem>
<listitem>
<para>Control-K for coloured text</para>
</listitem>
<listitem>
<para>Control-O for plain text</para>
</listitem>
</itemizedlist>
</para>
</sect1>

<sect1 id="examplessetcolors">
<title>Examples</title>

<para>To underline a single word in a sentence:
<orderedlist><listitem>
<para>Type Control-U</para>
</listitem>
<listitem>
<para>Type in the word</para>
</listitem>
<listitem>
<para>Type Control-U again</para>
</listitem>
</orderedlist>
</para>

<para>Only the text that is enclosed by the start and end codes will be affected.
You can use this method with all of the other control codes.</para>

<para>The Control-K control code is slightly different because it allows you to
specify a colour number. To colour a single word in a sentence:</para>

<para><orderedlist><listitem>
<para>Type Control-K</para>
</listitem>
<listitem>
<para>Type a number between 0 and 15</para>
</listitem>
<listitem>
<para>Type the word</para>
</listitem>
<listitem>
<para>Type Control-K again</para>
</listitem>
</orderedlist>
</para>

<para>If you also want to change the background colour of a word, you would need
to type two numbers separated by a comma instead of just one number. The
first number is the text colour, the second number is the background
colour. The colours range from 0 to 15, the index is in the previous section.</para>

<para>You can enclose text in multiple control codes, so for example you could
have a bold, underlined, and coloured word.</para>
</sect1>
</chapter>

<chapter id="filters">
<title>Filters</title>

<sect1 id="filterrulesandhowtomakethem">
<title>Filter Rules and How to Make them</title>

<para>If just you just can't figure it out, wait. I want to build a nice
"filter builder" where you can just click your way through it.
Though, it might be a while.</para>

<para>The filter tries to find the "match" string then use the "From" and
"To" as a substitution.  You could do both operations simply with the
substation this allows finer control on which strings you do the
substitution.  The match, from, and to are all perl regex
expressions. Rules are evaluated in descending order.  The top rule is
first evaluated, then the second from the top, etc. All strings are
evaluated as:</para>

<para>$&lt;name&gt; is expanded to the environment variable &lt;name&gt;.
This is done immediately when you insert the rule, and will not change
after that time.  Therefor it's probably of limited value.</para>

<para>$$&lt;name&gt; is substituted with the perl $&lt;name&gt; variable
during the match.  This can be substrings such as $1, $2 in the
substitution, or normal variables available under sirc (such as $nick,
$channel, etc).</para>

<para>&tilde;&lt;name&gt;&tilde; <emphasis remap="bf">PREPENDED ONCE AND ONLY ONCE</emphasis> to the line
will send the line of text to the window called &lt;name&gt;.  If the
window does not exist it will go to the last window which had focus.
There are several special windows, all prefixed by a single "!":</para>

<para><variablelist>
<varlistentry>
<term>!default</term>
<listitem>
<para>the current default window.  Guaranteed to be.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>!all</term>
<listitem>
<para>Send to every window.  This might not show up on all
windows, depending on how the parse the text.  For example, channel
windows won't show a part/quit unless the nick is on the channel.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>!discard</term>
<listitem>
<para>discards the text.</para>
</listitem>
</varlistentry>
</variablelist>
</para>

<para>The rest of the expression is dealt with as normal perl regex.  A good
understanding of the perlre man page will certainly help, but a basic
understating of regex is most certainly required.</para>
</sect1>

<sect1 id="examplesfilters">
<title>Examples:</title>

<para><orderedlist><listitem>
<para>Want to convert all boren from boren to BoreN</para>

<para><screen>Match: .*
From: boren
To: BoreN
</screen>
</para>

<para>Pretty straight forward, match anything, then substitute boren with BoreN.</para>

</listitem>
<listitem>
<para>You want to match everything with boren in it and send to the
window called "boren"</para>

<para><screen>Match: boren
From: ^
To: &tilde;boren&tilde;
</screen>
</para>

<para>Looks for "boren" if found, substitutes the beginning of the string (&circ;)
with &tilde;boren&tilde;.</para>

</listitem>
<listitem>
<para>Though &num;2 works, if the string already has <literal remap="tt">&tilde;somewindow&tilde;</literal> on it,
you'll now have two <literal remap="tt">&tilde;boren&tilde;&tilde;somewindow&tilde;...</literal>  So you can do this
instead.</para>

<para><screen>Match: boren
From: ^(?:&tilde;\S+&tilde;)
To: &tilde;boren&tilde;
</screen>
</para>

<para>Ok, the from line is a little bit more complicated.  It says match 0
or 1 copies of <literal remap="tt">&tilde;\S+&tilde;</literal>.  Which is 1 tilde, one or more none
whitespaces, and then another tilde.  The paranoid might do <literal remap="tt">(*:&tilde;\S+&tilde;)</literal>
which says match 0 or more channel directives in case prior rules are
broken.</para>

</listitem>
<listitem>
<para>Server kill messages then to be long, ugly, annoying, etc.  Basic
message on dalnet looks like:</para>

<para><screen>*** 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)
</screen>
</para>

<para>When you're <literal remap="tt">+s</literal> you get tons of them, you don't want all of them
flying across your screen.  I'm going to make 3 rules to deal with
them one bit at a time.  You could do it in less rules, but it'll show
you the basic rule structure, in nice steps, and how to use multiple
rules to parse a message.  The first step is to remove the Path:
portion of the message, and will be example 4.</para>

<para><screen>Match: ^\*\*\*.* KILL message for.*
From:  Path: \S+
To: .
</screen>
</para>

<para>Match looks for the message starting with <literal remap="tt">***</literal>, the *'s have to be
quoted with \ since by themselves they mean 0 or more of the prior
character.  <literal remap="tt">.*</literal> the means match anything until you find <literal remap="tt">" KILL message
for"</literal>.  This allows us to avoid typing in <literal remap="tt">-- Received...</literal> etc. The
trailing <literal remap="tt">.*</literal> says match anything to the end of the line. (not needed I think)</para>

<para>The From line says substitute space Path: space and any non whitespace
characters with the To.  To is a <literal remap="tt">"."</literal> therefore the entire path turns
into a single period.</para>

<para>The message now looks like:
<screen>*** Notice -- Received KILL message for BOBO!ANDY@line82-basel.datacomm.ch
from NickServ. (NickServ Enforcement)
</screen>

Notice the new <literal remap="tt">"."</literal> after <literal remap="tt">NickServ</literal>?</para>

</listitem>
<listitem>
<para>Ok, the message is a lot cleaner, but KILL's from nickserv aren't
really that important, so let's forward them to the <literal remap="tt">!discard</literal> window.
<screen>Match: ^\*\*\*.*KILL message.*\(NickServ Enforcement\)
From: ^(?:&tilde;\S+&tilde;)
To:  &tilde;!discard&tilde;
</screen>
</para>

<para>Match rule searches for the KILL message and makes sure it's from
NickServ.  Notice the <literal remap="tt">\(</literal> and <literal remap="tt">\)</literal> both <literal remap="tt">()</literal> and used in regex, therefore we
have to quote them.  This is very similar to example 3.</para>

</listitem>
<listitem>
<para>We've now filtered out all the nickserv kills, but the message is
still pretty hard to read by simply glancing at it.  So let's reorder
it to something like:</para>

<para><screen>*** [KILL] &lt;KILLER&gt; killed &lt;KILLED&gt; (reason)
Match: \*\*\*.*KILL message
From: \*\*\*.*for (.*?) from (.*?)\. \((.*?)\).*
To: *** [KILL] $$2 killed $$1 ($$3)
</screen>
</para>

<para>Ok, the match looks for <literal remap="tt">***&lt;something&gt;</literal> KILL message.  We can't use <literal remap="tt">&circ;</literal>
since we may have just appended <literal remap="tt">&tilde;&lt;window&gt;&tilde;</literal>.</para>

<para>The from line get's little more interesting.  The <literal remap="tt">"for (.*?) "</literal> looks
for the word for then some text.  <literal remap="tt">.*?</literal> says match zero or more of
anything except newline, but isn't greedy. Stop when the first
terminating condition is found, not the last.  In other words it
matches anything until a space.  The surrounding <literal remap="tt">()</literal> says to save the
contents.  Each () saves the matched data in <literal remap="tt">$&num;</literal> where <literal remap="tt">&num;</literal> starts at 1
for the first substring, etc.  In this case, <literal remap="tt">$1</literal> gets the nick/user-info
of the person killed.  <literal remap="tt">$2</literal> is then filled with the name of the killer.
Between the <literal remap="tt">()</literal> we have the reason for the kill.  Here the <literal remap="tt">(</literal> and <literal remap="tt">\(</literal> get
a little confusing.  Remember <literal remap="tt">\(</literal> matches the actual character <literal remap="tt">'('</literal>.</para>

</listitem>
<listitem>
<para>How to colourize your life. Ok, you want to add some colour to ksirc.  See
the <link linkend="sectcolors">Colors section</link> for colour info, but here's a filter ruls to highlight the nick
between <literal remap="tt">&lt;NICK&gt;</literal> on each line:
<screen>Match: ^(?:&tilde;\S+&tilde;)&lt;\S+&gt;
From: &lt;(\S+)&gt;
To: &lt;&tilde;4$$1&tilde;c&gt;
</screen>
</para>

<para>Takes the nick and adds colour &num;4 between the two <literal remap="tt">&lt;&gt; &tilde;c</literal> clears the colour.</para>

</listitem>
</orderedlist>
</para>
</sect1>
</chapter>

<chapter id="keys">
<title>Keys</title>

<para>This is a listing of the short cut and command keys available under Ksirc.
<itemizedlist>
<listitem>
<para><emphasis remap="bf">Alt-F</emphasis>
File Menu</para>
</listitem>
<listitem>
<para><emphasis remap="bf">Alt-E</emphasis>
Edit Menu</para>
</listitem>
<listitem>
<para><emphasis remap="bf">Ctrl-N</emphasis>
New Channel/Query Window</para>
</listitem>
<listitem>
<para><emphasis remap="bf">Ctrl-T</emphasis>
Ticker mode</para>
</listitem>
<listitem>
<para><emphasis remap="bf">Ctrl-Q</emphasis>
Quit</para>
</listitem>
<listitem>
<para><emphasis remap="bf">Ctrl-X</emphasis>
Cut Window</para>
</listitem>
<listitem>
<para><emphasis remap="bf">Ctrl-V</emphasis>
Paste</para>
</listitem>
<listitem>
<para><emphasis remap="bf">Ctrl-Enter</emphasis>
Prior person who messaged you</para>
</listitem>
<listitem>
<para><emphasis remap="bf">Ctrl-Shift-Enter</emphasis>
Next person who messaged you</para>
</listitem>
<listitem>
<para><emphasis remap="bf">Ctrl-K</emphasis>
Start colour code</para>
</listitem>
<listitem>
<para><emphasis remap="bf">Ctrl-U</emphasis>
Start/End underline</para>
</listitem>
<listitem>
<para><emphasis remap="bf">Ctrl-I</emphasis>
Start/End italics</para>
</listitem>
<listitem>
<para><emphasis remap="bf">Ctrl-B</emphasis>
Start/end bold</para>
</listitem>
<listitem>
<para><emphasis remap="bf">Ctrl-R</emphasis>
Start/end reverse</para>
</listitem>
<listitem>
<para><emphasis remap="bf">Tab</emphasis>
Nick Completion</para>
</listitem>
</itemizedlist>
</para>
</chapter>

<chapter id="programmingyoursircclient">
<title>Programming Your Sirc Client</title>

<para>Warning: to understand this you need to know perl (the programming
language; read the perl man pages for more info), and have read the
README thoroughly.</para>

<para>For a real usable example of a sirc script, look at the file <literal remap="tt">n0thing.pl</literal>;
if you wonder how you could do something in sirc script, try
understanding the functions defined in there.</para>

<sect1 id="commands">
<title>Commands</title>

<para>From <literal remap="tt">/loaded</literal> scripts and <literal remap="tt">.sircrc.pl</literal>, you can define new commands
and give their implementation in perl.</para>

<para>These scripts are actually files of perl code, and they get loaded
right into sirc's context.</para>

<para>To define a new command, all you need to do is define a sub with the
name <literal remap="tt">cmd&lowbar;yourcommandname</literal> which does whatever you want it to do, and call
<literal remap="tt">&amp;addcmd("yourcommandname");</literal></para>

<para>You can also define some help for the command, by calling
<literal remap="tt">&amp;addhelp("yourcommandname", "First line of help\nSecond line of help...")</literal>;</para>

<para>Your sub gets all of its arguments in the global variable <literal remap="tt">$args</literal>
(unparsed), its own name in <literal remap="tt">$cmd</literal>, and the whole command line in <literal remap="tt">$line</literal>.</para>

<para>It can also use a number of routines from the sirc client:</para>

<para><variablelist>
<varlistentry>
<term>&amp;load("file");</term>
<listitem>
<para>loads a sirc script, searching in @loadpath.
the ".pl" extension is optional.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>  &amp;dosplat;</term>
<listitem>
<para>turns a * into the current channel name, if it's
the first word of <literal remap="tt">$args</literal></para>
</listitem>
</varlistentry>
<varlistentry>
<term>  &amp;getarg;</term>
<listitem>
<para>to get the first word of <literal remap="tt">$args</literal> in $newarg and
the rest in <literal remap="tt">$args</literal></para>
</listitem>
</varlistentry>
<varlistentry>
<term>  &amp;yetonearg;</term>
<listitem>
<para>same thing, removing a trailing : in <literal remap="tt">$args</literal> if
there's one</para>
</listitem>
</varlistentry>
<varlistentry>
<term>  &amp;eq("txt1", "txt2");</term>
<listitem>
<para>tests case-insensitive equality</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&amp;sl("text");</term>
<listitem>
<para>to send a line of text to the server (the
trailing <literal remap="tt">"\n"</literal> gets added automatically)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&amp;tell("txt");</term>
<listitem>
<para>sends text to the screen, adding a <literal remap="tt">"\n"</literal>, and
only if not in silent mode</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&amp;print("txt");</term>
<listitem>
<para>sends text to the screen, adding a <literal remap="tt">"\n"</literal>, regardless
of silent mode</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&amp;getuserline("str", "prompt");</term>
<listitem>
<para>prints "str" on the screen, puts "prompt" as a
temporary prompt if using ssfe, and prompts the
users for a line, returning it in <literal remap="tt">$&lowbar;</literal></para>
</listitem>
</varlistentry>
<varlistentry>
<term>&amp;getuserpass("str", "prompt");</term>
<listitem>
<para>same for prompting passwords; ssfe will not echo
the password</para>
</listitem>
</varlistentry>
<varlistentry>
<term>  &amp;dostatus;</term>
<listitem>
<para>redisplays the status line</para>
</listitem>
</varlistentry>
<varlistentry>
<term>  &amp;msg("nck", "msg");</term>
<listitem>
<para>sends a message, printing it.  the destination
can be a nick, a channel, or a =nick (DCC CHAT)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>  &amp;notice("nck", "msg");</term>
<listitem>
<para>sends a notice, printing it.  the destination can be a channel or a nick</para>
</listitem>
</varlistentry>
<varlistentry>
<term>  &amp;say("msg");</term>
<listitem>
<para>says something on the current channel, printing it</para>
</listitem>
</varlistentry>
<varlistentry>
<term>  &amp;describe("nck", "msg");</term>
<listitem>
<para>sends a <literal remap="tt">/describe</literal>, printing it</para>
</listitem>
</varlistentry>
<varlistentry>
<term>  &amp;me("msg");</term>
<listitem>
<para>does an action on the current channel, printing it</para>
</listitem>
</varlistentry>
<varlistentry>
<term>  &amp;connect($fh, "host", port);</term>
<listitem>
<para>opens a tcp connection with the given host and
port.  the first argument <literal remap="tt">($fh)</literal> must be a
variable and <literal remap="tt">&amp;connect</literal> sets it to the value of
the file handle associated with the connection.
<literal remap="tt">&amp;tell's</literal> a message and returns 0 if there's an
error, otherwise returns 1.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>  &amp;listen($fh, port);</term>
<listitem>
<para>opens listening socket bound to the given port;
lets the system pick a port if the specified
port is 0 (or the second argument is not passed
at all).  the first argument must be a variable
and <literal remap="tt">&amp;listen</literal> sets it to the value of the file
handle associated with the listening socket.
&amp;tell's a message and returns 0 if there's an
error, otherwise returns the port on which the
socket listens.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>  &amp;accept($nfh, $ofh);</term>
<listitem>
<para>accepts a connection on the file handle <literal remap="tt">$ofh</literal>
(which must refer to a listening socket), and
returns it in <literal remap="tt">$nfh</literal>;  <literal remap="tt">$nfh</literal> must be a variable
and will be changed by <literal remap="tt">&amp;accept</literal>.  <literal remap="tt">$ofh</literal> is
automatically closed by <literal remap="tt">&amp;accept</literal>.  returns a
boolean value, but does not print an error
message in any case.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>  &amp;resolve("address");</term>
<listitem>
<para>resolves a hostname into a packed in&lowbar;addr (i.e
a 4-byte string representing the IP address).
the argument can be a hostname, an IP address
written in dotted quad notation, or a (large)
number representing the address, "read" as a
32-bit number in network order.  if the
resolution fails, returns a false result ("" or
0 or undef).</para>
<para>to get a dotted quad from what <literal remap="tt">&amp;resolve</literal> returns,
use <literal remap="tt">join(".", unpack("C4", &amp;resolve("whatever")))</literal></para>
</listitem>
</varlistentry>
<varlistentry>
<term>  &amp;newfh;</term>
<listitem>
<para>returns a fresh name for use as a filehandle</para>
</listitem>
</varlistentry>
<varlistentry>
<term>  &amp;doset("variable", "value");</term>
<listitem>
<para>sets a value to a SET variable; the value is
validated, and this has no effect if the value
is incorrect or the variable does not exist.
this is the only way scripts should ever change
the values of SET variables, except possibly
those that they define themselves.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>  &amp;docommand("command");</term>
<listitem>
<para>interprets a command line as if it were typed at
the keyboard.  a *single* leading "/" will
disable alias/function expansion on the
command.</para>
<para>*warning* this calls the command dispatcher
recursively from itself, which is pretty bad.
there is a test against loops (a limit on
recursion, set to 20), but it's mostly up to
*you* to make sure your scripts work.
perl being a language with strong and powerful
control structures (unlike ircII...), recursion
at this level should be avoided whenever
possible.</para>
</listitem>
</varlistentry>
</variablelist>
</para>

<para>You have access to the a number of global variables;  note that some have
been removed because they have been turned into SET variables, to be
read in &percnt;set and written to with &amp;doset.</para>

<para>Unless otherwise specified, these variables should be treated as
read-only by scripts.
<variablelist>
<varlistentry>
<term>$version</term>
<listitem>
<para>sirc's version - should always be a number, and
never be modified by a user function</para>
</listitem>
</varlistentry>
<varlistentry>
<term>$add&lowbar;ons</term>
<listitem>
<para>additional modules loaded; scripts can add a
"+scriptname" to it</para>
</listitem>
</varlistentry>
<varlistentry>
<term>$restrict</term>
<listitem>
<para>set to true if sirc is running in restricted
(secure) mode, which disallows access to the
shell and to the filesystem</para>
</listitem>
</varlistentry>
<varlistentry>
<term>$maxrecursion</term>
<listitem>
<para>number of times &amp;docommand may be called recursively
before giving a "max recursion exceeded" error (you
can change this one, but it is not guaranteed to
work on future versions where this might become a
SET variable)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>$nick</term>
<listitem>
<para>your current nick</para>
</listitem>
</varlistentry>
<varlistentry>
<term>$server</term>
<listitem>
<para>your current server</para>
</listitem>
</varlistentry>
<varlistentry>
<term>@channels</term>
<listitem>
<para>list of channels you're on</para>
</listitem>
</varlistentry>
<varlistentry>
<term>$talkchannel</term>
<listitem>
<para>your current channel (or '' if none)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>  &percnt;mode</term>
<listitem>
<para>associative array with the modes of the different
channels we're on.  the channel names are all in
lower case, and the mode is a string of letters
without +'s or -'s, and without 'k' or 'l' either
since those are treated separately.  the value
for channels without any mode is '', while the
value for channels we're not on is undef.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&percnt;chankey</term>
<listitem>
<para>keys to channels, undef if none or we're not on
the channel.  channel names are in lower case.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&percnt;limit</term>
<listitem>
<para>limits to channels, undef if none or we're not
on the channel.  channel names in lower case.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&percnt;haveops</term>
<listitem>
<para>associative array of booleans, true if we have ops
on the channel.  channel names are...  you know how</para>
</listitem>
</varlistentry>
<varlistentry>
<term>  $umode</term>
<listitem>
<para>user mode, string of letters without +'s or -'s</para>
</listitem>
</varlistentry>
<varlistentry>
<term>  $query</term>
<listitem>
<para>whoever you're querying, or '' if no-one</para>
</listitem>
</varlistentry>
<varlistentry>
<term>  &percnt;aliases</term>
<listitem>
<para>associative array of defined substitution aliases;
the alias name is in CAPS</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&percnt;set</term>
<listitem>
<para>associative array of SET variable values; the
variable name is in CAPS too</para>
</listitem>
</varlistentry>
<varlistentry>
<term> &percnt;notify</term>
<listitem>
<para>associative array of the notify list; the value
for a given nick is 0 for "absent", or the time
of the most recent notification for this nick</para>
</listitem>
</varlistentry>
<varlistentry>
<term>  $bindaddr</term>
<listitem>
<para>this is the IP address of the machine to which
outgoing connections are bound, as far as sirc
can tell.  it changes when the "localhost" SET
variable changes, and is set to the IP of the
proxy machine when sirc is running with socks
support loaded.  <literal remap="tt">$bindaddr</literal> is a 4-byte string
representing a packed <literal remap="tt">in&lowbar;addr;</literal> you can get an
integer out of it (as used by DCC CHAT/SEND)
with <literal remap="tt">unpack("N", $binaddr);</literal> and a dotted quad
with <literal remap="tt">join(".", unpack("C4", $bindaddr));</literal></para>
</listitem>
</varlistentry>
</variablelist>
</para>

<para>Unless otherwise specified, commands and hooks should never modify the
parameters that are passed to them (i.e. do somethign like
<literal remap="tt">$&lowbar;[1]="some value"</literal>.  If they wish to modify local copies of them, they
should start with <literal remap="tt">local(...)=@&lowbar;;</literal></para>

<para>Also, if your script is going to use global variables, please make sure
they're not likely to clash with sirc's own (same goes for file
descriptor names, and procedures).  A good convention would be to give
all these variables and procedures a name that starts with the script
name, or with a few letters from it.  For example, in <literal remap="tt">n0thing.pl</literal> all the
script's global variables and internal procedures have names that start
with "n&lowbar;".</para>

<para>Example, which could be put into a file and <literal remap="tt">/load'ed</literal> directly, of
a command that will yeek on a channel if you specify one, and at a
nick if you do too:</para>

<para><screen>sub cmd_yeek {
  &amp;dosplat;		# if the 1st arg is *, replace it with $talkchannel
  &amp;getarg;		# get 1st arg in $newarg
  local($channel)=($talkchannel);	# by default we talk to $talkchannel
  if ($newarg =&tilde; /^[\#\&amp;]/) {		# if the 1st arg starts with # or &amp;
    $channel=$newarg;			# talk there instead
    &amp;getarg;				# and get an extra arg
  }
  if ($newarg) {	# look at whether we specified who we're yeeking at
    &amp;describe($channel, "look at $newarg and *yeeeks*");
  } else {		# or not
    &amp;describe($channel, "*yeeks* at the crowd");
  }
}

# \cb is the way to specify ^B in perl
&amp;addcmd("yeek");
&amp;addhelp("yeek", "Usage: \cbYEEK\cb [&lt;channel&gt;] [&lt;nick&gt;]
Yeeks at the given nickname or at the whole channel.
Examples: /yeek someone
          /yeek * someone
 	  /yeek #channel
 	  /yeek #channel someone");
</screen>
</para>
</sect1>

<sect1 id="hooks">
<title>Hooks</title>

<para>From <literal remap="tt">/load'ed</literal> scripts, as well as from <literal remap="tt">.sircrc.pl</literal>, you have
the possibility to define subs to be called when specified events
occur.  This is the equivalent of ircII's <literal remap="tt">/on's</literal>.</para>

<para>To declare a hook, you must define a subroutine called <literal remap="tt">"hook&lowbar;somename"</literal>
which does whatever you want done when a hook of type <literal remap="tt">"hook&lowbar;type"</literal> is
triggered, and then call <literal remap="tt">&amp;addhook("hook&lowbar;type", "somename");</literal></para>

<para>To remove a hook, you call <literal remap="tt">&amp;remhook("hook&lowbar;type", "somename");</literal></para>

<para>Numeric hooks are also available, for every 3-digit number; to declare
one of those, define a soubroutine called <literal remap="tt">"hook&lowbar;somename"</literal> which does
what you want, and call <literal remap="tt">&amp;addhook("xxx", "somename")</literal>, where xxx is the
number of the numeric reply.  To remove one of these, you call
<literal remap="tt">&amp;remhook("xxx", "somename");</literal></para>

<para>Subs called from hooks have access to the same functions and variables
listed above for functions, plus a few specific ones (wherever
applicable):</para>

<para><screen>$who		is the nick that triggered the hook
$user           is the corresponding username
$host		is the corresponding hostname
</screen>
</para>

<para>Hooks can also set the variable <literal remap="tt">$silent</literal> if they want to provide the
display for the event (via <literal remap="tt">&amp;print</literal>) and inhibit the default.  This
is the direct equivalent of the <literal remap="tt">"&circ;"</literal> switch on ircII <literal remap="tt">/on's</literal>, except
for <literal remap="tt">"raw&lowbar;irc"</literal>.</para>

<para>Hooks marked with a <literal remap="tt">*</literal> can also set the special variable <literal remap="tt">$skip</literal> and cause
the line to be ignored by the client.  This is in general a bad idea,
use <literal remap="tt">$silent</literal> whenever possible.  Only the hooks where this provides some
actual additional functionality have this possibility.  For <literal remap="tt">"raw&lowbar;irc"</literal>
this is the equivalent of the <literal remap="tt">"&circ;"</literal> switch on ircII's <literal remap="tt">/on raw&lowbar;irc</literal>.</para>

<para>The following hooks are available, and get called with the following
arguments:</para>

<para><screen>action		activated by a ctcp action;
		1st arg is the nick or channel it was sent to
		2nd arg is the message

command      *	activated by the user typing a command (regardless of
		whether it is a /command or just a line of text)
		1st arg is the user's line
		this hook is special in that (like "print" and
		"status"), it is explicitly allowed to modify its
		argument ($_[0]) to change what command should be
		interpreted.
		setting $skip=1 in the hook will make sirc ignore the
		command

chat_disconnect activated when a dcc chat is lost (but not when the
		user closes one with DCC CLOSE CHAT)
		1st arg is the nick associated with the chat

ctcp	     *	activated by any ctcp, BEFORE the client parses
		and eventually answers the ctcp.
		1st arg is the nick or channel it was sent to
		2nd arg is the ctcp command
		3rd arg are the arguments

ctcp_reply	activated by ctcp replies;
		1st arg is the nick or channel it was sent to
		2nd arg is the ctcp command
		3rd arg are the arguments

dcc_chat	activated by received text over a dcc chat
		1st arg is the nick
		2nd arg is the text

dcc_disconnect  activated when a dcc get or send is finished or closed
		(even when the user closes one with DCC CLOSE GET/SEND)
		1st arg is the nick associated with the chat
		2nd arg is the filename
		3rd arg is the number of bytes transferred
		4th arg is the number of seconds the transfer took

dcc_request	activated by a received dcc chat or send request, and
		after the client has processed the request.  this is
		the hook to use if you want to implement any kind of
		auto-dcc.
		1st arg is the type ("CHAT" or "SEND")
		2nd arg is the machine address (a 32-bit integer)
		3rd arg is the port
		for a DCC SEND offer:
		  4th arg is the file name
		  5th arg is the file lenght

disconnect	activated by losing the connection to the server, or
		breaking it with /disconnect (but not with /server).
		no arguments are passed

input	     *	activated whenever the client wants to ask the user
		for a line through &amp;getuserline (i.e. when you got
		disconnected, or need a new nick, or some script called
		&amp;getuserline).
		1st arg is the "long" prompt
		2nd arg is the "short" one
		if the hook sets $skip, then &amp;getuserline won't ask
		the user for anything, and the contents of $_ will
		be returned

invite		activated by invites;
		1st arg is the channel you're invited to

join		activated by joins;
		1st arg is the channel that $who is joining

kick		activated by kicks;
		1st arg is the nick of the person who got kicked
		2nd arg is the channel that they got kicked from
		3rd arg is the reason

leave		activated by parts;
		1st arg is the channel that $who is leaving

mode		activated by mode changes;
		1st arg is the channel or user the change applies to
		2nd arg is the mode change itself

msg		activated by msgs;
		1st arg is the message

nick		activated by nick changes
		1st arg is $who's new nick

notice		activated by notices
		1st arg is the nick or channel it was sent to
		2nd arg is the message

server_notice	activated by notices from servers
		1st arg is the nick or channel it was sent to
		2nd arg is the message

notify_signon	activated by a notify signon
		1st arg is the nick
		$user and $host are *not* set to anything meaningful

notify_signoff	activated by a notify signoff
		1st arg is the nick
		$user and $host are *not* set to anything meaningful

print	     *	activated by the printing of any line to the screen
		1st arg is the line to print
		this hook is special in that (like "status" and
		"command") it is explicitly allowed to modify its
		argument ($_[0]) to change what line should be
		printed.
		setting $skip=1 in the hook will prevent the line from
		being actually printed

public		activated by non-ctcp messages to a channel;
		1st arg is the channel
		2nd arg is the message

raw_irc	     *	activated by any server line
		$who    is the originator (user or server)
		$user   is his username ('' if it comes from a server)
		$host   is his hostname (same comment)
		1st arg is the command
		2nd arg are the arguments

send_action	activated when we send a /me or a /de
		($who, $user and $host do not apply here)
		1st arg is the nick/channel
		2nd arg	is the action

send_ctcp	activated when we send a ctcp
		1st arg is the nick or channel the ctcp is being sent to
		2nd arg is the complete ctcp text (type and arguments)

send_dcc_chat	activated when we send text over a dcc chat
		($who, $user and $host do not apply here)
		1st arg is the nick we're sending to
		2nd arg is the text

send_text	activated when we send a /msg or speak on a channel
		($who, $user and $host do not apply here)
		1st arg is the nick/channel
		2nd arg is the msg

send_notice	activated when we send a notice
		($who, $user and $host do not apply here)
		1st arg is the nick/channel
		2nd arg is the notice

signoff		activated when someone signs off
		1st arg	is the quitting comment

status		activated when sirc redraws the status line (as a
		result of &amp;dostatus being called, either internally
		or by a script).
		1st arg is the proposed status line
		this hook is special in that (like "print" and
		"command") it is explicitly allowed to modify its
		argument ($_[0]) to change what should go to the status
		line

topic		activated when someone changes the topic
		1st arg is the channel
		2nd arg is the new topic

&lt;3-digit nb&gt;  * activated by that particular server numeric reply
		1st arg is whatever the server sent after the number,
	 	unparsed (which means there's still a : in front of the
	 	last argument)
</screen>
</para>

<para>Example, which could be put into a file and /load'ed directly, of
a hook that will rejoin a channel whenever you are kicked:</para>

<para><screen># auto-rejoin hook

sub hook_kicked {
  local($kicked, $where_from, $reason)=@_;
  					# local vars with the args
  if (&amp;eq($kicked, $nick)) {		# if *we* got kicked
    &amp;sl("JOIN $where_from");		# send a JOIN to the server
  }
}
&amp;addhook("kick", "kicked");	  	# activate the hook
</screen>
</para>

<para>Another example, to display the username and hostname with each message
(which is better done with /set printuh anyway):</para>

<para><screen># userhost-on message hook

sub hook_uhmsg {
  &amp;tell("[\cb${who}!${user}\@${host}\cb] $_[0]");  # print everything
  $silent=1;			# disable the default display
}
&amp;addhook("msg", "uhmsg");	  	# activate the hook
</screen>
</para>
</sect1>

<sect1 id="setvariables">
<title>SET variables</title>

<para>A script can access SET variables:
<itemizedlist>
<listitem>
<para>to read them, you just need to look at <literal remap="tt">$set&lcub;"VARIABLE"&rcub;</literal>, where the variable name is written in caps</para>
</listitem>
<listitem>
<para>to set them, call <literal remap="tt">&amp;doset("variable", "value");</literal>  the variable name
can be in either case (case is not significant) and the value is
checked</para>
</listitem>
</itemizedlist>
</para>

<para>A script can also add its own SET variables, providing a default value
and a hook to check and set a new value.  To do this, the script must:
<itemizedlist>
<listitem>
<para>set the variable to a default value, with <literal remap="tt">$set&lcub;"VAR"&rcub;="whatever";</literal>
sirc will not let the user <literal remap="tt">/set</literal> a variable if a value for it in <literal remap="tt">&percnt;set</literal>
does not exist
</para>
</listitem>
<listitem>
<para>define a sub called <literal remap="tt">set&lowbar;somename</literal>, and call <literal remap="tt">&amp;addset("var", "somename");</literal>
the variable name can be passed in either case.</para>
</listitem>
</itemizedlist>
</para>

<para>The subs that serve as hooks for SET variables get called with the
proposed value as the first argument.  They may (or not) change the
actual value in <literal remap="tt">$set&lcub;"VAR"&rcub;</literal>, to the value given or to another one.  By
convention, they should not <literal remap="tt">&amp;tell</literal> anything, and should ignore invalid
values.</para>

<para>What goes in <literal remap="tt">$set&lcub;"VAR"&rcub;</literal> must still be human-readable; for things like
toggles, it is suggested that the values in <literal remap="tt">$set&lcub;"VAR"&rcub;</literal> should be "on",
"off" or similar, and that <literal remap="tt">&amp;doset</literal> can set a variable (internal to the
script) to 0 or 1, which will be the one actually checked by the script.</para>
</sect1>

<sect1 id="userhostrequests">
<title>Userhost requests</title>

<para>Sometimes in a function you need to know the full username and hostname
for some nick.  If this happens in a hook, and the nick is the one who
did the action, then the nick is in <literal remap="tt">$who</literal> and the userhost data is
already in <literal remap="tt">$user</literal> and <literal remap="tt">$host</literal>.</para>

<para>Otherwise, you have to call the perl function <literal remap="tt">&amp;userhost</literal> giving it three
arguments: the nickname, what you want evaluated when the data is
available, and what you want evaluated if the nick is not found on IRC;
if the third argument is ommited, sirc will print the default message
<literal remap="tt">"*?* somenickname not found on IRC"</literal>.</para>

<para>Unlike with earlier versions of sirc, it is possible to do more than
one userhost request in a short time before getting the answers from
the server.</para>

<para>Example: a function that prints someone's country code</para>

<para><screen># country code

sub printcountry {		# prints $host's country code

  if ($host =&tilde; /\.([^.]+)$/) {  # match the last part of the host
    local($c)=($1); 		# put it in local var $c
    $c="USA" if $c =&tilde; /^edu$/i;	# if it's a .edu, say it's USA
    $c="USA (probably)" if $c =&tilde; /^com$/i || $c =&tilde; /^org$/i || $c =&tilde; /^net$/i;
				# if it's a .org, .com or .net, it's
				# probably in the USA too
    if ($c =&tilde; /^\d+$/) {	# if it's a number
      &amp;tell("*** out of luck, $who has an IP address :p");
				# complain, it's an IP
    } else {			# otherwise
      &amp;tell("*** $who is in $c");
				# announce the result
    }
  }
}

sub cmd_country {		# this is the command

  &amp;getarg;			# get the argument in $newarg
  if ($newarg) {		# if it's there
    &amp;userhost($newarg, "&amp;printcountry;");
				# request a userhost with &amp;printcountry as
				# action to take
  } else {			# otherwise
    &amp;tell("*** Whose?");	# complain
  }
}

&amp;addcmd("country");		# install the command
</screen>
</para>
</sect1>

<sect1 id="timers">
<title>Timers</title>

<para>It is possible in sirc to specify an action to be done but delayed, a
certain number of seconds later, just like with ircII's <literal remap="tt">/timer</literal> function.
This is only precise up to the second.</para>

<para>To do this, you call the function <literal remap="tt">&amp;timer</literal> with the number of seconds to
wait as the first argument, and the string to be evaluated as the second
argument.</para>

<para>A third argument can be supplied; it needs to be a non-zero number, and
will be used as the reference number for the timer.  Setting a timer when
another with the same reference number exists will delete the first
timer.  If no number is specified, the timer cannot be deleted.</para>

<para>To delete a timer with reference number <literal remap="tt">$n</literal>, call <literal remap="tt">&amp;deltimer($n);</literal></para>

<para>This is simple enough, but if you really need an example, here comes:
to print "hello" in 10 seconds, you'd do <literal remap="tt">&amp;timer(10, "&amp;tell('hello')");</literal></para>

<para>If you want to be able to cancel it, you'd do
<literal remap="tt">&amp;timer(10, "&amp;tell('hello')", 6);</literal> and then to cancel it you'd do
<literal remap="tt">&amp;deltimer(6);</literal>  It goes without saying that the '6' is arbitrary.</para>
</sect1>

<sect1 id="addingfilehandlestothemainselectloop">
<title>Adding file handles to the main select() loop</title>

<para>As of sirc 2.2, scripts can add file handles to the main loop, and set
hooks on them to get control when data is available.</para>

<para>It is up to the script to first open the file handle, which can refer to
a network connection, a tty, a pipe (as in <literal remap="tt">open(FH, "program &verbar;")</literal>), etc.</para>

<para>When dealing with network sockets, it is strongly suggested to use the
API provided by sirc (<literal remap="tt">&amp;connect, &amp;listen, &amp;accept, &amp;resolve, &amp;newfh</literal> and
<literal remap="tt">$bindaddr</literal>) rather than using the raw perl functions.  This will have the
effect of making these scripts work transparently over socks proxies,
when the socks module is loaded.  If you need some extra functionality,
though (such as UDP sockets, or accepting multiple connections from the
same listening socket), you can use perl's own functions.</para>

<para>To get control back when data is available over a filehandle, you add
it to the set of fh's sirc <literal remap="tt">select()s</literal> from, with</para>

<para><literal remap="tt">&amp;addsel($fh, "somename", flag);</literal>  where sel&lowbar;somename is the sub that will
get control back when there is something to read, and flag is 1 if you
want sirc to buffer the connection and break it into lines for you, and
0 if you don't want sirc to touch the data at all.</para>

<para>The convention for <literal remap="tt">sel&lowbar;somename</literal> subs is different in the two cases:</para>

<para><itemizedlist>
<listitem>
<para>for buffered filehandles, it is passed a single argument containing
a line that was read, including the final <literal remap="tt">\n</literal>.  if the connection is
closed or broken, this argument is <literal remap="tt">''</literal> and the filehandle has been
already closed and removed from the set of fh's to <literal remap="tt">select()</literal> on.  if
you close it yourself, you must use <literal remap="tt">&amp;remsel</literal> to tell sirc to remove
it from the set.
</para>
</listitem>
<listitem>
<para>for unbuffered filehandles, no arguments are passed; the hook is called
when <literal remap="tt">select()</literal> indicates that the fh is ready for reading, and it is
up to the hook to read from it (making sure not to block, so sysread
should be used and not &lt;&gt;), and eventually close it and remove it
with <literal remap="tt">&amp;remsel</literal>.</para>
</listitem>
</itemizedlist>
</para>

<para>To remove a filehandle from the set of fh's being <literal remap="tt">select()ed</literal> on, call
<literal remap="tt">&amp;remsel($fh);</literal>  where <literal remap="tt">$fh</literal> is the filehandle.</para>

<para>Note that sirc never does any checking that a filehandle you give it is
valid.  Having a closed or invalid <literal remap="tt">fh</literal> in the set of <literal remap="tt">select()able</literal> ones,
or not actually reading the data on an unbuffered <literal remap="tt">sel&lowbar;* hook</literal>, will cause
sirc to hog the CPU by not blocking in <literal remap="tt">select()</literal>.</para>

<para>For an example of a nontrivial use of all of this, see the script ftp.pl
which implements an ftp client inside sirc (it can be found at the sirc
webpage at <ulink url="http://www.eleves.ens.fr:8080/home/espel/sirc/sirc.html">http://www.eleves.ens.fr:8080/home/espel/sirc/sirc.html</ulink>).</para>
</sect1>

<sect1 id="bots">
<title>Bots</title>

<para>It is possible to make bots in sirc script, just like you make bots in
ircII.  It's even probably not a bad idea, since you have a proper and
powerful programming language (perl) at your disposition, with all the
boring network programming and parsing of server stuff already done for
you.</para>

<para>However, sirc was never meant as a bot client, and I have no intention
of filling it up with bells and whistles for bot support, so I've only
provided minimal support for this, with the -l and -q options.</para>

<para>The idea is, you program your bot as a set of internal functions and
hooks and a calls to <literal remap="tt">&amp;addhook</literal> and to <literal remap="tt">&amp;docommand</literal>, and then load the sirc
this way (obviously without ssfe):</para>

<para><literal remap="tt">nohup sirc -d -q -l &lt;botfile&gt; -i &lt;bot's ircname&gt; &lt;nick&gt; &lt;server&gt; &gt;/dev/null &amp;</literal></para>

<para>All of this without the <literal remap="tt">&lt;&gt;'s</literal>, of course.  The <literal remap="tt">&gt;/dev/null</literal> is there to
suppress the output, since you won't be reading it on the screen
anyway.</para>

<para>In the bot, make sure you catch (with a numeric hook) the lines that
tell <literal remap="tt">"nick in use"</literal> or <literal remap="tt">"invalid nick"</literal>, and send lines to the server with
some random nick, and get them skipped, or the bot will freeze trying to
ask the user for a nick.  You should also set up a hook on <literal remap="tt">"disconnect"</literal>, and
make it do a <literal remap="tt">&amp;docommand("server 0")</literal> or <literal remap="tt">"server some.server"</literal>.</para>

<para>Also remember that the file gets loaded even before the server connection
is made, so calls to <literal remap="tt">&amp;sl</literal> and most <literal remap="tt">&amp;docommand's</literal> at that point will fail.</para>

<para>Here's an example of a bot that connects, joins a channel, reconnects if
disconnected, responds to a few commands, ops its owner, and logs all it
sees except public stuff to a file; you'd load this one, assuming you
saved it in a file called "mybot" and want to call it BubbleBot, with:</para>

<para><literal remap="tt">nohup sirc -d -q -l mybot -i "bot in sirc" BubbleBot some.server.edu &gt;/dev/null</literal></para>

<para><screen>$botowner="espel\@clipper.ens.fr";	# change it to your address

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

sub hook_publicstuff {		# don't print the public chatter (so it
  $silent=1;			# doesn't fill the logfile
}
&amp;addhook("public", "publicstuff");

sub hook_connected {
  &amp;sl("JOIN #BotTub");
}
&amp;addhook("376", "connected");   # join on the "end of MOTD" numeric

srand;				# init random number generator

sub hook_badnick {
  local($n);
  $n="B".(int(rand(1000000))+4587454);  # send a garbage nick...
  &amp;sl("NICK $n");
  $skip=1;
}
&amp;addhook("432", "badnick");             # if told that ours is taken
&amp;addhook("433", "badnick");

sub hook_disc {         # if we got disconnectedj
  sleep(30);		# wait 30 seconds (so we don't bring the machine
			# down to a crawl if the server is down)
  &amp;docommand("server 1"); # reconnect to the same server
}
&amp;addhook("disconnect", "disc");

sub hook_joined {	# whenever someone joins
  local($ch)=($_[0]);
  $ch =&tilde; tr/A-Z/a-z/;	# put channel in lowercase
  if (&amp;eq($botowner, "$user\@$host") &amp;&amp; $haveops{$ch}) {
    &amp;sl("MODE $ch +o $who");	# op if that's the owner and we have ops
  }
}
&amp;addhook("join", "joined");

sub hook_message {
  if (&amp;eq($botowner, "$user\@$host")) {  # if it's a msg from the owner
    if ($_[0] =&tilde; /^die$/i) {             # die -&gt; die
      &amp;docommand("quit");
    } elsif ($_[0] =&tilde; /^say /i) {        # say &lt;something&gt; -&gt; say it
      &amp;say($');
    } elsif ($_[0] =&tilde; /^nick /i) {       # nick &lt;nick&gt; -&gt; change nicks
      &amp;sl("NICK $'");
    }
# add more commands here
  }
}
&amp;addhook("msg", "message");
</screen>
</para>
</sect1>
</chapter>
</book>
<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-shorttag: t
End:
-->
