# The KSirc Handbook

Andrew
Stanley-Jones

    asj@chowtown.cban.com

Philip
Rodrigues

    phil.rod@ntlworld.com

2001-07-25
1.10.00
&FDLNotice;

This documentation describes &ksirc; 1.1, the &kde; &irc; client.

KDE
KSirc
irc
Internet relay chat

## Introduction

&ksirc; is the default &kde; &irc; client. It supports scripting with Perl and has a lot of compatibility with &mirc; for general use.

## Using &ksirc;

### If you haven't used &irc; before...

Simply put, &irc; is a chat protocol, defined by official Internet standards, and capable of stealing many hours of your life. To use &irc;, you must connect to a server, and then join a channel (equivalent to a chat room).

To connect to a server, open &ksirc; and select Connections New Server or press F2. In the dialog box that is displayed, select a group from the leftmost drop-down box and then a server from the middle drop-down box. The port, shown on the right, will almost always be 6667. A new window will be displayed showing the messages sent by the server to the client. When these messages have finished scrolling past, you want to choose your channel. To display a list of available channels, type ``/list``. To join a channel, type: ``/join` #channelname`. To leave a channel, just type ``/part``.

That's the basics, for more detailed information, read on...

### &ksirc; Basics

#### Servers

&ksirc; allows you to connect to an arbitrary number of servers. To connect to a server, select Connections New Server or press F2.The Connection Dialog appears, and you can select a Group, then a Server, and also a Port to connect to.

Just click Connect when you're done, and a new window for the server is displayed. You can keep track of the servers you're connected to in the &ksirc; Server Control window.

#### Channels

You can connect to channels with the normal ``/join``, by selecting Connections Join Channel or by pressing F3.

Channels you are connected to are shown in the Server Control window under the server to which the they belong. To leave a channel, you can `/part`, select Channel Close or press &Ctrl;W.

#### Channel Options

The Channel menu, available in any channel window, contains some useful options:

&Ctrl;T Ticker Mode

  Displays the channel like a stock or a news ticker. Note that this mode does not allow you to enter text into the channel. To exit Ticker Mode, right click the ticker, and select Hide....

&Ctrl;S Save to Logfile...

  Saves the contents of the channel to a file.

&Ctrl;A Time Stamp

  Prepends each thing said in the channel with the time it was said, in the form HH:MM

#### Users

In a channel, the user list is displayed along the right hand side. Right-clicking a nick in that list gives you some options, most of which are self-explanatory:

Refresh Nicks

  Sends a message to the server to request the list of users in the channel.

Follow

  Follows the user into whatever channels he goes to.

unFollow

  Stops following the user.

Whois

  Sends a CTCP whois query to the user, which provides information about the user, such as their hostname and what server they are connected to.

Ping

  Sends a CTCP Ping to the user, to determine their echo time.

Version

  Sends a CTCP Version to the user, to determine what software they are using.

Abuse

  Abuses the user in one of various amusing ways.

The following commands are only available if you are an operator on the channel:

Kick

  Kicks the user off the channel.

Ban

  Bans the user from joining the channel.

unBan

  Removes the ban on the user joining the channel.

Op

  Gives the user operator privileges.

DeOp

  Removes operator privileges from the user.

## &ksirc; Colors

&ksirc; follows the color scheme used by &mirc; and a slight modification for more powerful in house use.

    <fg> == foreground
    <bg> == background
    &lsqb;&rsqb; == optional

### &mirc; compatibility

Format:

- `0x03<fg>&lsqb;,<bg>&rsqb;` sets the foreground and background

- `0x03` resets to defaults for THAT line

### &ksirc; native

Format:

- `˜<fg>&lsqb;,<bg>&rsqb;` sets the foreground and background

- `˜c` resets to defaults

- `˜b` sets bold font

- `˜u` sets underline

- `˜i` sets italics

- `˜r` sets underline

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

### Color Numbers

1. white

