

This is DreamBot 0.0.7, An Experimental Perl Bot,
(C) 1999-2002 Osman "spectre" Keskin

DreamBot is released under GPL. See the "COPYING" file for more info.
Use it at your own risk. I'm not resposible for any damage caused by it.
(that was a piece of disclaimer, you should have got used to it right?)

*** Please, do read NOTES file! ***


Contents:

  [0] What is?
  [1] Changes
  [2] Features
  [3] Setting it up!
  [4] Commands
  [5] Some other features
  [6] Notes & Troubleshooting
  [7] To Do
  [8] Contacting


                               -------------------
 

  [0] What is?
 
  DreamBot is an IRC Bot, just like the well-known EggDrop. It's written in
perl. Inspired from InfoBot. I was writing it for personal use, then decided
to release it. Thanks to my friend Disq (aka Kemal Hadimli), who encouraged
me to work on it :)

  BTW: DreamBot _requires_ perl 5.005+, it won't work with 5.004.


                               -------------------

  [1] Changes

   - Got rid of the awful, horrible coding style.
   - Fixed babelfish translation.
   - Removed Jabber completely
   - A few document updates


                               -------------------


  [2] Features

   - Everything is totally dynamic, no need to deal with dirty text files
     to add an user or channel etc.
   - It can learn from channel, and you can ask questions
   - Seen support
   - Leaving notes/memos to the people on the bot's userlist
   - Freshmeat/Slashdot backend support
   - Topic locks
   - Channel mode locks
   - Top talkers
   - Console and channel logging
   - Bitch mode
   - Op protection


                               -------------------


  [3] Setting it up!

  There're some files in the package. The one named 'config' contains the
main config of the bot. It looks like this:

  @servers = ('irc.stealth.net:6668','irc.webbernet.net');
  $ident = "dreambot";
  $username = "follow the white rabbit";
  @nicks = ('SunfLare','PornfLare','FunsLare','MarsfLare','MoonfLare');

  $datadir = "./data";
  $logdir = "./logs";

  $log = false;
  $logfile = "./console.log";

  As you can see, the config is pretty easy to do. You can just edit the
server list, ident and username of the bot, nick list that bot can use etc.

  $datadir is the dir that bot stores its data files in.
  $logdir is the dir where the log files lie.

  Then, edit the 'users' file, and add yourself manually with an 'm' flag.
You'll only do this once. File format is:

  <username>:<hostmasks>:<flags>:<channels>

<channels> and <hostmasks> are separated by space. Hostmasks are stored as
regular expressions. So, if you got a hostmask like this:

  ?spectre@*.mylovelyisp.com -> will be -> .?spectre@.*.mylovelyisp.com

  So just put a dot before '?' or '*', everytime. I'll do something about
it so you won't have to deal with that, soon. The syntax of 'users' file is
same as .adduser command's syntax (except hostmasks). See the 'commands'
section for more info about it. And don't forget to give yourself an 'm' flag,
otherwise you won't be able to use any command. (btw, theorically, the dots
should be escaped in the hostmasks, but for the sake of simplicity, you can
ignore it)


  - Examples:

  spectre:.*spectre@.*.mylovelyisp.com:mo:*
  disq:.?disqk@.*.ticaretnet.com .?disqk@195.174.236..*:mo:#scene.tr #chan


  After you added yourself, you're ready to run the bot. You can /msg the bot
to add a channel with .addchan.

  And, in order to cron the bot, take a look at the 'cron' file included in the
package.

  Also, use 'dreambot' script to run and cron the bot. Edit 'dreambot' file,
and correct the path at the end of the file.

  - Parameters:

  -c --config <config>        use the <config> file for configuration
  -d --datadir <datadir>      sets the datadir, default is set in config file
  -h --help                   help


                               -------------------


  [4] Commands
  
  There're many commands that can be used from irc. These commands are for
modifying userbase, hostnames, channels, or anything you can imagine. Commands
start with a dot '.' and the command follows. You can write commands on the
channels the bot is on, or you can just /msg the bot. Commands are only
available for users that has [m]aster status (the "m" flag), and must be
lowercase.

  Those commands are:

