Tcl Plugin for XChat 1.9.x - 2.x

This file includes names, descriptions and examples of added commands and TCL language extensions for XChat IRC Client.

Tcl Plugin XChat Commands:
/rehash, /source, /tcl

Tcl Plugin TCL Commands:
alias, away, channel, channels, chats, command, complete, dcclist, findcontext, getcontext, getinfo, getlist, host, ignores, killtimer, me, network, nickcmp, off, on, print, queries, raw, server, servers, setcontext, timer, timerexists, timers, topic, users, version, xchatdir

Tcl Plugin XChat Commands

Name: /rehash - Clear and reload all tcl scripts.
Synopsis: 
/rehash
Description: Clears out and reloads all tcl scripts. Any variables defined and any files open are lost.
See Also: /source

Name: /source - Load a specific tcl script file.
Synopsis: 
/source filename
Description: Loads a tcl script into XChat.
See Also: /rehash

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 xchatdir

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:

$_cmd the alias name
$_rest params included with alias

Example: 
# do 'ls -al' command on any directory
alias ls { 
  print "[eval "exec ls -al $_rest"]"
  complete
}

# brag about my uptime
alias uptime {
 /say [bold][me]'s Uptime:[bold] [string trim [exec uptime]]
}
See Also: complete, on

Name: away - Returns your /away message.
Synopsis: 
away ?server?
Description: Returns your /away message. If no server is omitted, the current server is assumed.
Example: 
set awaymsg [away]

Name: channel - Return the current query/channel name.
Synopsis: 
channel
Description: Returns the name of the current channel or query.
Example: 
set thischannel [channel]
See Also: channels, server, servers

Name: channels - Returns of list of all channels you are in.
Synopsis: 
channels ?server?
Description: Returns a list of all channels you are in. If server 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, server, servers

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

Name: command - Simulate a command entered into xchat.
Synopsis: 
command ?server? ?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: raw

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.

EAT_NONE Allows all other plugins and xchat to see this event.
EAT_XCHAT Halts further processing by xchat
EAT_PLUGIN Halts further processing by other plugins (default).
EAT_ALL Halts further processing by other plugins and xchat.

Example: 
on XC_TABOPEN whatever {
  print "Hello from [channel]"
  complete
}

alias bar {
  /me has been on irc long enough to still be traumatized by !bar scripts.
  complete
}
See Also: alias, on

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:

type chatsend, chatrecv, filesend, filerecv.
status queued, active, failed, done, connecting, aborted.
nick Nick of other user.
filename Name of file being sent or reveived.
size size of file being sent or reveived.
resume resume position of file being sent or reveived.
pos current position of file being sent or reveived.
cps current transfer speed in bytes per second.

Example: 
foreach entry [dcclist] {
  print "$entry"
}
See Also: chats

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 [findconext irc.whatever.com]
set context [findconext #mychannel]
set context [findconext irc.whatever.com #thatchannel]
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

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 [getconext]
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

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:

away away reason or NULL if you are not away.
channel current channel name.
host real hostname of the server you connected to.
network current network name or NULL.
nick your current nick name.
server current server name (what the server claims to be).
topic current channel topic.
version xchat version number.
xchatdir xchat config directory, e.g.: /home/user/.xchat.

Example: 
print "I am using XChat [getinfo version]"
See Also: away, channel, host, me, network, server, topic, version, xchatdir

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, names, queries, servers

Name: host - Returns the hostname of the server.
Synopsis: 
host ?server?
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: network, server

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]"
}

Name: killtimer - Kills the specified timer.
Synopsis: 
killtimer timerID
Description: Removes the specified timerID from the timer queue.
See Also: timer, timerexists, timers

Name: me - Returns your nick.
Synopsis: 
me ?server?
Description: Returns your current nick. If server is omitted, the current one is used by default.

Name: network - Returns the name of the network.
Synopsis: 
network ?server?
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: host, server

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.

Name: off - Removes a script previously assigned with on
Synopsis: 
off event ?label?
Description: Removes a script from the specified XChat event and label. If label is omitted, all scripts for that event are removed.
See Also: on

Name: on - Execute a command on an irc event
Synopsis: 
on numeric label { script | procname }
Description: Whenever numeric 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.

The numeric can be any server numeric or an internal XChat event. When executing your script, the following variables will be set:

