Object XChat

Main interface to XChat scripting.

object XChat

more...

Summary

Main interface to XChat scripting.

This object gives access to the XChat API. It provides informations, callback hook subscription and means to send direct commands to the host XChat applications.

Methods

command()

Sends a command to XChat.

XChat.command( cmd )

This method sends a command to the XChat application engine as if it was digited by the user on the currently active context.

The if the cmd parameter is not a string, it will be automatically converted by the Virtual Machine. This means that the toString FBOM method will be applied.

Note: Do not use a leading "/" before the command. The string is already interpreted as a command, and it doesn't require an extra "/".

Note: Through the command method it is possible to send menu and other GUI commands to the XChat engine. Please, refer to the XChat plugin programming manual for a list of GUI commands that are avaliable to plugins, and also to scripts.

emit()

Generates an XChat print event.

XChat.emit( evt, [...] )

Generates a print event. This can be any event found in the Preferences > Lists > Text Events window.

The FXchat plugin generates a list of print event through the command

/FALCON HELP EVENTS

Each event has zero or more parameters; the parameters passed to this method after the required print event name should be in the same number and order as explained in the text events window or as returned by the HELP EVENTS falcon command.

If the given parameters are not strings, they will be converted to strings by the virtual machine through the toString() basic object method.

findContext()

Finds an xchat context matching the given name.

XChat.findContext( [channel], [server] )

This method searches for a given context among the open panels in an XChat application. Both channel and server parameters are optional.

• If both channel and server are not given or nil, an XChatContext handler to the currently open context is returned.
• If server is not given or nil, the channel is searched among those opened in the currently active server context.
• If channel is nil and server is given, the server context with the matching name is searched.

In case a panel with the required criterion is not found, nil is returned, otherwise a new XChatContext containing the informations of the required panel is returned. That object can be used to send messages or otherwise manipulate the given context without the need to switch to it.

getContext()

Returns a context handler to the currently active context.

XChat.getContext( )

This method returns the currently open context (XChat window or tab) in a XChatContext instance.

Note: Possibly, record this value for later usage; avoid recreating it too often, if not necessary, as creating instances requires extra memory allocation.

getInfo()

Returns textual informations relative to the currently opened context.

XChat.getInfo( info )

This method queries the current context for one of the following informations (to be passed as the info parameter):

• "away": your current away reason or nil if you are not away.
• "channel": current channel name.
• "host": real hostname of the server you connected to.
• "inputbox": the input-box contents, what the user has typed (since 2.4.1).
• "libdirfs": library directory. e.g. /usr/lib/xchat. The same directory used for auto-loading plugins (since 2.4.0).This string isn't necessarily UTF-8, but local file system encoding.
• "network": current network name or NULL.
• "nick": your current nick name.
• "server": current server name (what the server claims to be). NULL if you are not connected.
• "topic": current channel topic.
• "version": xchat version number.
• "win_status": window status: "active", "hidden" or "normal" (since 2.0.9).
• "xchatdir": xchat config directory, e.g.: "/home/user/.xchat2" (since 2.0.9).
• "xchatdirfs": xchat config directory, e.g.: "/home/user/.xchat2" (since 2.0.9).

getPrefs()

ovides xchat's setting information (that which is available through the /set command).

XChat.getPrefs( setting )

Provides xchat's setting information (that which is available through the /set command).

Depending on the setting type the returned value may be a string, an integer or a boolean value; in case the setting cannot be found, the method returns nil.

Note: The preferences can be set via XChat.command, using the "set" command.

hookCommand()

Registers a new XChat command with its handler.

XChat.hookCommand( cmd, cb, [help] )

This method retgisters a command that will be available to XChat console and an handler that will manage it. The command is accesible from the XChat command line (prefixed with a leading "/"), from this plugin or from other plugins.

When the command is invoked, the handler gets called with two parameters:

• The command itself (so it is possible to use the same handler for different commands).
• The text entered after the command.

The handler should return one of the following values:

• XCHAT_EAT_ALL: The handler has managed the input data, and the processing of this command terminates here.
• XCHAT_EAT_XCHAT: The handler wants XChat NOT to manage this command; other plugins with a handler installed on the same command will have the chance to process it.
• XCHAT_EAT_PLUGIN: The handler wants XChat to manage this command, but other plugins having an handler installed on this command will be skipped.
• XCHAT_EAT_NONE: The handler acts as if it didn't process the command; other plugins and XChat will process the command as if this handler wasn't called.

Example:

   function OnReflect( cmd, text )
      > cmd, ": You said: ", text
      return XCHAT_EAT_ALL
   end

   XChat.hookCommand( "TEST", OnReflect, "Replay what you say" )

The cb parameter may be any Falcon callable item, including sigmas; is it so possible to store extra parameters and modify the callback on the fly. In the following sample we pass a parameter by reference to the callback sigma; the parameter is modified by the callback.

   function OnReflect( times, cmd, text )
      > cmd, ": You said: ", text
      > cmd, ": You called this command ", times++, " times."
      return XCHAT_EAT_ALL
   end

   times = 0
   XChat.hookCommand( "TEST", [ OnReflect, $times ], "Replay what you say" )

It would be equally possible to use a global variable and modify directly the sigma array, and of course, it would be possible to change the callable item in front of the sigma to modify the handling object.

The hookCommand method returns an XChatHook class instance; changing the callback property of the returned item it is possible to dynamically modify the handler call (changing the handler function/method or just its sigma parameters).

In example:

   function OnReflect( hook, id, cmd, text )
      > cmd, ": You said: ", text

      // change the callback
      hook.callback = [ OnReflect, $hook, id + 1 ]

      > "Called ", id, " times."

      return XCHAT_EAT_ALL
   end

   handler = XChat.hookCommand( "TEST", [ OnReflect, $handler, 0 ], "Replay what you say" )

The hook handler can be unregistered through the XChatHook.unhook method even from the command handler.

Callable items used as callback points can also be instance methods or sigmas built on methods.

hookPrint()

Registers a new handler for XChat Print events.

XChat.hookPrint( event, cb )

This method installs a print event handler that is called back when the print event occurs (actually, before it occurs). The handler has the chance to block the event and print something else instead, or let the event to flow and to be handled by other handlers and finally by XChat.

The cb item can be any callable Falcon item, including object methods and Sigmas. During the callback, the cb item receives a single parameter (other than eventually declared parameters as Sigmas): a data dictionary containing informations on the event. The data dictionary is granted to have one field called "event" which contains the name of the event that has generated the callback. The other keys in the data dictionary are strings, and the composition of the dictionary depends from the event intercepted. The contents of the data dictionary is described by the /FALCON HELP EVENT command, and the list of events that can be intercepted can be obtained with the /FALCON HELP EVENTS command.

In example:

   object objHandler
      count = 0

      function onEvent( event )
         > "You have received a print event (handler called ", \
            self.count++, " times)."

         > "Events content: "
         inspect( event )

         return XCHAT_EAT_NONE
      end
   end

   //=============
   // Main program

   XChat.hookPrint( "YOU JOIN", objHandler.onEvent )
   XChat.hookPrint( "YOU PART", objHandler.onEvent )

may produce the following output in case of channel join:

 You have received a print event (handler called 0 times).
Events content:
test_print: Dict[4]{
test_print:    "channel" => "#jmtest"
test_print:    "event" => "YOU JOIN"
test_print:    "host" => "~jm@217-133-50-123.b2b.tiscali.it"
test_print:    "nick" => "jonnymind"
test_print: }

See the description of XChat.hookCommand for more informations about the possible usage of sigmas and XChatHook handlers.

hookServer()

Registers a new handler for XChat server message.

XChat.hookServer( event, cb )

This method installs a server message handler that is called back when the specified message is received from the server.