.rehash -or- .load
  Reloads all the stuff that matters. (userlist, facts, and notes)

.raw <text> -or- .order <text> -or- .quote <text>
  Sends raw <text> to server. For any condition, to help masters.

.ctcp <user> <text>
  Like doing /ctcp <user> <text>, that does the same. You can make the bot
ctcp version someone by doing .ctcp someone version.

.cycle <channel>
  Cycling is not automated yet, but you can make the bot cycle a channel
(rejoining to regain ops) by doing .cycle <channel>

.addchan <channel> <flags> -or-
.setchan <channel> <flags>

  Adds or Updates <channel>

  <channel> is the name of the channel,
  <flags> are:
  
         log: When enabled, logs the channel to the file
	      <logdir>/[channelname].log

    modelock: If enabled, channel's modes will be reset to <modes>
              when it's changed or empty.

   topiclock: If set on, the topic of the chan can't be changed, bot resets it
              back when it changes.

       bitch: (bitchmode) Deops people that doesn't have an 'o' flag. And only
              allows people that has 'o' flag to be op.

      opprot: (op protection) Deops people who deops anyone with an 'o' flag.
              And recovers the person's op.

       modes: To set the channel modes for modelock. Example: +modes nt

         key: Sets the key for channel. It doesn't set +k channel mode. It just
              teaches the bot the channel key if it's +k.

  needinvite: This flag allows the bot to msg some other bot or person to
              request inviting to the channel if the channel is +i.
	      Syntax: +needinvite <user> <nick> <msg>.
	      Example: +needinvite spectre spekka invite me
	      The bot will /msg me if the channel is +i and say "invite me".

   freshmeat: (enabled by default) Allows the bot to announce freshmeat news on
              the channel. Otherwise only /msg'ing the bot will work.

    slashdot: (enabled by default) Same thing for slashdot.


  - Examples:
  
    .addchan #dreambot +log +modes nt -bitch -slashdot

      Enables the channel logging and disables bitch mode, and sets the modes
      to 'nt'
    
    .addchan #blabla

      Just adds the channel without any flag (currently all of the flags will
      be disabled by default)

    .addchan #blabla -freshmeat +needinvite spectre sPec^fLR invite me -bitch

      You guess.

  - Notes:

    Bot automatically joins when you add a channel.


.remchan <channel>
  Removes <channel> from channel list. And bot leaves the channel.

.chaninfo [<channel>]
  Prints channel flags (topiclock, modelock, bitchmode, op protection)

.adduser <user> <hostmasks> <flags> <channels> -or-
.setuser <user> <hostmasks> <flags> <channels>
  Adds -OR- Updates an user record. <user> is the name of the record.
<hostmasks> must be separated by comma.

  - Examples:

  .adduser spectre spectre@*.mylovelyisp.com mo #flare #scene.tr
  .adduser disq ?disqk@*.ticaretnet.com,?disqk@195.174.236.* mo *

  - Flags:

  There're currently 4 flags. Those are:

    m -> Master status
    o -> Auto op
    v -> Auto voice
    b -> Auto ban
    n -> Nick serv

  That's it :)

    If you add an user with 'n' flag, you need to specify nickserv password
  on the channel field, like:
  
  .adduser nickserv s@NickServ n mypassword


  - Channels:
  
  Channels that user have access on. Separated by space. You can just write
"*" to give access on every channel.

.remuser <user>
  Deletes the user record <username>

.showuser <user>
  Shows the user record (hostnames, flags, and channel access list).

.serverlist
  Prints the server list.

.userlist
  Lists all users.

.chanlist
  Prints the channel list.

.save
  Saves all the stuff that matters. Userbase, facts, notes (memos), topiclock
status, seen db and top talkers.

.topiclock <on/off> [<channel>]
  Enables or disables the topiclock on current channel. When set on, if someone
tries to change the topic, bot sets it back. Specify <channel> when you /msg
the bot.

.modelock <on/off> [<channel>]
  Enables or disables the modelock on current channel. When set on, if someone
tries to change the channel modes, bot sets them back. Specify <channel> when
you /msg the bot.

.bitchmode <on/off> [<channel>]
  Enables or disables the bitchmode on current channel. When set on, if someone