2. black

3. blue

4. green

5. red

6. brown

7. purple

8. orange

9. yellow

10. lightGreen

11. cyan

12. lightCyan

13. lightBlue

14. pink

15. gray

16. lightGray

### Sending Bold, Underline, Reverse, and Color

You can use the following key combinations to insert control codes in text:

- &Ctrl;B for bold text

- &Ctrl;U for underlined text

- &Ctrl;R for reverse text

- &Ctrl;K for colored text

- &Ctrl;O for plain text

### Examples

To underline a single word in a sentence:

1. Type &Ctrl;U

2. Type in the word

3. Type &Ctrl;U again

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.

The &Ctrl;K control code is slightly different because it allows you to specify a color number. To color a single word in a sentence:

1. Type &Ctrl;K

2. Type a number between 0 and 15

3. Type the word

4. Type &Ctrl;K again

If you also want to change the background color 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 color, the second number is the background color. The colors range from 0 to 15, the index is in the previous section.

You can enclose text in multiple control codes, so for example you could have a bold, underlined, and colored word.

## Filters

### Filter Rules and How to Make them

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

The filter tries to find the match string then use the From and To as a substitution. The match, from and to are all Perl regex expressions. Rules are evaluated in descending order. The top rule is evaluated first, then the second from the top, &etc; All strings are evaluated as:

`$name` is expanded to the environment variable `name`. This is done immediately when you insert the rule, and will not change after that time. Therefore it's probably of limited value.

`$$name` is substituted with the perl `$name` 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;).

`˜name˜` PREPENDED ONCE AND ONLY ONCE to the line will send the line of text to the window called name. 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 `!`:

`!default`

  The current default window. Guaranteed to exist.

`!all`

  Send to every window. This might not show up on all windows, depending on how the text is parsed. For example, channel windows won't show a part/quit unless the nick is on the channel.

`!discard`

  discards the text.

The rest of the expression is dealt with as normal Perl regex. A good understanding of the `perlre` man page will definitely help, but a basic understanding of regex is most certainly required.

### Examples:

1. Want to convert all boren from boren to BoreN

       Match: .*
       From: boren
       To: BoreN

   Pretty straight forward, match anything, then substitute boren with BoreN.

2. You want to match everything with boren in it and send to the window called boren

       Match: boren
       From: ˆ
       To: ˜boren˜

   Looks for boren if found, substitutes the beginning of the string (ˆ) with ˜boren˜.

3. Though the previous example works, if the string already has `˜somewindow˜` on it, you'll now have two `˜boren˜˜somewindow˜...` So you can do this instead.

       Match: boren
       From: ^(?:˜\S+˜)
       To: ˜boren˜

   Ok, the from line is a little bit more complicated. It means: match 0 or 1 copies of `˜\S+˜`. Which is 1 tilde, one or more non-whitespaces, and then another tilde. The paranoid might do `(*:˜\S+˜)`, which means: match 0 or more channel directives in case prior rules are broken.

4. Server kill messages tend to be long, ugly, annoying, &etc; A basic message on dalnet looks like:

       *** 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[2008.1.222.222]!services.dal.net
       (NickServ Enforcement)

   When you're `+s` 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.

       Match: ^\*\*\*.* KILL message for.*
       From:  Path: \S+
       To: .

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

   The From line means: substitute " Path: " and any non-whitespace characters with the To. To is a `"."` therefore the entire path turns into a single period.

   The message now looks like:

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

   Notice the new `"."` after `NickServ`?

5. Ok, the message is a lot cleaner, but KILLs from nickserv aren't really that important, so let's forward them to the `!discard` window.

       Match: ^\*\*\*.*KILL message.*\(NickServ Enforcement\)
       From: ^(?:˜\S+˜)
       To:  ˜!discard˜

   Match rule searches for the KILL message and makes sure it's from NickServ. Notice the `\(` and `\)` both `()` and used in regex, therefore we have to quote them. This is very similar to example 3.

