 |
:: "Welcome Back" ::
IMPORTANT: Running this at the same time as TuxServe can cause problems where both plugins refuse to work! A fix is on its way.
You've probably all seen those fancy mIRC users with their WB (Welcome Back) scripts, welcoming their friends/enemies/random-people back into the channel. You've probably heard some funny quotes that need to be immortalised in a WB script, to haunt whoever uttered them for the rest of their IRC going life. You've probably wanted something like that for XChat. Well, maybe...
I did. So, in the summer of 2003, I decided to put my new found XChat plugin-coding ability to use. I hacked up a very ugly perl script (you can't get non-ugly perl scripts) to do just this. It was also the second usage of the ultra-bright TuxServe theme that has become a theme among all of my plugins/scripts for XChat. A kind of trademark, if you will :)
This script of mine worked fine, blinding people with quotes whenever they returned. It even chose a random quote from the list of saved quotes - none of that just-one-quote crap those mIRC users get. It was the good life... Unless other people wanted to use it, or I needed to add a new quote.
To be honest, neither of those were hard, per se. But they could have been easier. The main reason for this was that all the quotes were hard-coded into the perl script itself - no outside files. This meant that every time I added a new quote, I had to unload the WB script (along with all other perl scripts) and then reload. Another problem was that it worked on all channels that you were in - no matter whether you wanted it to or not.
That script went on being used until early 2004 - collecting quite a few great quotes. But for some long-forgotten reason, it was abandoned and it was forgotten...
Then, about early December 2004 (still in the mood to update old scripts - see Join-up4) I brought back the old WB script. People seemed to like it. /me had an idea. Yep - rewrite
it in C - but make it much more configurable and maintainable. And I did.
Which brings us to around about now: the plugin is ready for release to the public, and documentation needs to be written for it. I'm actually writting this a day or 2 before final release of the code, as there may still be some bugs to be fixed, or other cool stuff to be added. Here's a screenshot of it in action:
Just before I start, I'd like to give a huge amount of thanks to "fuzzybear" for her help. Without her constant badgering (in a good way) and testing, this plugin may have never been released. All the original members of #oldskool on irc.odinnet.ca also need to be thanked for their great quotes :)
This, as with all my work, is released under the GNU/GPL - so feel free to play with it, and/or destroy the code. The link to download it is at the bottom of the page.
:: How To Compile, Install, And Run It ::
First off; how to compile it. After you've downloaded the archive, change directory to where it was saved to, and carry out these instructions:
tar -zxvf wb-0.5.tar.gz
cd wb-0.5
make
make install
"make install" will install the file "wb-0.5.so" and its config file "wb" into "~/.xchat2/", which means that it will load everytime XChat is started. If you don't want this, don't use the command "make install" - or do that, but move it to whereever you want it.
As always, there's Mac OS X support:
tar -zxvf wb-0.5.tar.gz
cd wb-0.5
make xca
make install_xca
This will install both the "wb-0.5.so" and the "wb" files to "/applications/x-chat_aqua/plugins/". If you don't want it there, or if it doesn't work from there, feel free to place it whereever you want.
For the windows version you shouldn't need to compile it (there is a binary included in the archive - "wb.dll"). Just tell X-Chat to load that file and it should work. Eg: "/load wb.dll". I think.
Now that it's compiled and/or installed, you'll want to load it. Go to the text input box of XChat (the bit where you type all your normal text) and type this:
/load <path to wb-0.5.so>/wb-0.5.so
You must include the full path to the the file "wb-0.5.so" (substituting "~/" for your home will also work). Something like:
/load ~/wb-0.5/wb-0.5.so
Or, if you used "make install":
/load ~/.xchat2/wb-0.5.so
Now, you'll probably wanting to use it. To find a list of commands, type:
/wb
This will display something like this:
----------
WB Help ::
----------
/wb help :: This menu.
/wb path <path> :: Changes the config file's path to .
/wb reload :: Reloads the config (only needed when you change the channels).
/wb channels :: Lists all the channels it's set to use.
----------
+ The first command ("/wb help") just shows the help menu as displayed above.
+ The second command ("/wb path <path>") sets a new path for where the plugin should look for its config file. This usually won't need to be used. When you load WB it will first look for the file "~/.xchat2/wb" - if it doesn't find this, it will look for the file "/applications/x-chat_aqua/plugins/wb" (for Mac OS X users). If neither of these files are found, WB will give you an error and you will need to either move the "wb" file to one of the 2 above places, or use the "/wb path <path>" command to point to a different file. This path MUST include the filename! It will also need to be set every time you reload the plugin (there's no way of saving it).
+ The third command ("/wb reload") reloads the channel settings from the config/wb file (see the above command). This command is NOT needed to reload quotes (see below).
+ The forth command ("/wb channels") displays a list of all the channels that it is currently set to check in. The list it displays will only be seen by you - not displayed to a channel. It will only WB people in the channels on this list.
:: The Quote/Config File - How To Set It Up ::
The "wb" file used by this plugin contains both the quotes and the config info it needs to run. This file is just a plain text file, and can be edited with any decent text editor (nano). The structure of the file may seem a bit weird at first, but it does make sense once you know it.
First of all, you'll need to know a few things about how it works. WB can have a list of upto 8 different channels (on multiple networks - but if more than 1 network has the same channel, it will either display the wb on the focussed server or not at all). Alternatively, you can, like in TuxServe, set the channels to "all" so that it will work on every channel that you are in.
The first few lines of the quote/config file (which is the same file) are used to store the names of the channels you want it to respond in. To add a channel, just write the channel's name (eg: "#oldskool") at the top of the wb file. Case doesn't matter on channel names, as they are compared using a case-insensitive function. There must be only 1 channel name per line, and the channel name cannot be longer than 255 characters. WB will only check the first 8 lines of the config file for channel names - so if there are more than 8, or if the channel names are elsewhere in the file, they will be ignored.
All channel names must start with a hash ("#"), with the exception of "all". If you are going to set it to work on all channels, set the first line of the config file to "all" - not followed (or following) any other channel names. Including other channel names before/after "all" could make it act weird.
Now onto the quotes themselves.
The quotes can be in any order, anywhere in the file (but they MUST be after the channels list). You do not have to seperate the quote sections from each other with white space (blank lines), as WB will ignore blank lines, but adding them helps readability and makes it easier for you to update in the future. I advise 1 blank line between each user's quote section.
Each quote is made up of 3 sections: the header, the number of quotes, and the block of quotes itself.
The header is just the nick of the person you want to welcome back, incased in square brackets: "[Aypok]". This needs to be on a line by itself. The nick *IS* case-sensitive! The nick (excluding the brackets) must be no longer than 64 characters.
The number of quotes must be on the line following the header, and must be a normal positive integer number, like "10". This is how many quotes are in the following quote block. It must be manually increased whenever you add a new quote for the person.
The quote block is just a block of quotes that you want to use to welcome this person back with. A quote is chosen randomly by WB whenever they join a channel that WB is set to monitor. You must use only 1 quote per line, and each quote must not exceed 511 characters in length. The quote block must be on the next line after the number of quotes, and there must be no blank lines between each quote (doing so will result in blank welcome back quotes).
The quotes can be anything you want them to be - they can be a quote of something they said (which is what I use it for), or a message/reminder to that person. You can also include coloured, bold, and underlined text in these quotes. There are 2 ways of doing this: You can use the normal mIRC characters - but some text editors don't like these, and some people don't know how to use them. The second way is to use the XChat way: use %C for colours, %B for bold, and %U for underlined. These will work in exactly the same way as they would if enter them into XChat directly - so feel free to test your quotes before saving them :)
I know that may not make a lot of sense, so the best way to show you what I mean is to, uh, show you. Here's a screenshot of Gedit editing a sample wb file:
I know it looks messy - but if you pay attention to the line numbers down the side, it becomes a lot clearer. If you still don't understand it, or want clarification, feel free to drop by on IRC.
:: Help And Other Info ::
Here's a bunch of FAQ type things:
Q: Do I have to reload the plugin or config file for new quotes to take effect?
A: No. the quotes are read each time that someone joins the channel - so, as long as you've saved the new quote to the file, it will find it.
Q: Is there a limit to the number of quotes I can have per person, or on the number of people to welcome back?
A: No. The only limits are on the length of each quote (511 chars) and the number of channels (8).
Q: Instead of a quote, can I include a command to be executed when someone joins - like an action ("/me") or a kick ("/kick ")?
A: Not yet, no - but it may be added soon. Let me know if you want it.
Q: What happens if the line (quote/nick/etc) is longer than it should be?
A: It will be trimmed down to the maximum length.
Q: I want to add styles to my text (bold, colours, underlining, etc). How do I do it?
A: See above (the "How To Set It Up" section) for info.
Q: It won't find the config file. why not?
A: Make sure the file "wb" exists in either "~/.xchat2/" or, if you use Mac OS X, "/applications/x-chat_aqua/plugins/"
Q: I need the text "%C", "%B" or "%U" in the quote, but printed as it is (not as a style code) - how do I do that?
A: You don't. Not yet.
Q: Why does it display the same quote on each channel when someone joins several channels at once?
A: The random-number-generator is seeded with the system time each time it tries to find a quote, and as they join all channels at the same time, the outcome is the same. I may fix this in the next version.
As usual - all comments, suggestions, bug reports, ideas, compliments, money, girls, etc, can be given to me via IRC or email (see the contact button).
Linux/Unix/OS X:
Win32:
|
|
 |