ops a person who doesn't have an 'o' flag (op status), bot deops the person.
Specify <channel> when you /msg the bot.

.opprot <on/off> [<channel>]
  Enables or disables the op protection on current channel. When set on, if
someone tries to deop any person who has an 'o' flag (op status), bot ops the
person, and deops the guy who deopped the person. Specify <channel> when you
/msg the bot.

.log <on/off> [<channel>]
  Enables or disables the channel logging. When set on, it logs the channel to
the file <logdir>/[channelname].log. You can set logdir in config. Specify
<channel> when you /msg the bot.

.nick <nick>
  Changes bot's nick to <nick>.

.join <channel>
  Bot joins <channel>. It just joins. It doesn't add <channel> to the channel
list. If you wanna add the channel, use .ADDCHAN command.

.part <channel>
  Bot leaves <channel>. It doesn't remove <channel> from the channe list. If
you wanna remove the channel, use .REMCHAN command.

.say <channel> <text>
  Makes bot say <text> on <channel>.

.topic <channel> <topic>
  Makes bot set <topic> on <channel>.

.mode <channel> <modes>
  Makes bot set <modes> on <channel>.

.op <person> [<channel>]
  Bot ops <person>. Specify <channel> when you /msg the bot.

.d[e]op <person> [<channel>]
  Bot deops <person>. Specify <channel> when you /msg the bot.

.kick <channel> <nick> <reason>
  Makes bot kick <nick> outta <channel> with <reason>.

.ban <channel> <hostmask>
  Makes bot ban <hostmask> on <channel>

.unban <channel> <hostmask>
  Makes bot unban <hostmask> on <channel>

.flag[s] <user> [+/-]<flags>
  Sets, adds or removes user flags.
 
  - Examples:
  
  .flags disq +m		Adds master status to user disq
  .flags disq -m		Removes master status from user disq
  .flags spectre mo		Sets flags m and o for user spectre

.addhost <user> <host>
  Adds a new hostmask to user <user>. See command .ADDUSER for more info
about hostmasks.

.remhost <user> <host>
  Removes the hostmask <host> from <user>.

.addchanuser <user> <chans>
  Gives user <user> access on channels <chans>. You can't add "*" with this
command.

.die [<reason>]
  Kills the bot with a quit reason [reason] if specified.

.restart [<reason>]
  Restarts the bot.

.jump <server>[:<port>]
  Jumps to a new server. Warning: this command doesn't add <server:port> to
server list of the bot. (@servers)

.help [<command>]
  Guess what


                               -------------------


  [5] Some other features
  
  Bot can do some more things. It has the ability of learning, You can ask
questions, receive freshmeat/slashdot headlines, leave notes to other people.


  - It learns!
  
  If you write something like that:
  
  <spectre> The Matrix is a great movie!
  
  It'll learn and know that the matrix is a great movie :) and able to answer
the well-known question: What is The Matrix?

  It'll catch all the crap from the channel that includes "is" "are" and so on,
It may not be accurate or intelligent, but sometimes it's useful, and fun! :)
If you want the bot to answer your question, you gotta ask it _to_ the bot:

  <spectre> MyBot: What is The Matrix?

  or,

  <spectre> ?? The Matrix
  (no addressing required)

  or,

  <spectre> MyBot: The Matrix?
  (addressing required)

  You can also use "=" to teach the bot:
  
  <spectre> MyBot: The Matrix = great movie

  Also, you can use "<reply>" tag, which is the same thing from infobot.

  <spectre> MyBot: matrix is <reply> you gotta see it for yourself.
  <spectre> MyBot:

  You can also teach several things on the same line using sentences:

  <spectre> MyBot: disq is your friend. d4 3v1l is your enemy.
  <spectre> MyBot: who's disq?
  <MyBot> spectre: disq is my friend
  <spectre> MyBot: who's d4 3v1l?
  <MyBot> spectre: d4 3v1l is my enemy.

  That's all :)


  - Freshmeat and Slashdot Headlines:

  Examples:
  <spectre> SunfLare, freshmeat headlines
  <spectre> SunfLare, /.
  <spectre> SunfLare, slash

  Etc. You know what will it do? Yes you do. It'll fetch headlines from