$_label As defined by the 'on' command.
$_src source of the event. nick!ident@host -or- irc.servername.com
$_cmd irc command. JOIN, PRIVMSG, KICK, etc.
$_dest intended target of this event. nick,
$_rest the rest of the message.
$_raw the raw line received from the irc server.
$_private '0' means the message was public, '1' = private.


You may further use splitsrc command to create the additional variables:

$_nick irc user nick extracted from $_src
$_ident irc user ident extracted from $_src
$_host irc user hostname extracted from $_src


For channel management scripts, you may use any word with '!' in front (e.g. !pingme") as the numeric. Any time someone uses that command in a channel or in a private message, the script will be executed.

The following custom XChat internal numerics are also available:

ACTION Incoming /me whatever action command.
CHAT Incoming line of text from dcc chat conversation.
CTCP Incoming CTCP (PING, VERSION, etc)
CTCR Incoming reply from your CTCP to someone else.
SNOTICE Incoming notice from a server.
XC_TABOPEN A new channel/nick/server tabs was created.
XC_TABCLOSE One of the channel/nick/server tabs was closed.
XC_TABFOCUS You changed focus to a new tab.
XC_ADDNOTIFY Add Notify
XC_BANLIST Ban List
XC_BANNED Banned
XC_CHANGENICK Change Nick
XC_CHANACTION Channel Action
XC_HCHANACTION Channel Action Hilight
XC_CHANBAN Channel Ban
XC_CHANDATE Channel Creation
XC_CHANDEHOP Channel DeHalfOp
XC_CHANDEOP Channel DeOp
XC_CHANDEVOICE Channel DeVoice
XC_CHANEXEMPT Channel Exempt
XC_CHANHOP Channel Half-Operator
XC_CHANINVITE Channel INVITE
XC_CHANLISTHEAD Channel List
XC_CHANMSG Channel Message
XC_CHANMODEGEN Channel Mode Generic
XC_CHANMODES Channel Modes
XC_HCHANMSG Channel Msg Hilight
XC_CHANNOTICE Channel Notice
XC_CHANOP Channel Operator
XC_CHANRMEXEMPT Channel Remove Exempt
XC_CHANRMINVITE Channel Remove Invite
XC_CHANRMKEY Channel Remove Keyword
XC_CHANRMLIMIT Channel Remove Limit
XC_CHANSETKEY Channel Set Key
XC_CHANSETLIMIT Channel Set Limit
XC_CHANUNBAN Channel UnBan
XC_CHANVOICE Channel Voice
XC_CONNECTED Connected
XC_CONNECT Connecting
XC_CONNFAIL Connection Failed
XC_CTCPGEN CTCP Generic
XC_CTCPGENC CTCP Generic to Channel
XC_CTCPSEND CTCP Send
XC_CTCPSND CTCP Sound
XC_DCCCHATABORT DCC CHAT Abort
XC_DCCCONCHAT DCC CHAT Connect
XC_DCCCHATF DCC CHAT Failed
XC_DCCCHATOFFER DCC CHAT Offer
XC_DCCCHATOFFERING DCC CHAT Offering
XC_DCCCHATREOFFER DCC CHAT Reoffer
XC_DCCCONFAIL DCC Conection Failed
XC_DCCGENERICOFFER DCC Generic Offer
XC_DCCHEAD DCC Header
XC_MALFORMED DCC Malformed
XC_DCCOFFER DCC Offer
XC_DCCIVAL DCC Offer Not Valid
XC_DCCRECVABORT DCC RECV Abort
XC_DCCRECVCOMP DCC RECV Complete
XC_DCCCONRECV DCC RECV Connect
XC_DCCRECVERR DCC RECV Failed
XC_DCCFILEERR DCC RECV File Open Error
XC_DCCRENAME DCC Rename
XC_DCCRESUMEREQUEST DCC RESUME Request
XC_DCCSENDABORT DCC SEND Abort
XC_DCCSENDCOMP DCC SEND Complete
XC_DCCCONSEND DCC SEND Connect
XC_DCCSENDFAIL DCC SEND Failed
XC_DCCSENDOFFER DCC SEND Offer
XC_DCCSTALL DCC Stall
XC_DCCTOUT DCC Timeout
XC_DELNOTIFY Delete Notify
XC_DISCON Disconnected
XC_FOUNDIP Found IP
XC_IGNOREADD Ignore Add
XC_IGNORECHANGE Ignore Changed
XC_IGNOREFOOTER Ignore Footer
XC_IGNOREHEADER Ignore Header
XC_IGNOREREMOVE Ignore Remove
XC_IGNOREEMPTY Ignorelist Empty
XC_INVITE Invite
XC_INVITED Invited
XC_JOIN Join
XC_KEYWORD Keyword
XC_KICK Kick
XC_KILL Killed
XC_MSGSEND Message Send
XC_MOTD Motd
XC_MOTDSKIP MOTD Skipped
XC_NICKCLASH Nick Clash
XC_NICKFAIL Nick Failed
XC_NODCC No DCC
XC_NOCHILD No Running Process
XC_NOTICE Notice
XC_NOTICESEND Notice Send
XC_NOTIFYEMPTY Notify Empty
XC_NOTIFYHEAD Notify Header
XC_NOTIFYNUMBER Notify Number
XC_NOTIFYOFFLINE Notify Offline
XC_NOTIFYONLINE Notify Online
XC_PART Part
XC_PARTREASON Part with Reason
XC_PINGREP Ping Reply
XC_PINGTIMEOUT Ping Timeout
XC_PRIVMSG Private Message
XC_DPRIVMSG Private Message to Dialog
XC_ALREADYPROCESS Process Already Running
XC_QUIT Quit
XC_RAWMODES Raw Modes
XC_WALLOPS Receive Wallops
XC_RESOLVINGUSER Resolving User
XC_SERVERCONNECTED Server Connected
XC_SERVERERROR Server Error
XC_SERVERLOOKUP Server Lookup
XC_SERVNOTICE Server Notice
XC_SERVTEXT Server Text
XC_STOPCONNECT Stop Connection
XC_TOPIC Topic
XC_TOPICDATE Topic Creation
XC_NEWTOPIC Topic Change
XC_UKNHOST Unknown Host
XC_USERLIMIT User Limit
XC_USERSONCHAN Users On Channel
XC_WHOIS5 WhoIs Away Line
XC_WHOIS2 WhoIs Channel/Oper Line
XC_WHOIS6 WhoIs End
XC_WHOIS4 WhoIs Idle Line
XC_WHOIS4T WhoIs Idle Line with Signon
XC_WHOIS1 WhoIs Name Line
XC_WHOIS3 WhoIs Server Line
XC_UJOIN You Join
XC_UPART You Part
XC_UPARTREASON You Part with Reason
XC_UKICK You Kicked
XC_UINVITE Your Invitation
XC_UCHANMSG Your Message
XC_UCHANGENICK Your Nick Changing

Example: 
on PRIVMSG example {
  if { [string match -nocase "*[me]*" $_rest] } {
    play mynick.wav
    complete
  }
}

on !opme example {
  splitsrc
  /op $_nick
  complete
}

on XC_TABOPEN example {
  switch [string index [channel] 0] {
    "#" -
    "&" -
    "(" -
    "" { return }
  }
  play attention.wav
  print "Now in private conversation with [channel]."
  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

Name: print - Print text to an xchat window/tab
Synopsis: 
print ?server? ?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!"

# print text to the channel or nick window
print #channel "Hello, World!"

# print text to the channel window 
# belonging to a specific server.
print irc.blahblah.com #channel "Hello, World!"
See Also: puts

Name: queries - Returns a list of private queries.
Synopsis: 
queries ?server?
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
}

Name: raw - Send a line directly to the server.
Synopsis: 
raw ?server? ?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

Name: server - Return the current server.
Synopsis: 
server
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: host

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

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

Name: timer - Executes tcl command after a certain number of seconds have passed.
Synopsis: 
timer seconds {script | procname ?args?}
Description: Executes a tcl command or script after a certain number of seconds have passed. It is only executed 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

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

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, and the command that will 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

Name: topic - Returns the topic of a channel.
Synopsis: 
topic ?server? ?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, users

Name: users - Returns a list of users in a channel.
Synopsis: 
users ?server? ?channel?
Description: Returns a list of all the users in a channel. The list consists of 3 elements; nick, hostmask, and channel status.
Example: 
alias listusers {
  print "- --------------- ----------------------------------------"
  foreach user [users] {
    print "[format "%-1s" [lindex $user 2]] [format "%-15s" [lindex $user 0]] [lindex $user 1]"
  }
}
See Also: channels, getlist, servers

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: xchatdir

Name: xchatdir - Returns the current xchat config directory.
Synopsis: 
xchatdir
Description: Returns the current xchat config dir within your own user space.
Example: 
print "My XChat config directory is [xchatdir]"
See Also: version