home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / bx75p3.zip / doc / tcl-commands.doc < prev    next >
Text File  |  1999-02-23  |  38KB  |  1,021 lines
  1. This is an exhaustive list of all the Tcl commands added to eggdrop.  All
  2. of the normal Tcl built-in commands are still there, of course.  But you
  3. can also use these to manipulate features of the bot.  They are listed
  4. according to category.
  5.  
  6. NOTICE:  Quite a lot has changed in the transition to v1.0!
  7. SCRIPTS WHICH WERE WRITTEN FOR v0.9 WILL PROBABLY NOT WORK WITHOUT SERIOUS
  8. MODIFICATION.  To help along the transition to v1.0 scripts, I have marked
  9. the changed commands (and new ones) by putting vertical bars to the left.
  10. Anything that uses those commands will need to be changed for v1.0.
  11.  
  12.  
  13.  
  14. *** OUTPUT COMMANDS ***
  15.  
  16.   putserv <text>
  17.     sends text to the server, like 'dump' (intended for direct server
  18.       commands)
  19.     returns: nothing
  20.  
  21.   puthelp <text>
  22.     sends text to the server like 'puthelp', but uses a different queue
  23.       (intended for sending messages to channels or people)
  24.     returns: nothing
  25.  
  26. | puterror <text>
  27. |   [no longer exists: use putlog]
  28.  
  29.   putlog <text>
  30.     sends text to the log for any channel, marked as 'misc' (o)
  31.     returns: nothing
  32.  
  33.   putcmdlog <text>
  34.     sends text to the log for any channel, marked as 'command' (c)
  35.     returns: nothing
  36.  
  37.   putxferlog <text>
  38.     sends text to the log for any channel, marked as 'file-area' (x)
  39.     returns: nothing
  40.  
  41. | putloglev <level> <channel> <text>
  42. |   sends text to the log, marked as one of the user levels, 1-5, and
  43. |     sent to the appropriate channel level
  44. |   returns: nothing
  45.  
  46. | dumpfile <nick> <filename>
  47. |   dumps out a file from the text directory to a user on IRC via
  48. |     msg (one line per msg); %( and %[ won't work because it will
  49. |     assume the user is not an op or master
  50.  
  51.  
  52. *** USER RECORD MANIPULATION COMMANDS ***
  53.  
  54.   countusers
  55.     returns: number of users in the bot's database
  56.  
  57.   validuser <handle>
  58.     returns: "1" if a user by that name exists; '0' otherwise
  59.  
  60.   finduser <nick!user@host>
  61.     finds the user record which most closely matches the given user@host
  62.     returns: the handle found, or "*" if none
  63.  
  64.   userlist [flags]
  65.     returns: a list of the handles of users on the bot -- if you specify
  66.       flags, only users who have ALL of those flags will be in the list
  67.  
  68.   passwdok <handle> <pass>
  69.     checks the password given against the user's password -- if the user has
  70. |     not set a password, will always return "1"; check against the password
  71. |     "" (a blank string) to find out if a user has no password set
  72.     returns: "1" if password matches for that user; "0" if not
  73.  
  74.   chpass <handle> <pass>
  75.     attempts to set a new password for a user, if that user exists
  76.  
  77.   chhandle <old-handle> <new-handle>
  78. | chnick <old-handle> <new-handle>
  79.     changes a user's handle (they are the same command)
  80.     returns: "1" on success; "0" if the handle is already used, the handle
  81.       is invalid, or the user can't be found
  82.  
  83.   chattr <handle> [changes]
  84.     changes the attributes for a user record, if you include any -- changes
  85.       are of the form "+f", "-o", "+dk", "-o+d", etc
  86.     returns: new flags for the user (if you made no changes, returns current
  87.       flags) -- returns "*" if that user does not exist
  88.  
  89.   matchattr <handle> <flags>
  90.     returns: "1" if the specified user has ALL the flags requested
  91.  
  92.   adduser <handle> <hostmask>
  93.     creates a new user entry with the handle and hostmask given (with no pass-
  94.       word, and the default flags)
  95.     returns: "1" if successful, "0" if it already existed
  96.  
  97. | addbot <handle> <address>
  98. |   creates a new bot entry with the handle and bot linking address given
  99. |     (with no password and no flags)
  100. |   returns: "1" if successful, "0" if it already existed
  101.  
  102. | deluser <handle>
  103. |   attempts to erase a user record with that handle
  104. |   returns: "1" if successful, "0" if no such user exists
  105.  
  106.   addhost <handle> <hostmask>
  107.     adds a hostmask to the hostmask list for a user
  108.     returns: nothing
  109.  
  110.   delhost <handle> <hostmask>
  111.     deletes a hostmask from a user's hostmask list
  112.     returns: "1" on success, "0" if that hostmask wasn't in the list or the
  113.       user does not exist
  114.  
  115.   gethosts <handle>
  116.     returns: the hostmask list for that user if there are any, "none" if
  117.       the user exists but there are no hostmasks, "" if the user doesn't
  118.       exist
  119.  
  120. | getinfo <handle>
  121. |   returns: info line for that user ("" if none exists); always returns
  122. |   an empty string for bots
  123.  
  124. | getaddr <handle>
  125. |   returns: link address for that bot ("" if none exists); always returns
  126. |   and empty string for non-bots
  127.  
  128.   getdccdir <handle>
  129.     returns: dcc directory for that user ("" if none exists)
  130.  
  131.   getcomment <handle>
  132.     returns: comment for that user ("" if none exists)
  133.  
  134.   getemail <handle>
  135.     returns: email address for that user ("" if none exists)
  136.  
  137.   getxtra <handle>
  138.     returns: xtra info for a user ("" if none exists)
  139.  
  140.   getlaston <handle>
  141.     returns: last time that user was on the channel (in unixtime format)
  142.  
  143.   setinfo <handle> <info>
  144.     sets the info line for a user
  145.     returns: nothing
  146.  
  147.   setdccdir <handle> <dccdir>
  148.     sets the dcc directory for a user
  149.     returns: nothing
  150.  
  151.   setcomment <handle> <comment>
  152.     sets the comment for a user
  153.     returns: nothing
  154.  
  155.   setemail <handle> <email>
  156.     sets the email address for a user
  157.     returns: nothing
  158.  
  159.   setxtra <handle> <xtrastuff>
  160.     sets the xtra info for a user (this field exists specifically to be used
  161.       by Tcl scripts)
  162.     returns: nothing
  163.  
  164. | setlaston <handle> [timestamp]
  165. |   sets the last time the user was on the channel to the current time (or
  166. |     the time you specify, in unixtime)
  167. |   returns: nothing
  168.  
  169. | newchanban <channel> <ban> <creator> <comment> [lifetime]
  170. |   adds a ban to the enforced ban list of a channel; creator is given
  171. |     credit for the ban in the ban list; lifetime is specified in
  172. |     minutes; if lifetime is not specified, ban-time (usually 60) is
  173. |     used; setting the lifetime to 0 makes it a permanent ban
  174. |   returns: nothing
  175.  
  176. | newban <ban> <creator> <comment> [lifetime]
  177. |   adds a ban to the global ban list (which takes effect on all channels);
  178. |     other arguments work exactly like newchanban
  179. |   returns: nothing
  180.  
  181. | killchanban <channel> <ban>
  182. |   removes a ban from the enforced ban list for a channel
  183. |   returns: "1" if successful, "0" otherwise
  184.  
  185. | killban <ban>
  186. |   removes a ban from the global ban list
  187. |   returns: "1" if successful, "0" otherwise
  188.  
  189.   addban <ban> <channel> [comment]
  190.     [this command is obsolete and will eventually be removed; use newchanban]
  191.  
  192.   addglban <ban> [comment]
  193.     [this command is obsolete and will eventually be removed; use newban]
  194.  
  195.   delban <ban> <channel>
  196.     [this command is obsolete and will eventually be removed; use killchanban]
  197.  
  198.   delglban <ban>
  199.     [this command is obsolete and will eventually be removed; use killban]
  200.  
  201. | isban <ban> [channel]
  202. |   returns: "1" if that ban is in the global ban list, "0" otherwise; if
  203. |     a channel is specified, that channel's ban list is checked too
  204.   
  205. | ispermban <ban> [channel]
  206. |   returns: "1" if that ban is in the global ban list AND is marked as
  207. |     permanent, "0" otherwise; if a channel is specified, that channel's
  208. |     ban list is checked too
  209.  
  210. | matchban <nick!user@host> [channel]
  211. |   returns: "1" if that user address matches a ban in the global ban list,
  212. |     "0" otherwise; if a channel is specified, that channel's ban list is
  213. |     checked too
  214.  
  215. | banlist [channel]
  216. |   returns: list of global bans, or (if a channel is specified) list of
  217. |     channel-specific bans; each entry is itself a list, containing:
  218. |     hostmask, comment, expiration timestamp, time added, last time
  219. |     active, and creator (the three timestamps are in unixtime format)
  220.  
  221. | newignore <hostmask> <creator> <comment> [lifetime]
  222. |   adds an entry to the ignore list; creator is given credit for the
  223. |     ignore; lifetime is how many minutes until the ignore expires and
  224. |     is removed; if lifetime is not specified, ignore-time (usually 60)
  225. |     is used; setting the lifetime to 0 makes it a permanent ignore
  226. |   returns: nothing
  227.  
  228. | killignore <hostmask>
  229. |   removes an entry from the ignore list
  230. |   returns: "1" if successful, "0" otherwise
  231.  
  232. | ignorelist
  233. |   returns: list of ignores; each entry is itself a list, containing:
  234. |     hostmask, comment, expiration timestamp, time added, and creator
  235. |     (the three timestamps are in unixtime format)
  236.  
  237.   addignore <nick!user@host>
  238.     [this command is obsolete and will eventually be removed; use newignore]
  239.  
  240.   addpermignore <nick!user@host>
  241.     [this command is obsolete and will eventually be removed; use newignore]
  242.  
  243.   delignore <nick!user@host>
  244.     [this command is obsolete and will eventually be removed; use killignore]
  245.  
  246. | isignore <hostmask>
  247. |   returns: "1" if the ignore is in the list, "0" otherwise
  248.  
  249.   save
  250.     writes the userfile to disk
  251.     returns: nothing
  252.  
  253. | reload
  254. |   loads the userfile from disk (replacing whatever's in memory)
  255.  
  256. | getting-users
  257. |   returns: "1" if the bot is currently downloading a userfile from
  258. |     a sharebot (and hence, user records are about to drastically
  259. |     change), "0" if not
  260.  
  261.  
  262. *** CHANNEL COMMANDS ***
  263.  
  264. | channel add <name> <option-list>
  265. |   adds a channel record for the bot to monitor; the full list of possible
  266. |     options is given in the "lamestbot" sample config file; note that the
  267. |     channel options must be in a list (enclosed in {})
  268. |   returns: nothing
  269.  
  270. | channel set <name> <options...>
  271. |   sets options for the channel specified; the full list of possible
  272. |     options is given in the "lamestbot" sample config file
  273. |   returns: nothing
  274.  
  275. | channel info <name>
  276. |   returns: list of info about that channel record: enforced mode, idle
  277. |     kick limit, need-op script, need-invite script, and then various
  278. |     +/- options as seen in the config file
  279.  
  280. | channel remove <name>
  281. |   destroys a channel record for the bot and makes the bot no longer
  282. |     monitor that channel
  283. |   returns: nothing
  284.  
  285. | channels
  286. |   returns: list of the channels the bot is monitoring (or trying to)
  287.  
  288. | botisop <channel>
  289. |   returns: "1" if the bot is an op on that channel; "0" otherwise
  290.  
  291. | isop <nickname> <channel>
  292. |   returns: "1" if someone by that nickname is on the channel and has chop;
  293. |     "0" otherwise
  294.  
  295. | isvoice <nickname> <channel>
  296. |   returns: "1" if someone by that nickname is on the channel and has voice
  297. |     (+v); "0" otherwise
  298.  
  299. | onchan <nickname> <channel>
  300. |   returns: "1" if someone by that nickname is on the bot's channel; "0"
  301. |     otherwise
  302.  
  303. | nick2hand <nickname> <channel>
  304. |   returns: handle of the person on the channel with that nickname, if
  305. |     someone by that nickname is on the channel; "" otherwise
  306.  
  307. | handonchan <handle> <channel>
  308. |   returns: "1" if the the user@host for someone on the channel matches
  309. |     for the handle given; "0" otherwise
  310.  
  311. | hand2nick <handle> <channel>
  312. |   returns: nickname of the first person on the channel whose user@host
  313. |     matches that handle, if there is one; "" otherwise
  314.  
  315. | ischanban <ban> <channel>
  316. |   returns: "1" if that is a ban on the bot's channel
  317.  
  318. | chanbans <channel>
  319. |   returns: a list of the current bans on the channel
  320.  
  321. | getchanhost <nickname> <channel>
  322. |   returns: user@host of that person if they are on the channel; {} otherwise
  323.  
  324. | onchansplit <nick> <channel>
  325. |   returns: "1" if that nick is split from the channel; "0" otherwise
  326.  
  327. | chanlist <channel> [flags]
  328. |   returns: list of nicknames currently on the bot's channel that have all
  329. |      of the flags specified; if no flags are given, all of the nicknames
  330. |      are returned
  331.  
  332. | getchanidle <nickname> <channel>
  333. |   returns: number of minutes that person has been idle; "0" if the speci-
  334. |     fied user isn't even on the channel
  335.  
  336. | getchanmode <channel>
  337. |   returns: string of the type "+ntik key" for the channel specified
  338.  
  339.   jump [server [port [password]]]
  340.     jumps to the server specified, or (if none is specified) the next server
  341.       in the list
  342.     returns: nothing
  343.  
  344. | pushmode <channel> <mode> [arg]
  345. |   sends out a channel mode change (ex: pushmode #lame +o goober) through
  346. |     the bot's queueing system; all the mode changes will be sent out at
  347. |     once (combined into one line as much as possible) after the script
  348. |     finishes, or when 'flushmode' is called
  349.  
  350. | flushmode <channel>
  351. |   forces all previously pushed channel mode changes to go out right now,
  352. |     instead of when the script is done (just for the channel specified)
  353.  
  354.  
  355. *** DCC COMMANDS ***
  356.  
  357.   putdcc <idx> <text>
  358.     sends text to the dcc user indicated
  359.     returns: nothing
  360.  
  361.   dccbroadcast <message>
  362.     sends your message to everyone on the party line on the bot net, in the
  363.       form "*** <message>" for local users, and "*** [Bot] <message>" for
  364.       users on other bots
  365.  
  366.   dccputchan <channel> <message>
  367.     sends your message to everyone on a certain channel on the bot net, in
  368.       a form exactly like dccbroadcast does -- valid channels are 0 thru 99999
  369.     returns: nothing
  370.  
  371. | dccsimul <idx> <text...>
  372. |   simulates text typed in by the dcc user specified -- note that in v0.9,
  373. |     this only simulated commands; now a command must be preceded by a '.'
  374. |     to be simulated
  375. |   returns: nothing
  376.  
  377.   hand2idx <handle>
  378.     returns: the idx (a number greater than or equal to zero) for the user
  379.       given, if she is on the party line in chat mode (even if she is currently
  380.       on a channel or in chat off), the file area, or in the control of a
  381.       script; "-1" otherwise -- if the user is on multiple times, the oldest
  382.       idx is returned
  383.     (for backwards compatability, "getidx" is an alias for this)
  384.  
  385.   idx2hand <idx>
  386.     returns: handle of the user with that idx
  387.  
  388.   getchan <idx>
  389.     returns: the current party line channel for a user on the party line --
  390.       "0" indicates he's on the group party line, "-1" means he has chat off,
  391.       and a value from 1 to 99999 is a private channel
  392.  
  393.   setchan <idx> <channel>
  394.     sets a party line user's channel rather suddenly (the party line user
  395.       is not notified that she is now on a new channel); a channel name
  396.       can be used (provided it exists)
  397.     returns: nothing
  398.  
  399. | console <idx> [channel] [console-modes]
  400. |   changes a dcc user's console mode, either to an absolute mode (like "mpj")
  401. |     or just adding/removing flags (like "+pj" or "-moc" or "+mp-c"); the
  402. |     user's console channel view can be changed also (as long as the new
  403. |     channel is defined in the bot)
  404. |   returns: a list containing the user's (new) channel view, and (new)
  405. |     console mode, or nothing if that user isn't currently in dcc chat
  406.  
  407. | echo <idx> [status]
  408. |   turns a user's echo on or off; the status has to be a 1 or 0
  409. |   returns: new value of echo for that user (or the current value, if
  410. |     status was omitted)
  411.  
  412.   putbot <bot-nick> <message>
  413.     sends a message across the bot-net to another bot; if no script intercepts
  414.       the message on the other end, the message just vanishes
  415.     returns: nothing
  416.  
  417.   putallbots <message>
  418.     broadcasts a message across the bot-net to all currently connected bots
  419.     returns: nothing
  420.  
  421.   killdcc <idx>
  422.     kills a party-line or file area connection, rather abruptly
  423.     returns: nothing
  424.  
  425.   bots
  426.     returns: list of the bots currently connected to the botnet
  427.  
  428.   dccused
  429.     returns: number of dcc connections currently in use
  430.  
  431.   dcclist
  432.     returns: list of active dcc connections that are in the chat area, the
  433.       file area, or a script; each item in the list will be a sublist with
  434.       four elements: idx, nickname, hostname, and type; type will be "chat",
  435. |     "files", or "script" (or "socket" for connections that haven't been
  436. |     put under 'control' yet)
  437.  
  438. | whom <chan>
  439. |   returns: list of people on the botnet who are on that channel (0 is
  440. |     the default party line); each item in the list will be a sublist
  441. |     with six elements: nickname, bot, hostname, access flag ('-', '@',
  442. |     '+', or '*'), minutes idle, and away message (blank if the user is
  443. |     not away)
  444.  
  445. | getdccidle <idx>
  446. |   returns: number of seconds the dcc chat/file system/script user has
  447. |     been idle
  448.  
  449. | getdccaway <idx>
  450. |   returns: away message for a dcc chat user (or "" if the user is not
  451. |     set away)
  452.  
  453. | setdccaway <idx> <message>
  454. |   sets a party line user's away message and marks them away; if set to
  455. |     "", the user is marked un-away
  456. |   returns: nothing
  457.  
  458. | assoc <chan> [name]
  459. |   sets the name associated with a botnet channel, if you specify one
  460. |   returns: current name for that channel, if any
  461.  
  462. | killassoc <chan>
  463. |   removes the name associated with a botnet channel, if any exists
  464. |   returns: nothing
  465.  
  466. | connect <host> <port>
  467. |   makes an outgoing connection attempt and creates a dcc entry for it;
  468. |     a 'control' command should be used immediately after a successful
  469. |     'connect' so no input is lost
  470. |   returns: idx of the new connection
  471.  
  472. | dccdumpfile <idx> <filename>
  473. |   dumps out a file from the text directory to a dcc chat user; %( and
  474. |     %[ will work (unlike 'dumpfile')
  475.  
  476.  
  477. *** FILE SYSTEM COMMANDS ***
  478.  
  479. | setpwd <idx> <dir>
  480. |   changes the directory of a file system user, in exactly the same way
  481. |     as a 'cd' command would (ie, the directory can be specified relative
  482. |     or absolute)
  483. |   returns: nothing
  484.  
  485. | getpwd <idx>
  486. |   returns: the current directory of a file system user
  487.  
  488. | getfiles <dir>
  489. |   returns: list of files in the directory given; the directory is relative
  490. |     to dcc-path
  491.  
  492. | getdirs <dir>
  493. |   returns: list of subdirectories in the directory given; the directory
  494. |     is relative to dcc-path
  495.  
  496.   dccsend <filename> <ircnick>
  497.     attempts to start a dcc file transfer to the given nick; the filename must
  498.       be specified either by full pathname or in relation to the bot's startup
  499.       directory
  500.     returns: "0" on success, "1" if the dcc table is full (too many con-
  501.       nections), "2" if it can't open a socket for the transfer, "3" if the
  502.       file doesn't exist, and "4" if the file was queued for later transfer
  503.       (which means that person has too many file transfers going right now)
  504.  
  505. | filesend <idx> <filename> [ircnick]
  506. |   like dccsend, except it operates for a current filesystem user, and
  507. |     the filename is assumed to be a relative path from that user's
  508. |     current directory
  509. |   returns: "0" on failure; "1" on success (either an immediate send
  510. |     or a queued send)
  511.  
  512. | setdesc <dir> <file> <desc>
  513. |   sets the description for a file in a file system directory; the
  514. |     directory is relative to the dcc-path
  515. |   returns: nothing
  516.  
  517. | getdesc <dir> <file>
  518. |   returns: the description for a file in the file system, if one
  519. |     exists
  520.  
  521. | setowner <dir> <file> <handle>
  522. |   changes the owner for a file in the file system; the directory is
  523. |     relative to the dcc-path
  524. |   returns: nothing
  525.  
  526. | getowner <dir> <file>
  527. |   returns: the owner of a file in the file system
  528.  
  529. | setlink <dir> <file> <link>
  530. |   creates or changes a linked file (a file that actually exists on
  531. |     another bot); the directory is relative to dcc-path
  532. |   returns: nothing
  533.  
  534. | getlink <dir> <file>
  535. |   returns: the link for a linked file, if it exists
  536.  
  537.   getfileq <handle>
  538.     returns: list of files queued by someone; each item in the list will be
  539.       a sublist with two elements: nickname the file is being sent to, and
  540.       the filename
  541.  
  542.  
  543. *** MISCELLANEOUS COMMANDS ***
  544.  
  545.   bind <type> <attr(s)> <command-name> <proc-name>
  546.     adds a new keyword command to the bot; valid types are listed below; the
  547.       <attr(s)> are the flags that a user must have to trigger this command;
  548.       the <command-name> for each type is listed below; <proc-name> is the
  549.       name of the Tcl procedure to call for this command (see below for the
  550.       format of the procedure call)
  551.     returns: name of the command that was added
  552.  
  553.   unbind <type> <attr(s)> <command-name> <proc-name>
  554.     removes a previously-made binding
  555.     returns: name of the command that was removed
  556.  
  557. | logfile [<modes> <channel> <filename>]
  558. |   creates a new logfile, which will log the modes given for the channel
  559. |     listed -- or, if no logfile is specified, just returns a list of
  560. |     logfiles; "*" can be used to mean all channels; you can also change
  561. |     the modes and channel of an existing logfile with this command --
  562. |     entering a blank mode and channel makes the bot stop logging there
  563. |   returns: filename of logfile created, or (if no logfile is specified) a
  564. |     list of logfiles like: "{mco * eggdrop.log} {jp #lame lame.log}"
  565.  
  566.   maskhost <nick!user@host>
  567.     returns: hostmask for the string given ("n!u@1.2.3.4" -> "*!u@1.2.3.*",
  568.       "n!u@lame.com" -> "*!u@lame.com", "n!u@a.b.edu" -> "*!u@*.b.edu")
  569.  
  570.   timer <minutes> <tcl-command>
  571.     executes the tcl command after a certain number of minutes have passed
  572.     returns: a timerID
  573.  
  574. | utimer <seconds> <tcl-command>
  575. |   executes the tcl command after a certain number of seconds have passed
  576. |   returns: a timerID
  577.  
  578.   timers
  579.     returns: list of active minutely timers; each entry in the list contains
  580.       the number of minutes left till activation, the command that will be
  581.       executed, and the timerID
  582.  
  583. | utimers
  584. |   returns: list of active secondly timers, identical in format to the
  585. |     output from 'timers'
  586.  
  587.   killtimer <timerID>
  588.     removes a minutely timer from the list
  589.     returns: nothing
  590.  
  591. | killutimer <timerID>
  592. |   removes a secondly timer from the list
  593. |   returns: nothing
  594.  
  595.   unixtime
  596.     returns: a long integer which is the current time according to unix
  597.  
  598.   time
  599.     returns: the current time in 24-hour format (ie "14:15")
  600.  
  601.   date
  602.     returns: the current date in standard format (ie "21 Dec 1994")
  603.  
  604.   ctime <unixtime>
  605.     returns: a string of the date/time represented by the unix time given
  606.       (ie "Fri Aug  3 11:34:55 1973")
  607.  
  608.   myip
  609.     returns: a long number representing the bot's IP address, as it might
  610.       appear in (for example) a DCC request
  611.  
  612.   rand <limit>
  613.     returns: a random integer between 0 and limit-1  
  614.  
  615.   control <idx> <command>
  616.     removes a user from the party line and sends all future input from them
  617.       to the Tcl command given; the command will be called with two parameters:
  618.       the idx of the user, and the input text; the command should return "0"
  619.       to indicate success and "1" to indicate that it relinquishes control of
  620.       the user back to the bot; the idx must be for a user in the party line
  621.       area or the file area; if the input text is blank (""), it indicates
  622.       that the dcc user has dropped connection
  623.     returns: nothing
  624.  
  625.   sendnote <from> <to> <message>
  626.     simulates what happens when one user sends a note to another (this can
  627.       also do cross-bot notes)
  628.     returns: "1" if the note was delivered locally or sent to another bot,
  629. |     "2" if the note was stored locally, "3" if the user's notebox is too
  630. |     full to store a note, "4" if a Tcl binding caught the note, "5" if
  631. |     the note was stored because the user is away, or "0" if the send failed
  632.  
  633.   link [via-bot] <bot>
  634.     attempts to link to another bot directly (or, if you give a via-bot,
  635.       it tells the via-bot to try
  636.     returns: "1" if it looks okay and it will try; "0" if not
  637.  
  638.   unlink <bot>
  639.     attempts to remove a bot from the botnet
  640.     returns: "1" if it will try or has passed the request on; "0" if not
  641.  
  642. | encrypt <key> <string>
  643. |   returns: encrypted string (using blowfish), encoded into ascii using
  644. |     base-64 so it can be sent over the botnet
  645.  
  646. | decrypt <key> <encrypted-base64-string>
  647. |   returns: decrypted string (using blowfish)
  648.  
  649.  
  650. GLOBAL VARIABLES:
  651.   (All config-file variables are global, too.  But these three variables
  652.   are set by the bot.)
  653.  
  654. | channel
  655. |   [no longer used]
  656.  
  657.   botnick
  658.     current nickname the bot is using, ie 'Valis' or 'Valis0', etc
  659.  
  660.   botname
  661.     current nick!user@host that the server sees, ie 'Valis!valis@crappy.com'
  662.  
  663.   server
  664.     current server the bot is using, ie 'irc.math.ufl.edu:6667'
  665.  
  666. | version
  667. |   current bot version (ie: "1.0k 1200"); first item is the text version,
  668. |     second item is a numerical version, and any following items are the
  669. |     names of patches that have been added
  670.  
  671.  
  672. COMMAND EXTENSION:
  673.  
  674. You can use the 'bind' command to attach Tcl procedures to certain events.
  675. For example, you can write a Tcl procedure that gets called every time a
  676. user says "danger" on the channel.  The following is a list of the types of
  677. bindings, and how they work.  Under each binding type is the format of the
  678. bind command, the list of arguments sent to the Tcl proc, and an explanation.
  679.  
  680. Some bindings are marked as "stackable".  That means that you can bind
  681. multiple commands to the same trigger.  Normally, for example, a binding
  682. of "bind msg - stop msg_stop" (which makes a msg-command "stop" call the
  683. Tcl proc "msg_stop") will overwrite any previous binding you had for the
  684. msg-command "stop".  With stackable bindings, like 'msgm' for example,
  685. you can bind to the same command or mask again and again.  When the
  686. binding is triggered, ALL the Tcl procs that are bound to it will be
  687. called, one after another.
  688.  
  689. To remove a binding, use "unbind".  For example, to remove that binding
  690. for the msg-command "stop", use "unbind msg - stop msg_stop". 
  691.  
  692.  
  693.   (1)  MSG
  694.        bind msg <flags> <command> <proc>
  695.        procname <nick> <user@host> <handle> <args>
  696.  
  697.        used for /msg commands; the first word of the user's msg is the
  698.        command, and everything else becomes the argument string
  699.  
  700.   (2)  DCC
  701.        bind dcc <flags> <command> <proc>
  702.        procname <handle> <idx> <args>
  703.  
  704.        used for commands from a dcc chat on the party line; as in MSG, the
  705.        command is the first word and everything else is the argument string;
  706.        the idx is valid until the user disconnects; after that it may be
  707.        reused, to be careful about storing an idx for long periods of time
  708.  
  709.   (3)  FIL
  710.        bind fil <flags> <command> <proc>
  711.        procname <handle> <idx> <args>
  712.  
  713.        the same as DCC, except this is triggered if the user is in the file
  714.        area instead of the party line
  715.  
  716. | (4)  PUB
  717. |      bind pub <flags> <command> <proc>
  718. |      procname <nick> <user@host> <handle> <channel> <args>
  719. |
  720. |      used for commands given on a channel; just like MSG, the first word
  721. |      becomes the command and everything else is the argument string
  722.  
  723.   (5)  MSGM   (stackable)
  724.        bind msgm <flags> <mask> <proc>
  725.        procname <nick> <user@host> <handle> <text>
  726.  
  727.        matches the entire line of text from a /msg with the mask; this is
  728.        more useful for binding Tcl procs to words or phrases spoken anywhere
  729.        within a line of text
  730.  
  731. | (6)  PUBM   (stackable)
  732. |      bind pubm <flags> <mask> <proc>
  733. |      procname <nick> <user@host> <handle> <channel> <text>
  734. | 
  735. |      just like MSGM, except it's triggered by things said on a channel
  736. |      instead of things /msg'd to the bot; the mask is matched against
  737. |      the channel name followed by the text, ie, "#nowhere hello there!",
  738. |      and can contain wildcards
  739.  
  740. | (7)  JOIN   (stackable)
  741. |      bind join <flags> <mask> <proc>
  742. |      procname <nick> <user@host> <handle> <channel>
  743. | 
  744. |      triggered by someone joining the channel; the <mask> in the bind
  745. |      is matched against "#channel nick!user@host" and can contain
  746. |      wildcards
  747.  
  748. | (8)  PART   (stackable)
  749. |      bind part <flags> <mask> <proc>
  750. |      procname <nick> <user@host> <handle> <channel>
  751. |
  752. |      triggered by someone leaving the channel; as in JOIN, the <mask>
  753. |      is matched against "#channel nick!user@host" and can contain
  754. |      wildcards
  755.  
  756. | (9)  SIGN   (stackable)
  757. |      bind sign <flags> <mask> <proc>
  758. |      procname <nick> <user@host> <handle> <channel> <reason>
  759. | 
  760. |      triggered by a signoff, or possibly by someone who got netsplit and
  761. |      never returned; the signoff message is the last argument to the proc;
  762. |      wildcards can be used in <mask>, which contains the channel name
  763.  
  764. | (10) TOPC   (stackable)
  765. |      bind topc <flags> <mask> <proc>
  766. |      procname <nick> <user@host> <handle> <channel> <topic>
  767. |
  768. |      triggered by a topic change; can use wildcards in <mask>, which is
  769. |      matched against the channel name and new topic
  770.  
  771. | (11) KICK   (stackable)
  772. |      bind kick <flags> <mask> <proc>
  773. |      procname <nick> <user@host> <handle> <channel> <kicked-nick> <reason>
  774. | 
  775. |      triggered when someone is kicked off the channel; the <mask> is
  776. |      matched against "#channel nick" where the nickname is of the person
  777. |      who got kicked off (can use wildcards); the proc is called with
  778. |      the nick, user@host, and handle of the kicker, plus the channel,
  779. |      the nickname of the person who was kicked, and the reason; <flags>
  780. |      is unused here
  781.  
  782. | (12) NICK   (stackable)
  783. |      bind nick <flags> <mask> <proc>
  784. |      procname <nick> <user@host> <handle> <channel> <newnick>
  785. | 
  786. |      triggered when someone changes nicknames; wildcards are allowed;
  787. |      the mask is matched against "#channel newnick"
  788.  
  789. | (13) MODE   (stackable)
  790. |      bind mode <flags> <mask> <proc>
  791. |      proc-name <nick> <user@host> <handle> <channel> <mode-change>
  792. | 
  793. |      mode changes are broken down into their component parts before being
  794. |      sent here, so the <mode-change> will always be a single mode, like
  795. |      "+m" or "-o snowbot"; flags are ignored; the bot's automatic response
  796. |      to a mode change will happen AFTER all matching Tcl procs are called;
  797. |      the <mask> will have the channel prefixed (ie, "#turtle +m")
  798.  
  799.   (14) CTCP
  800.        bind ctcp <flags> <keyword-mask> <proc>
  801.        proc-name <nick> <user@host> <handle> <dest> <keyword> <args...>
  802.     
  803.        destination will be a nickname (the bot's nickname, obviously) or
  804.        a channel name; keyword is the ctcp command and args may be empty;
  805. |      if the proc returns 0, the bot will attempt its own processing of
  806. |      the ctcp command
  807.  
  808.   (15) CTCR
  809.        bind ctcr <flags> <keyword-mask> <proc>
  810.        proc-name <nick> <user@host> <handle> <dest> <keyword> <args...>
  811.  
  812.        just like ctcp, but this is triggered for a ctcp-reply (ie, ctcp
  813.        embedded in a notice instead of a privmsg)
  814.  
  815.   (16) RAW   (stackable)
  816.        bind raw <flags> <mask> <proc>
  817.        procname <raw-string>
  818.  
  819.        THIS ONLY WORKS IF YOU COMPILED WITH RAW ENABLED
  820.        the mask is checked against every incoming string from the server; the
  821.        proc is given the entire string, just as it came from the server; flags
  822.        are ignored
  823.  
  824.   (17) BOT
  825.        bind bot <flags> <command> <proc>
  826.        proc-name <from-bot> <command> <args>
  827.  
  828.        triggered by a message coming from another bot in the botnet; works
  829.        similar to a DCC binding; the first word is the command and the rest
  830.        becomes the argument string; flags are ignored
  831.  
  832.   (18) CHON   (stackable)
  833.        bind chon <flags> <mask> <proc>
  834.        proc-name <handle> <idx>
  835.  
  836.        when someone first enters the "party-line" area of the bot via dcc
  837.        chat or telnet, this is triggered before they are connected to a
  838.        chat channel (so yes, you can change the channel in a 'chon' proc);
  839.        mask matches against handle; this is NOT triggered when someone
  840.        returns from the file area, etc
  841.  
  842.   (19) CHOF   (stackable)
  843.        bind chof <flags> <mask> <proc>
  844.        proc-name <handle> <idx>
  845.  
  846.        triggered when someone leaves the party line to disconnect from the
  847.        bot; mask matches against the handle; note that the connection may
  848.        have already been dropped by the user, so don't send output to that
  849.        idx
  850.  
  851.   (20) SENT   (stackable)
  852.        bind sent <flags> <mask> <proc>
  853.        proc-name <handle> <nick> <path/to/file>
  854.  
  855.        after a user has successfully downloaded a file from the bot, this
  856.        binding is triggered; mask is matched against the handle of the user
  857.        that initiated the transfer; nick is the actual recipient (on IRC) of
  858.        the file; the path is relative to the dcc directory (unless the file
  859.        transfer was started by a script call to 'dccsend', in which case the
  860.        path is the exact path given in the call to 'dccsend')
  861.  
  862.   (21) RCVD   (stackable)
  863.        bind rcvd <flags> <mask> <proc>
  864.        proc-name <handle> <nick> <path/to/file>
  865.  
  866.        triggered after a user uploads a file successfully; mask is matched
  867.        against the user's handle; nick is the nickname on IRC that the file
  868.        transfer originated from; the path is where the file ended up,
  869.        relative to the dcc directory (usually this is your incoming dir)
  870.  
  871.   (22) CHAT   (stackable)
  872.        bind chat <flags> <mask> <proc>
  873.        proc-name <nick> <channel#> <text>
  874.  
  875.        when someone says something on the botnet, it invokes this binding;
  876.        flags is ignored; nick could be a user on this bot (ie "DronePup")
  877.        or on another bot (ie "Eden@Wilde"); the mask is checked against the
  878.        text
  879.  
  880.   (23) LINK   (stackable)
  881.        bind link <flags> <mask> <proc>
  882.        proc-name <botname> <via>
  883.  
  884.        triggered when a bot links into the botnet; botname is the name of
  885.        the bot that just linked in; via is the bot it linked through; the
  886.        mask is checked against the bot that linked; flags is ignored
  887.  
  888.   (24) DISC   (stackable)
  889.        bind disc <flags> <mask> <proc>
  890.        proc-name <botname>
  891.  
  892.        triggered when a bot disconnects from the botnet for whatever reason;
  893.        just like the link bind, flags are ignored; mask is checked against the
  894.        nickname of the bot that left
  895.  
  896. | (25) SPLT   (stackable)
  897. |      bind splt <flags> <mask> <proc>
  898. |      procname <nick> <user@host> <handle> <channel>
  899. | 
  900. |      triggered when someone gets netsplit on the channel; be aware that
  901. |      this may be a false alarm (it's easy to fake a netsplit signoff
  902. |      message); <mask> may contain wildcards, and is matched against the
  903. |      channel and nick!user@host just like join; anyone who is SPLT will
  904. |      trigger a REJN or SIGN within the next 15 minutes
  905.  
  906. | (26) REJN   (stackable)
  907. |      bind rejn <flags> <nick!user@host> <proc>
  908. |      procname <nick> <user@host> <handle> <channel>
  909. |
  910. |      someone who was split has rejoined; <mask> can contain wildcards,
  911. |      and contains channel and nick!user@host just like join
  912.  
  913. | (27) FILT   (stackable)
  914. |      bind filt <flags> <mask> <proc>
  915. |      procname <idx> <text>
  916. |
  917. |      DCC party line and file system users have their text sent through
  918. |      filt before being processed; if the proc returns a 1, the text is
  919. |      considered parsed, otherwise the bot will continue to process the
  920. |      text as a command, etc
  921.  
  922. | (28) FLUD   (stackable)
  923. |      bind flud <flags> <type> <proc>
  924. |      procname <nick> <user@host> <handle> <type> <channel>
  925. |
  926. |      any floods detected through the flood control settings (like
  927. |      'flood-ctcp') are sent here before processing; if the proc
  928. |      returns 1, no further action is taken on the flood; if the proc
  929. |      returns 0, the bot will do its normal "punishment" for the flood;
  930. |      the flood type is "pub", "msg", "join", or "ctcp" (and can be
  931. |      masked to "*" for the bind); flags is ignored
  932.  
  933. | (29) NOTE
  934. |      bind note <flags> <nickname> <proc>
  935. |      procname <from> <to> <text>
  936. |
  937. |      incoming notes (either from the party line, someone on IRC, or
  938. |      someone on another bot on the botnet) are checked against these
  939. |      binds before being process; if a bind exists, the bot will not
  940. |      deliver the note; the nickname must be an exact match (no wild-
  941. |      cards), but it is not case sensitive; flags is ignored
  942.  
  943. | (30) ACT   (stackable)
  944. |      bind act <flags> <mask> <proc>
  945. |      proc-name <nick> <channel#> <action>
  946. |
  947. |      when someone does an action on the botnet, it invokes this binding;
  948. |      flags is ignored; the mask is checked against the text of the
  949. |      action (this is very similar to the CHAT binding)
  950.  
  951.  
  952.  
  953. (A) RETURN VALUES
  954.  
  955.     Several bindings pay attention to the value you return from the proc
  956.     (using "return $value").  Usually they expect a 0 or 1, and failing
  957.     to return any value is interpreted as a 0.
  958.  
  959.     Here's a list of the bindings that use the return value from procs
  960.     they trigger:
  961.  
  962.     MSG   Return 1 to make the command get logged like so:
  963.           (nick!user@host) !handle! command
  964.  
  965.     DCC   Return 1 to make the command get logged like so:
  966.           #handle# command
  967.  
  968.     FIL   Return 1 to make the command get logged like so:
  969.           #handle# files: command
  970.  
  971.     PUB   Return 1 to make the command get logged like so:
  972.           <<nick>> !handle! command
  973.  
  974.     CTCP  Return 1 to ask the bot not to process the CTCP command on its
  975.           own.  Otherwise it would send its own response to the CTCP
  976.           (possibly an error message if it doesn't know how to deal with
  977.           it).
  978.  
  979.     FILT  Return 1 to indicate the text has been processed, and the bot
  980.           should just ignore it.  Otherwise it will treat the text like
  981.           any other.
  982.  
  983.     FLUD  Return 1 to ask the bot not to take action on the flood.
  984.           Otherwise it will do its normal punishment.
  985.  
  986.  
  987. (B) CONTROL PROCEDURES
  988.  
  989.     Using the 'control' command you can put a DCC connection (or outgoing
  990.     TCP connection) in control of a script.  All text that comes in on
  991.     the connection is sent to the proc you specify.  All outgoing text
  992.     should be sent with 'putdcc'.
  993.  
  994.     The control procedure is called with these parameters:
  995.        procname <idx> <input-text>
  996.     This allows you to use the same proc for several connections.  The
  997.     idx will stay the same until the connection is dropped -- after that,
  998.     it will probably get reused for a later connection.
  999.  
  1000.     To indicate that the connection has closed, your control procedure
  1001.     will be called with blank text (the input-text will be "").  This
  1002.     is the only time it will ever be called with "" as the text, and it
  1003.     is the last time your proc will be called for that connection.
  1004.  
  1005.     If you want to hand control of your connection back to eggdrop, your
  1006.     proc should return 1.  Otherwise, return 0 to retain control.
  1007.  
  1008.  
  1009. (C) MATCH CHARACTERS
  1010.  
  1011.     Many of the bindings allow match characters in the arguments.  Here
  1012.     are the four special characters:
  1013.  
  1014.     ?  matches any single character
  1015.     *  matches 0 or more characters of any type
  1016.     %  matches 0 or more non-space characters (can be used to match a
  1017.           single word)
  1018.     ~  matches 1 or more space characters (can be used for whitespace
  1019.           between words)
  1020.  
  1021.