freshmeat.net and slashdot.org, and print them. Pretty easy.

  Valid keywords are:
   - fm
   - fresh
   - freshmeat
   - /.
   - slash
   - slashdot
  'headlines' or 'news' can be appended.


  - Leaving/Reading and Deleting Notes (Memos):
  
  You can leave a msg to someone by doing:
  <spectre> MyBot, note to disq: cabbar is cool!
  
  It'll tell disq he got a note waiting when he joins to a channel the bot
is on.

  To read notes: /msg MyBot read notes
  <MyBot> [0] spectre: cabbar is cool!
  
  To delete all notes: /msg MyBot delete notes
  To delete a specific note: /msg MyBot delete note 0


  - Seen support:

  That's the well-known and useful "seen" support:

  <spectre> MyBot, seen disq?
  <MyBot> spectre, disq is on the channel right now, don't you see?!
  <spectre> MyBot, oh really? see how stupid i am..


  - TopTen Talkers:

  Bot counts how many letters people write on the channels. And sorts them.
You can see the topten talkers by asking the bot like this:

  <spectre> MyBot, topten?

  You can redirect the output to any channel when you /msg the bot:
  /msg MyBot topten #scene.tr?

  And output will appear on #scene.tr

  <spectre> MyBot, place?
  Outputs my rank.
  
  <spectre> MyBot, place cash?
  Outputs cash's rank.

  And also,
  
  <spectre> MyBot, count [user]?
  Outputs how many letters the [user] (or yourself) wrote.


  - Babelfish/Translation support:

  Just a few examples are enough:

  <spectre> MyBot, translate to de: hey man, what's up?
   that'll translate "hey man, what's up?" to german.
  
  <spectre> MyBot, translate from de: hallo
   that'll translate "hallo" to english.

  You can use xlate, xl instead of 'translate' word:
  
  <spectre> MyBot, xlate to fr: I love you!
  <MyBot> spectre, translation: Je vous aime!

  Available languages are (currently):
    fr -> french
    de -> german
    it -> italian
    pt -> portuguese
    es -> spanish

  If bot says an error occured, it means it didn't get the expected answer
  from babelfish. There're two common reasons for that, either babelfish's
  translation server is unavailable at the moment (it happens), or babelfish
  changed its interface and bot couldn't recognize it. Of course that also
  can occur if bot can't connect to the server, etc.

  Translations are done in the background, thus, it doesn't block the bot
  while waiting for translated text to transfer.


  - User Password support:
  
  Now, every user can have a password, which will be encrypted using crypt()
and stored in 'passwd' file.

  To set your password: /msg mybot pass <yourpass>
 
  And then you can get ops using /msg mybot op <yourpass> as though using an
eggdrop. And it'll give you op in the channels you've access on.


                               -------------------


  [6] Notes & Troubleshooting

  - The bot prints an error about "?:" regexp stuff and quits? Then your perl
    version is not 5.005+. Unfortunately DreamBot requires 5.005+ to work.
    Check your perl version with "perl --version". And upgrade it.

  - Bot saves its pid to ~/.dreambot.pid and uses that file as a lock file.
    If bot doesn't run when you run it, remove ~/.dreambot.pid and re-run.
    'dreambot' script does that automatically. Useful for croning etc.

  - Bot saves its data files hourly.

  - And also, I'm sure a lot of bugs exist in this release, so please calm
  down. Hey I said calm down! And just inform me instead.


                               -------------------


  [7] To Do
  
  - Flood protection
  - Ban protection
  - Auto inviting users with an 'i' flag


                               -------------------


  [8] Contacting


  That's all! Now you can go config your bot, run it and pray. Don't forget
to send me your comments, suggestions, and everything about it. Please join
the survey on the project page.

  Email: spectre@theplanes.org
    ICQ: 17944437

  IRC Support channel (on OpenProjects): #dreambot
  (you can use irc.openprojects.net, irc.stampede.org, irc.linux.com etc)

  DreamBot Homepage: http://dreambot.sourceforge.net
       Project Page: http://sourceforge.net/projects/dreambot
