mirror of
https://github.com/moparisthebest/hexchat
synced 2024-12-24 16:48:52 -05:00
68 KiB
68 KiB
HexChat Tcl Interface
(This file is currently not converted properly to Markdown format.)
Note to Eggdrop Scripters: The Tcl Plugin for XChat will not run eggdrop scripts. Contrary to popular belief, Tcl was not invented by or for eggdrop. Eggdrop, like many other successful projects is just another happy user of Tcl. Tcl was around long before Eggdrop and is broadly considered the industry standard language for automation.
| Name: | /reload - Clear and reload all tcl scripts. |
| Synopsis: | /reload |
| Description: | Clears out and reloads all tcl scripts. Any variables defined and any open files are lost. |
| See Also: | /source |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | /source - Load a specific tcl script file. |
| Synopsis: | /source filename |
| Description: | Loads a tcl script into XChat. |
| See Also: | /reload |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | /tcl - Execute any tcl command |
| Synopsis: | /tcl command ?args? |
| Description: | Allows for the immediate execution of any tcl command. |
| Example: | /tcl puts "Hello, XChat World!" /tcl configdir |
| Downloads: | Download recommended Tcl plugin support scripts. |
Tcl Plugin TCL Commands
| Name: | alias - Creates a new xchat command. | ||||
| Synopsis: | alias name { script } |
||||
| Description: | Creates a new xchat command and executes script when that command is entered.
Upon executing the alias, the following variables will be set:
You can also hook all text (non-commands) sent to any given tab/window by pre-pending the name of any tab with an '@'. |
||||
| Example: | # do 'ls -al' command on any directory
alias ls {
print "[eval "exec ls -al $_rest"]"
complete
}
|
||||
| See Also: | complete, on | ||||
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | away - Returns your /away message. |
| Synopsis: | away ?server|context? |
| Description: | Returns your /away message. If no server or context is omitted, the current server is assumed. |
| Example: | set awaymsg [away] |
| See Also: | findcontext, getcontext |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | channel - Return the current query/channel name. |
| Synopsis: | channel ?context? |
| Description: | Returns the name of the current channel or query. You may also specify a specific context to get the name of. |
| Example: | set thischannel [channel] |
| See Also: | channels, findcontext, getcontext, server, servers |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | channels - Returns of list of all channels you are in. |
| Synopsis: | channels ?server|context? |
| Description: | Returns a list of all channels you are in. If server or context is omitted, the current server is assumed. |
| Example: | alias mychannels {
foreach s [servers] {
print "Server: $s"
foreach c [channels $s] {
print " - Channel: $c - [topic $s $c]"
}
}
complete
} |
| See Also: | channel, findcontext, getcontext, server, servers |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | chats - Returns a list of opened dcc chats. |
| Synopsis: | chats |
| Description: | Returns the name of the current active dcc chats. |
| Example: | set mychats [chats] print "I am directly connected to [join $mychats ", "]" |
| See Also: | channels, dcclist, queries |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | command - Simulate a command entered into xchat. |
| Synopsis: | command ?server|context? ?channel|nick? text |
| Description: | Executes any internal or external chat command as if it had been typed into xchat directly. If server or channel|nick are omitted, the current ones are assumed. |
| Example: | command "whois [me]" command #mychannel "me wonders what this does." command irc.myserver.com #thatchannel "say Hello, World!" command irc.nyserver.com "away I'm gone" |
| See Also: | findcontext, getcontext, raw |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | complete - Set return mode of an 'on' or 'alias' script | ||||||||
| Synopsis: | complete ?retcode? |
||||||||
| Description: | Similar to TCL's return command, complete halts further processing of an on or alias script and sets a return value.
|
||||||||
| Example: | on XC_TABOPEN whatever {
print "Hello from [channel]"
complete
}
|
||||||||
| See Also: | alias, on | ||||||||
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | dcclist - Returns detailed information about all dcc chats and files transfers. | ||||||||||||||||||||
| Synopsis: | dcclist |
||||||||||||||||||||
| Description: | Returns a list of all dcc chats and transfers.
Each list entry is made up of the following elements:
|
||||||||||||||||||||
| Example: | foreach entry [dcclist] {
print "$entry"
} |
||||||||||||||||||||
| See Also: | chats | ||||||||||||||||||||
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | findcontext - Finds a context based on a channel and/or server name. |
| Synopsis: | findcontext ?server? ?channel|nick? |
| Description: | Finds a context based on a channel and/or server name. If the server is omitted, it finds any channel (or query) by the given name on the current server. If channel|nick is omitted, it finds the default server tab for that server. |
| Example: | set context [findcontext irc.whatever.com] set context [findcontext #mychannel] set context [findcontext irc.whatever.com #thatchannel] set context [findcontext] |
| Notes: | This function is not normally needed with the tclplugin. It is included only to add completeness with the XChat C API. |
| See Also: | getcontext, setcontext |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | getcontext - Returns the current context for your plugin. |
| Synopsis: | getcontext |
| Description: | Returns the current context for your plugin. You can use this later with setcontext. |
| Example: | set context [getcontext] |
| Notes: | This function is not normally needed with the tclplugin. It is included only to add completeness with the XChat C API. |
| See Also: | findcontext, setcontext |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | getinfo - Returns information based on your current context. | ||||||||||||||||||
| Synopsis: | getinfo field |
||||||||||||||||||
| Description: | Provides direct access to XChat C API command xhat_get_info. Most of these have replacement tcl plugin commands that offer more functionality.
The following fields are currently defined:
|
||||||||||||||||||
| Example: | print "I am using XChat [getinfo version]" |
||||||||||||||||||
| See Also: | away, channel, host, me, network, server, topic, version, configdir | ||||||||||||||||||
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | getlist - Returns information from XChats list of lists |
| Synopsis: | getlist ?listname? |
| Description: | Returns a list of information from XChat's internal list of lists. If listname is omitted, the names of all the available lists are returned.
The first entry in the list is the names of all the fields for that list. The rest of list are the actual list entries. |
| See Also: | channels, dcclist, ignores, queries, servers |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | host - Returns the hostname of the server. |
| Synopsis: | host ?server|context? |
| Description: | Returns the hostname of the server you connected to. If you connected to a networks round-robin name, e.g. irc.openprojects.org, irc.newnet.net, etc., it will return that name. If server is omitted, the current one is assumed. |
| Example: | print "I attempted to connect to [host] on [network]." print "I am actually connected to [server]." |
| Notes: | If you want to know the exact server name, use server. |
| See Also: | findcontext, getcontext, network, server |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | ignores - Returns list of ignored hosts. |
| Synopsis: | ignores |
| Description: | Returns a list of all ignored hosts.
Each list entry is made up the hostmask being ignored, followed by a sub-list of the types of ignores on that mask. |
| Example: | set ignorelist [ignores]
foreach entry $ignorelist {
print "Ignoring:"
print "[lindex $entry 0]: [lindex $entry 1]"
} |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | killtimer - Kills the specified timer. |
| Synopsis: | killtimer timerID |
| Description: | Removes the specified timerID from the timer queue. |
| See Also: | timer, timerexists, timers |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | me - Returns your nick. |
| Synopsis: | me ?server|context? |
| Description: | Returns your current nick. If server is omitted, the current one is used by default. |
| See Also: | findcontext, getcontext |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | network - Returns the name of the network. |
| Synopsis: | network ?server|context? |
| Description: | Returns the name of the network, relative to the server list, that you are connected to. If no serveris omitted, the current one current one is used by default. |
| Example: | print "I attempted to connect to [host] on [network]." print "I am actually connected to [server]." |
| See Also: | findcontext, getcontext, host, server |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | nickcmp - Performs an RFC1459 compliant string compare. |
| Synopsis: | nickcmp string1 string2 |
| Description: | This command performs an RFC1459 compliant string compare. Use this to compare channels and nicknames. The function works the same way as strcasecmp.
Because of IRC's scandanavian origin, the characters {}| are considered to be the lower case equivalents of the characters [], respectively. This is a critical issue when determining the equivalence of two nicknames. |
| Returns: | An integer less than, equal to, or greater than zero if string1 is found, respectively, to be less than, to match, or be greater than string2. |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | off - Removes a script previously assigned with on |
| Synopsis: | off token ?label? |
| Description: | Removes a script from the specified XChat token and label. If label is omitted, all scripts for that token are removed. |
| See Also: | on |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | on - Execute a command on an irc event | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Synopsis: | on token label { script | procname } |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Description: | Whenever token is triggered, script will be executed. label is some descriptive word that identifies which script is being executed when you have multiple scripts assigned to the same event. It is suggested that you use your initials or the name of your script as the 'label'.
The token can be any server token or an internal XChat event. When executing your script, the following variables will be set:
You may further use splitsrc command to create the additional variables:
For channel management scripts, you may use any word with '!' in front (e.g. !pingme") as the token. Any time someone uses that command in a channel or in a private message, the script will be executed. The following custom XChat internal token are also available:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Example: | on PRIVMSG example {
if { [string match -nocase "*[me]*" $_rest] } {
play mynick.wav
complete
}
}
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Notes: | All events starting with XC_ correspond to the events listed in the Settings->Lists->EventTexts window in XChat. All parameters are appended to $_raw, e.g:
arg1 is [lindex $_raw 1] arg2 is [lindex $_raw 2] arg3 is [lindex $_raw 3] arg4 is [lindex $_raw 4] |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| See Also: | alias, off | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | print - Print text to an xchat window/tab |
| Synopsis: | print ?server|context? ?channel|nick? text |
| Description: | Prints text to a window. If a channel|nick is included, the text is printed to that channel/nick. You may also include a specific server. |
| Example: | # print text to the current window print "Hello, World!" |
| See Also: | findcontext, getcontext, puts |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | queries - Returns a list of private queries. |
| Synopsis: | queries ?server|context? |
| Description: | Returns a list of all private queries. If server is omitted, the server belonging to the current server is used by default. |
| Example: | alias myqueries {
foreach s [servers] {
print "Server: $s"
foreach q [queries $s] {
print " - Query: $q"
}
}
complete
} |
| See Also: | channels, chats, findcontext, getcontext |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | raw - Send a line directly to the server. |
| Synopsis: | raw ?server|context? ?channel|nick? text |
| Description: | This command sends text directly to the server without further processing or interpretation by xchat. If server or channel|nick name is omitted, the current ones are used by default. |
| Example: | raw "PRIVMSG bubba :Howdy Bubba!" |
| See Also: | command, findcontext, getcontext |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | server - Return the current server. |
| Synopsis: | server ?context? |
| Description: | Returns the current server name (what the server claims to be). |
| Example: | print "I attempted to connect to [host] on [network]." print "I am actually connected to [server]." |
| See Also: | findcontext, getcontext, host |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | servers - Returns of list of all servers you are on. |
| Synopsis: | servers |
| Description: | Returns a list of all servers you are currently connected to. |
| Example: | alias mychannels {
foreach s [servers] {
print "Server: $s"
foreach c [channels $s] {
print " - Channel: $c - [topic $s $c]"
}
}
complete
} |
| See Also: | channel, channels, server |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | setcontext - Changes your current context to the one given. |
| Synopsis: | setcontext context |
| Description: | Changes your current context to the one given. The argument context must have been returned by getcontext or findcontext. |
| Example: | set context [findcontext #channel] setcontext $context |
| Notes: | This function is not normally needed with the tclplugin. It is included only to add completeness with the XChat C API. |
| See Also: | findcontext, getcontext |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | timer - Executes tcl command after a certain number of seconds have passed. |
| Synopsis: | timer ?-repeat? ?-count times? seconds {script | procname ?args?} |
| Description: | Executes a tcl command or script after a certain number of seconds have passed.
If the -repeat flag is included, it will will keep repeating until killed with killtimer. If the -count flag is added, it will repeat the number of times specified after the flag. In all other cases, it is executed only once. |
| Example: | timer 5 { /say Times up! } |
| Returns: | timer ID code is to identify the timer with for use with other timer commands. |
| See Also: | killtimer, timerexists, timers |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | timerexists - Returns 1 if the specified timer exists. |
| Synopsis: | timerexists timerID |
| Description: | Determines of the specified timerID exists. |
| Returns: | 1 if the specified timer exists, 0 otherwise |
| See Also: | killtimer, timer, timers |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | timers - Returns a list of timers currently active. |
| Synopsis: | timers |
| Description: | Returns a list of active timers; each entry in the list contains the timerID, the number of seconds left till activation, the command that will be executed, the number of seconds specified, and the number of times left to be executed. |
| Example: | timer 5 { print "Important message coming soon!" }
timer 10 { print "It is now 10 seconds later! Yay!!!!!" }
print "[timers]" |
| See Also: | killtimer, timer, timerexists |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | topic - Returns the topic of a channel. |
| Synopsis: | topic ?server|context? ?channel? |
| Description: | Returns the channel topic from the current channel or from a specific server and channel. |
| Example: | alias mychannels {
foreach s [servers] {
print "Server: $s"
foreach c [channels $s] {
print " - Channel: $c - [topic $s $c]"
}
}
complete
} |
| See Also: | channel, channels, findcontext, getcontext, users |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | users - Returns a list of users in a channel. |
| Synopsis: | users ?server|context? ?channel? |
| Description: | Returns a list of all the users in a channel. The list consists of 4 elements; nick, hostmask, channel status and selected. |
| Example: | alias listusers {
print "- --------------- ----------------------------------------"
foreach user [users] {
print "[format "%-1s" [lindex $user 2]] [format "%-15s" [lindex $user 0]] [lindex $user 1]"
}
} |
| See Also: | channels, findcontext, getcontext, getlist, servers |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | version - Returns XChat version number. |
| Synopsis: | version |
| Description: | Returns the full XChat version number. |
| Example: | print "I am using XChat version [version]" |
| See Also: | configdir |
| Downloads: | Download recommended Tcl plugin support scripts. |
| Name: | configdir - Returns the current HexChat config directory. |
| Synopsis: | configdir |
| Description: | Returns the current xchat config dir within your own user space. |
| Example: | print "My XChat config directory is [configdir]" |
| See Also: | version |
| Downloads: | Download recommended Tcl plugin support scripts. |