6. 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:

       *** [KILL] <KILLER> killed <KILLED> (reason)
       Match: \*\*\*.*KILL message
       From: \*\*\*.*for (.*?) from (.*?)\. \((.*?)\).*
       To: *** [KILL] $$2 killed $$1 ($$3)

   Ok, the match looks for `***something` KILL message. We can't use `ˆ` since we may have just appended `˜<window>˜`.

   The from line get's a little more interesting. The `"for (.*?) "` looks for the word "for" then some text. `.*?` means: 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 is encountered. The surrounding `()` means: save the contents. Each () saves the matched data in `$&num;` where `&num;` starts at 1 for the first substring, &etc; In this case, `$1` gets the nick/user-info of the person killed. `$2` is then filled with the name of the killer. Between the `()` we have the reason for the kill. Here the `(` and `\(` get a little confusing. Remember `\(` matches the actual character `'('`.

7. How to colorize your life. Ok, you want to add some color to &ksirc;. See the Colors section for color info, but here's a filter rule to highlight the nick between `<NICK>` on each line:

       Match: ^(?:˜\S+˜)<\S+>
       From: <(\S+)>
       To: <˜4$$1˜c>

   Takes the nick and adds color &num;4 between the two `<> ˜c` clears the color.

## Keys

This is a listing of the short cut and command keys available under &ksirc;.

### Keybindings

Keybinding | Action
--- | ---
&Alt;F | Open the File menu.
&Alt;E | Open the Edit menu.
&Ctrl;N | Open a new Channel/Query Window
&Ctrl;T | Ticker Mode
&Ctrl;Q | Quit
&Ctrl;X | Cut Window
&Ctrl;V | Paste
&Ctrl;Enter | Begin a message to the most recent person to send you a message
&Ctrl;&Shift;Enter | Begin a message to the next to last person to send you a message
&Ctrl;K | Start color code (with a number, text you type after this will be colored)
&Ctrl;U | Begin or end underlining text. Text after the first occurrence of this will be underlined until you type it again.
&Ctrl;I | Begin or end italic text. Text after the first occurrence of this will be italic until you type it again.
&Ctrl;B | Begin or end bold text. Text after the first occurrence of this will be bold until you type it again.
&Ctrl;R | Begin or end reverse video text. Text after the first occurrence of this will be reversed until you type it again.
Tab | Tries to complete the nickname of someone on the channel, based on the text you entered. You are probably familiar with this from your commandline shell.

## Credits and Licenses

&ksirc; copyright 1997-2001, the &ksirc; developers.

Portions of documentation copyright 1997, Andrew Stanley Jones

Documentation updated for &kde; 2.2 by Philip Rodrigues phil.rod@@ntlworld.com

&underFDL; &underGPL;

## Installation

### Where to get &ksirc;

&ksirc; is part of the &kde; Project . You will find the current version of &ksirc; in the kdenetwork package at ftp://ftp.kde.org/pub/kde , the &FTP; server of the &kde; project.

### Requirements

If you want to install &ksirc;, you need at least a &kde; 2.2 installation.

If you intend to compile and install &ksirc; yourself, you have to make sure that the following programs are present on your system:

- g++ 2.8 / egcs 1.0.3 (or compatible)

- GNU make

- autoconf 2.1

- automake 1.4

- Qt 2.2.x

- KDE 2.1

### Compilation and Installation

&ksirc; is part of the kdenetwork package of &kde; 2.2 and is installed together with it. In general, there is no need for the user to compile the source code of &ksirc; by hand. If you nevertheless intend to do so, or if you have only the source code available, compilation and installation is, as usual on Linux, done by typing:

    % ./configure
    % make
    % su -c "make install"

&ksirc; uses `autoconf` and `automake`, so no problems should occur during the compilation process. If you do hit on any problems though, please contact the &kde; developers mailing list kde-devel@master.kde.org.