TCL-COMMANDS.DOC
This is an exhaustive list of all the Tcl commands added to eggdrop. All of the normal Tcl built-in commands are still there, of course. But you can also use these to manipulate features of the bot. They are listed according to category.

NOTICE: This list is accurate for the v2.0 series of eggdrop!

SCRIPTS WHICH WERE WRITTEN FOR EARLIER VERSIONS WILL PROBABLY NOT WORK WITHOUT MODIFICATION. ALTHOUGH SOME CAN BE MADE TO WORK USING THE COMPAT.TCL DISTRIBUTED WITH EGGDROP.


Sections:
Core Eggdrop Commands
  • Output Commands
  • User Record Manipulation Commands
  • Channel Commands
  • DCC Commands
  • Miscellaneous Commands
  • Global Variables
  • Command Extension
  • Return Values
  • Match Characters
  • Eggdrop Module Information (TCL commands, general info., etc..)
  • Assoc Module
  • Blowfish Module
  • Botnet Module
  • Botservice Module
  • Channels Module
  • File System Module
  • IRC Module
  • Notes Module
  • Scriptsock Module
  • Server Module
  • Timers Module

  • CORE EGGDROP COMMANDS

    These are commands provided in the core part of eggdrop, for module specific commands, select the appropriate link above for the module you want information on.


    OUTPUT COMMANDS

    putcmdlog <text>
    sends text to the log for any channel, marked as 'command' (c)
    returns: nothing

    putxferlog <text>
    sends text to the log for any channel, marked as 'file-area' (x)
    returns: nothing

    putloglev <level(s)> <channel> <text>
    sends text to the log, tagged with all of the valid levels given (use "*" to indicate all log levels)
    returns: nothing

    dumpfile <nick> <filename>
    dumps out a file from the help/text directory to a user on IRC via msg (one line per msg); the user has no flags, so the flag bindings won't work within the file.


    USER RECORD MANIPULATION COMMANDS

    countusers
    returns: number of users in the bot's database

    validuser <handle>
    returns: "1" if a user by that name exists; '0' otherwise

    finduser <nick!user@host>
    finds the user record which most closely matches the given user@host
    returns: the handle found, or "*" if none

    userlist [flags]
    returns: a list of the handles of users on the bot you can use the new flag matching system here,
    usage: [global]{&/|}[chan]{&/|}[bot]
    matches the flags relevantly, (chan matches vs anywhere), & specifies an and match, | specifies or, only the first of these is relevant, the default is or.

    passwdok <handle> <pass>
    checks the password given against the user's password -- if the user has not set a password, will always return "1"; check against the password "" (a blank string) to find out if a user has no password set
    returns: "1" if password matches for that user; "0" if not

    getuser <handle> <entry-type> [extra info]
    this is a generic interface to the new generic userfile support, it return info specific to each entry-type, valid entry types are:

    BOTFL - returns the current bot-specific flags for the user (if it's a bot :)
    BOTADDR - (another bot-only thing :) returns a list containing the bots address, the bots telnet port, and it's relay port.
    HOSTS - returns a list of the host for the user
    LASTON - returns a list containing the unixtime last seen, and the last seen place.
    OR
    LASTON #channel returns the time last seen on the channel or 0 if no info
    INFO - returns the user's global info line
    COMMENT - returns the master-visible only comment for the user
    EMAIL - returns the users email address
    URL - returns the users url address
    XTRA - returns xtra info, use the form:
    getuser <handle> XTRA <key>
    to receive data set for a certain key

    setuser <handle> <entry-type> [extra info]
    this is the counterpart of getuser, it lets you set the various values extra ones not supported about:

    PASS - use this to set a users password (no 3rd arg will clear it)
    HOSTS - for setting hosts, no extra info = clear, otherwise *1* hostmask is added
    LASTON - sets global laston time, will also set laston time for any channel the user has a chanrec for (if it matches) to prevent setting a channel time from ALSO setting the global time use LASTON time #channel *
    XTRA - in the form:
    setuser <handle> XTRA <key> <data>
    sets upto 500 bytes of data per key (use no data to clear)
    chnick <old-handle> <new-handle>
    changes a user's handle
    returns: "1" on success; "0" if the handle is already used, the handle is invalid, or the user can't be found

    chattr <handle> [changes [channel]]
    changes the attributes for a user record, if you include any -- changes are of the form "+f", "-o", "+dk", "-o+d", etc; if a channel is specified, the channel-specific flags for that channel are altered you can now use the +o|-o #channel format here too.
    returns: new flags for the user (if you made no changes, returns current flags); if a channel was specified, the channel-specific flags for that channel are returned -- returns "*" if that user does not exist

    matchattr <handle> <flags> [channel]
    returns: "1" if the specified user has the matching flags. (using the new matching system)

    adduser <handle> <hostmask>
    creates a new user entry with the handle and hostmask given (with no pass- word, and the default flags)
    returns: "1" if successful, "0" if it already existed

    deluser <handle>
    attempts to erase a user record with that handle
    returns: "1" if successful, "0" if no such user exists

    delhost <handle> <hostmask>
    deletes a hostmask from a user's hostmask list
    returns: "1" on success, "0" if that hostmask wasn't in the list or the user does not exist

    newignore <hostmask> <creator> <comment> [lifetime]
    adds an entry to the ignore list; creator is given credit for the ignore; lifetime is how many minutes until the ignore expires and is removed; if lifetime is not specified, ignore-time (usually 60) is used; setting the lifetime to 0 makes it a permanent ignore
    returns: nothing

    killignore <hostmask>
    removes an entry from the ignore list
    returns: "1" if successful, "0" otherwise

    ignorelist
    returns: list of ignores; each entry is itself a list, containing: hostmask, comment, expiration timestamp, time added, and creator (the three timestamps are in unixtime format)

    isignore <hostmask>
    returns: "1" if the ignore is in the list, "0" otherwise

    save
    writes the userfile to disk
    returns: nothing

    reload
    loads the userfile from disk (replacing whatever's in memory)
    returns: nothing

    backup
    makes a simple backup of the userfile that's on disk
    returns: nothing

    getting-users
    returns: "1" if the bot is currently downloading a userfile from a sharebot (and hence, user records are about to drastically change), "0" if not


    CHANNEL COMMANDS

    channel add <name> <option-list>
    adds a channel record for the bot to monitor; the full list of possible options is given in the "eggdrop.conf.dist" sample config file; note that the channel options must be in a list (enclosed in {})
    returns: nothing

    channel set <name> <options...>
    sets options for the channel specified; the full list of possible options is given in the "eggdrop.conf.dist" sample config file
    returns: nothing

    channel info <name>
    returns: list of info about that channel record: enforced mode, idle kick limit, need-op script, need-invite script, and then various +/- options as seen in the config file

    channel remove <name>
    destroys a channel record for the bot and makes the bot no longer monitor that channel
    returns: nothing

    savechannels
    saves the channel settings to the channel-file if one is defined.
    returns: nothing

    loadchannels
    reloads the channel settings from the channel-file if one is defined.
    returns: nothing

    channels
    returns: list of the channels the bot is monitoring (or trying to)

    validchan <channel>
    checks if the bot is monitoring that channel
    returns: 1 if the channel exists, 0 if not

    isdynamic <channel>
    returns: 1 if the channel is an existing dynamic channel, 0 if not


    DCC COMMANDS

    putdcc <idx> <text>
    sends text to the dcc user indicated
    returns: nothing

    dccbroadcast <message>
    sends your message to everyone on the party line on the bot net, in the form "*** <message>" for local users, and "*** [Bot] <message>" for users on other bots

    dccputchan <channel> <message>
    sends your message to everyone on a certain channel on the bot net, in a form exactly like dccbroadcast does -- valid channels are 0 thru 99999
    returns: nothing

    restart
    restarts the bot
    returns: nothing

    rehash
    rehashes the bot
    returns: nothing

    dccsimul <idx> <text...>
    simulates text typed in by the dcc user specified -- note that in v0.9, this only simulated commands; now a command must be preceded by a '.' to be simulated
    returns: nothing

    hand2idx <handle>
    returns: the idx (a number greater than or equal to zero) for the user given, if she is on the party line in chat mode (even if she is currently on a channel or in chat off), the file area, or in the control of a script; "-1" otherwise -- if the user is on multiple times, the oldest idx is returned

    idx2hand <idx>
    returns: handle of the user with that idx

    valididx <idx>
    returns: "1" if the idx currently exists; "0" if not

    getchan <idx>
    returns: the current party line channel for a user on the party line -- "0" indicates he's on the group party line, "-1" means he has chat off, and a value from 1 to 99999 is a private channel

    setchan <idx> <channel>
    sets a party line user's channel rather suddenly (the party line user is not notified that she is now on a new channel); a channel name can be used (provided it exists)
    returns: nothing

    console <idx> [channel] [console-modes]
    changes a dcc user's console mode, either to an absolute mode (like "mpj") or just adding/removing flags (like "+pj" or "-moc" or "+mp-c"); the user's console channel view can be changed also (as long as the new channel is defined in the bot)
    returns: a list containing the user's (new) channel view, and (new) console mode, or nothing if that user isn't currently in dcc chat

    echo <idx> [status]
    turns a user's echo on or off; the status has to be a 1 or 0
    returns: new value of echo for that user (or the current value, if status was omitted)

    killdcc <idx>
    kills a party-line or file area connection, rather abruptly
    returns: nothing

    dccused
    returns: number of dcc connections currently in use

    dcclist
    returns: list of active dcc connections that are in the chat area, the file area, or a script; each item in the list will be a sublist with four elements: idx, nickname, hostname, and type; type will be "chat", "files", "bot", "file_receiving", "file_sending", "file_send_pending", or "script" (or "socket" for connections that haven't been put under 'control' yet) or any new dcc type that gets added.

    getdccidle <idx>
    returns: number of seconds the dcc chat/file system/script user has been idle

    getdccaway <idx>
    returns: away message for a dcc chat user (or "" if the user is not set away)

    setdccaway <idx> <message>
    sets a party line user's away message and marks them away; if set to "", the user is marked un-away
    returns: nothing

    listen <port> [mask]
    accepts connections from users only (no bots); the optional mask is used to identify permitted nicknames; if the mask begins with '@' it is interpreted to be a mask of permitted hosts to accept connections from
    returns: port #
    listen <port> off
    stop listening at a port
    returns: nothing

    dccdumpfile <idx> <filename>
    dumps out a file from the text directory to a dcc chat user; the flag matching that's used everywhere else works here too


    MISCELLANEOUS COMMANDS

    bind <type> <attr(s)> <command-name> [proc-name]
    adds a new keyword command to the bot; valid types are listed below; the <attr(s)> are the flags that a user must have to trigger this command; the <command-name> for each type is listed below; <proc-name> is the name of the Tcl procedure to call for this command (see below for the format of the procedure call); if the proc-name is omitted, no binding is added -- instead, the current binding is returned (if it's stackable, a list of the current bindings is returned) yes, you can use the new flag binding method here too, and this is where it becomes truely phearful since you may never need to check attr's inside functions again...imagine:

    bind pub -o&+o command command_proc
    returns: name of the command that was added, or (if proc-name was omitted), a list of the current bindings for this command

    unbind <type> <attr(s)> <command-name> <proc-name>
    removes a previously-made binding
    returns: name of the command that was removed

    logfile [<modes> <channel> <filename>]
    creates a new logfile, which will log the modes given for the channel listed -- or, if no logfile is specified, just returns a list of logfiles; "*" can be used to mean all channels; you can also change the modes and channel of an existing logfile with this command -- entering a blank mode and channel makes the bot stop logging there
    returns: filename of logfile created, or (if no logfile is specified) a list of logfiles like: "{mco * eggdrop.log} {jp #lame lame.log}"

    maskhost <nick!user@host>
    returns: hostmask for the string given ("n!u@1.2.3.4" -> "*!u@1.2.3.*", "n!u@lame.com" -> "*!u@lame.com", "n!u@a.b.edu" -> "*!u@*.b.edu")

    unixtime
    returns: a long integer which is the current time according to unix

    time
    returns: the current time in 24-hour format (ie "14:15")

    strftime <formatstring> [time]
    returns: a formatted string of time using standard strftime format, uses the value of time, or now if no time specified

    date
    returns: the current date in standard format (ie "21 Dec 1994")

    ctime <unixtime>
    returns: a string of the date/time represented by the unix time given (i.e. "Fri Aug 3 11:34:55 1973")

    myip
    returns: a long number representing the bot's IP address, as it might appear in (for example) a DCC request

    rand <limit>
    returns: a random integer between 0 and limit-1

    die [reason]
    causes the bot to log a fatal error and exit completely; if no reason is given, "EXIT" is used

    unames
    returns: the current operating system the bot is using.


    GLOBAL VARIABLES:
    (All config-file variables are global too, but these variables are set by the bot.)

    version
    current bot version (ie: "1.1.2+pl1 1010201 pl1"); first item is the text version, second item is a numerical version, and any following items are the names of patches that have been added

    numversion
    current numeric bot version (ie: "1010201");

    Numerical version is "MMNNRRPP" where:
    MM is the major release number
    NN is the minor release number
    RR is the sub-release number
    PP is the patch level for that sub-release

    uptime
    unixtime value for when the bot was started

    lastbind
    The last command binding which triggered. This allows you to identify which command triggered a tcl routine.


    COMMAND EXTENSION

    You can use the 'bind' command to attach Tcl procedures to certain events. For example, you can write a Tcl procedure that gets called every time a user says "danger" on the channel. The following is a list of the types of bindings, and how they work. Under each binding type is the format of the bind command, the list of arguments sent to the Tcl proc, and an explanation.

    Some bindings are marked as "stackable". That means that you can bind multiple commands to the same trigger. Normally, for example, a binding of "bind msg - stop msg_stop" (which makes a msg-command "stop" call the Tcl proc "msg_stop") will overwrite any previous binding you had for the msg-command "stop". With stackable bindings, like 'msgm' for example, you can bind to the same command or mask again and again. When the binding is triggered, ALL the Tcl procs that are bound to it will be called, one after another.

    To remove a binding, use "unbind". For example, to remove that binding for the msg-command "stop", use "unbind msg - stop msg_stop".

    There are more bindings which are enabled from the loading of specific modules, see the specific module information pages to see which module provides which bindings.

    DCC

    bind dcc <flags> <command> <proc>
    proc-name <handle> <idx> <args>
    used for commands from a dcc chat on the party line; as in MSG, the command is the first word and everything else is the argument string; the idx is valid until the user disconnects; after that it may be reused, so be careful about storing an idx for long periods of time

    BOT

    bind bot <flags> <command> <proc>
    proc-name <from-bot> <command> <args>
    triggered by a message coming from another bot in the botnet; works similar to a DCC binding; the first word is the command and the rest becomes the argument string; flags are ignored

    CHON (stackable)

    bind chon <flags> <mask> <proc>
    proc-name <handle> <idx>
    when someone first enters the "party-line" area of the bot via dcc chat or telnet, this is triggered before they are connected to a chat channel (so yes, you can change the channel in a 'chon' proc); mask matches against handle; this is NOT triggered when someone returns from the file area, etc

    CHOF (stackable)

    bind chof <flags> <mask> <proc>
    proc-name <handle> <idx>
    triggered when someone leaves the party line to disconnect from the bot; mask matches against the handle; note that the connection may have already been dropped by the user, so don't send output to that idx

    CHAT (stackable)

    bind chat <flags> <mask> <proc>
    proc-name <nick> <channel#> <text>
    when someone says something on the botnet, it invokes this binding; flags is ignored; nick could be a user on this bot (i.e. "DronePup") or on another bot (i.e. "Eden@Wilde"); the mask is checked against the text

    LINK (stackable)

    bind link <flags> <mask> <proc>
    proc-name <botname> <via>
    triggered when a bot links into the botnet; botname is the name of the bot that just linked in; via is the bot it linked through; the mask is checked against the bot that linked; flags is ignored

    DISC (stackable)

    bind disc <flags> <mask> <proc>
    proc-name <botname>
    triggered when a bot disconnects from the botnet for whatever reason; just like the link bind, flags are ignored; mask is checked against the nickname of the bot that left

    FILT (stackable)

    bind filt <flags> <mask> <proc>
    proc-name <idx> <text>
    DCC party line and file system users have their text sent through filt before being processed; if the proc a blank string, the text is considered parsed; otherwise the bot will use the text returned from the proc and continue parsing that

    ACT (stackable)

    bind act <flags> <mask> <proc>
    proc-name <nick> <channel#> <action>
    when someone does an action on the botnet, it invokes this binding; flags is ignored; the mask is checked against the text of the action (this is very similar to the CHAT binding)

    BCST (stackable)

    bind chat <flags> <mask> <proc>
    proc-name <bot> <channel#> <text>
    when a bot says something on the botnet, it invokes this binding; flags is ignored; the mask is checked against the text

    CHJN (stackable)

    bind chat <flags> <mask> <proc>
    proc-name <bot> <nick> <channel#> <flag><sock> <from>
    when someone joins a botnet channel, it invokes this binding; flags is ignored; the mask is checked against the text

    CHPT (stackable)

    bind chat <flags> <mask> <proc>
    proc-name <bot> <nick> <sock> <chan>
    when someone parts a botnet channel, it invokes this binding; flags is ignored; the mask is checked against the channel

    TIME (stackable)

    bind time - <mask> <proc>
    proc-name <min> <hour> <day> <month> <year>
    allows you to schedule procedure calls at certain times, mask matches 5 space seperated integers of the form: "min hour day month year"

    AWAY (stackable)

    bind away - <mask> <proc>
    proc-name <bot> <idx> <msg>
    triggers when a user goes away or comes back on the botnet (msg == "" when returning)

    LOAD (stackable)

    bind load - <mask> <proc>
    proc-name <module>
    triggers when a module is loaded.

    UNLD (stackable)

    bind unld - <mask> <proc>
    proc-name <module>
    triggers when a module is unloaded.

    NKCH (stackable)

    bind nkch - <mask> <proc>
    proc-name <oldnick> <newnick>
    triggered whenever a local users nick is changed (in the userfile)


    RETURN VALUES

    Several bindings pay attention to the value you return from the proc (using "return $value"). Usually they expect a 0 or 1, and failing to return any value is interpreted as a 0.

    Here's a list of the bindings that use the return value from procs they trigger, these bindings are mostly enabled from the loading of specific modules, see the specific module information pages to see which module provides which bindings.

    MSG
    Return 1 to make the command get logged like so:
    (nick!user@host) !handle! command

    DCC
    Return 1 to make the command get logged like so:
    #handle# command

    FIL
    Return 1 to make the command get logged like so:
    #handle# files: command

    PUB
    Return 1 to make the command get logged like so:
    <<nick>> !handle! command

    CTCP
    Return 1 to ask the bot not to process the CTCP command on its own. Otherwise it would send its own response to the CTCP (possibly an error message if it doesn't know how to deal with it).

    FILT
    Return 1 to indicate the text has been processed, and the bot should just ignore it. Otherwise it will treat the text like any other.

    FLUD
    Return 1 to ask the bot not to take action on the flood. Otherwise it will do its normal punishment.

    RAW
    Return 1 to ask the bot not to process the server text. This can affect the bot's performance (by causing it to miss things that it would normally act on) -- you have been warned.

    WALL
    Return 1 to make the command get logged liked so:
    !nick! msg


    MATCH CHARACTERS

    Many of the bindings allow match characters in the arguments. Here are the four special characters:

    ? matches any single character
    * matches 0 or more characters of any type
    % matches 0 or more non-space characters (can be used to match a single word)
    ~ matches 1 or more space characters (can be used for whitespace between words)

    (c) 1997 Robey Pointer
    (c) 1998 Eggdrop Development Team