README for the TopicEngine
--------------------------

## Quick Start for the impatient:

1. Unpack the archive
2. Put the two TCL files in your eggdrop/scripts directory
3. Edit your eggdrop's config file, and add the following line at the end:

source scripts/TopicEngine.tcl

4. Edit scripts/TopicEngineSettings.tcl in your favourite editor:

- Set the channels list to the channels you want the script to be active in
- Set the maximum length for the topic (120 is a good bet for EFNet, 60 for IRCNet,
  for other networks, try /quote info or talk to your friendly ircop :)
- If you want the bot to say something when it resets the topic after a split,
  set topicAnnounceReset to 1, else 0
- If you want to use a character other than | to split the topic, change the
  topicSeparator setting

5. Rehash your bot.

Everyone who is opped or voiced in a channel will be able to use the commands.

For help on using the script, you can /msg yourbot topic help.


## Slower start for the patient:

1. Do steps one to 4 above.

2. Read the notes for the settings

3. Add lines for your channels with required settings.

(Note that the format of the settings file changed in 1.19!)

If, for example, you want users who have +v in the bot to be able to use
the script in #lamest, add this line:

set topicInfo(#lamest,canFlags) "|v"

To set a default prefix element (perhaps a URL), use "leadIn".

The script will automatically try to learn a topic if one is set directly with /topic.
To disable this, set learnOnChange to 0.

5. Rehash your bot.


## Usage notes:

General syntax:

!topic <command> <parameter>

or for some commands with shortcuts:
!topic <shortcut><parameter>

Where command (shortcut) is:

add (+)		Add the text to the topic
append (<<<)	Add the text to the topic, deleting earlier stuff if needed
insert (>>>)	Add the text to the start of the topic, deleting later stuff if needed
del (-)		Delete an element. The first element is 1; prefixes and postfixes
		cannot be removed with this.
set (=)		Set the topic to the text, removing anything else.
		set prefix (=prefix) will set the prefix
		set postfix (=postfix) will set the postfix
		use "none" to delete the topic/pre-/postfix (!topic =prefix none)
info (?)	Find out about the topic. No parameters will give into on the
		topic as a whole. Use with a number to find out about an element
		(!topic ?2). Use "info undo" to find out about the undo buffer
undo		Reverse the last command.
regexp (/)	Do a regexp find/replace on the topic.
		!topic regexp 3 /hello/goodbye/
		Shortcut: !topic /3/hello/goodbye/
		Options g and i are supported.
clear		clears the topic on irc, but remembers it in the bot. use rehash to
		get it back. clear content will clear everything but the pre-/postfix
		clear all will delete the whole thing.
reset		synonum for clear
lock		locks the topic (channel owner only) from changes
unlock		reverse a lock
rehash (#)	set the topic again. use "rehash force" to force the topic to be set
		even if the bot doesn't think it needs doing. ! is a shortcut for force
		(i.e. !topic #!)

Other shortcuts:

Prefix the topic with @ to lock it at the same time. (!topic add @this will be locked)
Prefix the topic with ~ to delay the update. Here's an example:

1137.27 [  JamesOff] !topic ?
1137.28 [@  NoTopic] #molsoft: topic [ extremely long bit of topic with too
                     many spaces again | extremely long bit of topic with too
                     many spaces again pop jum ] ... changed [ JamesOff | Tue
                     Jan 14 14:21:48 GMT 2003 ]

Delete the first element:
1137.44 [  JamesOff] !topic -~1

Add hello to the end:
[  JamesOff] !topic +~hello
[  JamesOff] !topic ?
[@  NoTopic] #molsoft: topic [ extremely long bit of topic with too
             many spaces again pop jum | hello ] ... changed [ JamesOff
             | Wed Jan 15 11:33:16 GMT 2003 ]  ... buffer [ dirty ]

Note the the buffer is dirty, meaning the bot hasn't updated the topic on IR
to match. A rehash will fix that:

[  JamesOff] !topic #
NoTopic changed the topic of #molsoft to: extremely long bit of topic
   with too many spaces again pop jum | hello

If I hadn't used ~ when adding hello, it would have immediately updated the
topic immediately:
[  JamesOff] !topic +hello
NoTopic changed the topic of #molsoft to: extremely long bit of topic
   with too many spaces again pop jum | hello


## Notes:

* The the script automatically contracts runs of more than one space into one
* Adding a topic with |s in may cause problems if you use | to separate topic elements
* More information may be available on http://www.jamesoff.net/go/topicengine

Enjoy!

James

$Id: README,v 1.3 2003/03/30 21:39:09 jamesoff Exp $