The cb item can be any callable Falcon item, including object methods and Sigmas. During the callback, the cb item receives a single parameter (other than eventually declared parameters as Sigmas): a data dictionary containing informations on the event. The data dictionary is granted to have one field called "event" which contains the name of the event that has generated the callback.

The other keys in the data dictionary are strings, and the composition of the dictionary depends from the event intercepted. The contents of the data dictionary is described by the /FALCON HELP MESSAGE command, and the list of events that can be intercepted can be obtained with the /FALCON HELP MESSAGES command.

In example:

   object objHandler
      count = 0

      function onMessage( event )
         > "You have received a server message (handler called ", \
            self.count++, " times)."

         > "Events content: "
         inspect( event )

         return XCHAT_EAT_NONE
      end
   end

   //=============
   // Main program

   XChat.hookServer( "PRIVMSG", objHandler.onMessage )
   XChat.hookServer( "JOIN", objHandler.onMessage )

may produce the following output in case of channel join:

   You have received a server message (handler called 0 times).
   Events content:
   test_server2: Dict[6]{
   test_server2:    "channel" => "#jmtest"
   test_server2:    "event" => "JOIN"
   test_server2:    "nick" => "jonnymind"
   test_server2:    "nick:all" => "jonnymind!~jm@217-133-50-123.b2b.tiscali.it"
   test_server2:    "nick:net" => "217-133-50-123.b2b.tiscali.it"
   test_server2:    "nick:user" => "~jm"
   test_server2: }

See the description of XChat.hookCommand for more informations about the possible usage of sigmas and XChatHook handlers.

hookTimer()

Registers a new handler for XChat server message.

XChat.hookTimer( timeout, cb )

This method installs a callback handler that will be called after a certain amout of time. The timeout parameter is expressed in seconds and can be a floating point number.

The cb parameter may be any Falcon callable item, including sigmas and methods.

The cb item is called only once; a new registration is necessary if it must be called again.

Note: This method is given for compatibility with simpler programming tecnhiques, but actually using sleep() and/or coroutines for handling timeouts and sleep periods may be preferred in most cases. The sleep() Falcon RTL function will actually give off the control to XChat, resuming the script only after the required sleep time has elapsed; same happens for sleeps and waits performed by coroutines.

list()

Returns the one of the XChat lists.

XChat.list( list )

The method allows to call one of the list functions dynamically. The list parameter can be one of the following values:

• "channels": see XChat.listChannels- "dcc": see XChat.listDcc- "ignore": see XChat.listIgnore- "notify": see XChat.listNotify- "users": see XChat.listUsers

Note: Please, refer to the XChat plugin manual for updated informations about availability of the various list requests and the filed they return under different XChat versions.

listChannels()

Returns the list of tab contexts currently opened (channels, queries and servers).

XChat.listChannels( )

Each entry in the returned array is a dictionary containing the following fields:

• "channel": Channel or query name
• "chantypes": Channel types e.g. "#!&"
• "flags": Server/Channel Bits: 0=Connected 1=Connecting 2=Away 3=EndOfMotd (Login complete) 4=Has WHOX 5=Has IDMSG (FreeNode) 6=Hide Join/Parts 7=Color Paste 8=Beep on Message 9=Blink Tray on Message
• "id": Unique server ID, as an integer
• "lag": Lag in milliseconds
• "maxmodes": Maximum modes per line
• "network": Network name to which this channel belongs
• "nickprefixes": Nickname prefixes e.g. "
• "nickmodes": Nickname mode chars e.g. "ov"
• "queue": Number of bytes in the send-queue
• "server": Server name to which this channel belongs string
• "type": Type of context this is: 1-Server 2-Channel 3-Dialog
• "users" Number of users in this channel

Note: Please, refer to the XChat plugin manual for updated informations about availability of the dictionary fields under different XChat versions.

listDcc()

Returns the list of DCC transfers currently active.

XChat.listDcc( )

Each entry in the returned array is a dictionary containing the following fields:

• "address32":Address of the remote user (ipv4 address)
• "cps": Bytes per second (speed)
• "destfile": Destination full pathname
• "file": File name
• "nick": Nickname of person who the file is from/to
• "port": TCP port number
• "pos": Bytes sent/received
• "resume": Point at which this file was resumed (or zero if it was not resumed)
• "size": File size in bytes, low order 32 bits (cast it to unsigned)
• "sizehigh": File size in bytes, high order 32 bits
• "status": DCC Status: 0-Queued 1-Active 2-Failed 3-Done 4-Connecting 5-Aborted
• "type": DCC Type: 0-Send 1-Receive 2-ChatRecv 3-ChatSend

Note: Please, refer to the XChat plugin manual for updated informations about availability of the dictionary fields under different XChat versions.

listIgnore()

Returns the list of users in the global ignore list .

XChat.listIgnore( )

Each entry in the returned array is a dictionary containing the following fields:

• "mask": Ignore mask. .e.g: *!*string
• "flags": Bit field of flags. 0=Private 1=Notice 2=Channel 3=Ctcp 4=Invite 5=UnIgnore 6=NoSave 7=DCC

Note: Please, refer to the XChat plugin manual for updated informations about availability of the dictionary fields under different XChat versions.

listNotify()

Returns the list of users in the notify list for the current server.

XChat.listNotify( )

Each entry in the returned array is a dictionary containing the following fields:

• "networks": Networks to which this nick applies. Comma separated. May be nil.
• "nick": Nickname string
• "flags" Bit field of flags. 0=Is online.
• "on": Time when user came online (As a TimeStamp instance)
• "off": Time when user went offline (As a TimeStamp instance)
• "seen": Time when user the user was last verified still online (As a TimeStamp instance)

Note: Please, refer to the XChat plugin manual for updated informations about availability of the dictionary fields under different XChat versions.

listUsers()

Returns the list of users in the current channel.

XChat.listUsers( )

Each entry in the returned array is a dictionary containing the following fields:

• "away": Away status 0=not away, 1=away
• "lasttalk": Last time the user was seen talking (as a TimeStamp instance)
• "nick": Nick name
• "host": Host name in the form: user\@host (or nil if not known).
• "prefix": Prefix character, .e.g: \@ or +. Points to a single char.
• "selected": Selected status in the user list, only works for retrieving the user list of the focused tab.

Note: Please, refer to the XChat plugin manual for updated informations about availability of the dictionary fields under different XChat versions.

message()

Sends a message to a channel or a nick name.

XChat.message( target, msg )

This method sends a message for the specified target, which may be any valid IRC target. If the target parameter is prefixed with "#" or "&", the, then the message will be directed to the named channel, otheriwse it will be directed to the given nick.

Both target and msg parameters must be strings.

Note: Actually, this command is just a shortcut to the "PRIVMSG $target :$msg" command.

nickcmp()

Performs a nick name string-wise comparison.

XChat.nickcmp( nick1, nick2 )

Performs a nick name comparison, based on the current server connection. This might be a RFC1459 compliant string compare, or plain ascii (in the case of DALNet). 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.

Note: If the parameters are not strings, they are converted to strings by the Virtual Machine using the toString() basic object method.

sendModes()

Send a mode change request to the current channel.

XChat.sendModes( targets, sign, mode, [modes_per_line] )

Sends a number of channel mode changes to the current channel. For example, you can Op a whole group of people in one go. It may send multiple MODE lines if the request doesn't fit on one. Pass 0 for modes_per_line to use the current server's maximum possible.

Note: This function should only be called while in a channel context.

strip()

Strips mIRC color codes and/or text attributes (bold, underlined etc) from the given string

XChat.strip( string, [flags] )

Strips mIRC color codes and/or text attributes (bold, underlined etc) from the given string.

If not given, flags parameter defaults to 3 (strip all).

Note: If the string parameter is not a string, it is converted to a string by the Virtual Machine using the toString() basic object method.