XChat-Ruby Plugin v. 1.2
Jamis Buck <firstname.lastname@example.org>
25 April 2007
This is a plugin for XChat2 (http://www.xchat.org) which allows you to use
plugins written in the Ruby scripting language (http://www.ruby-lang.org).
Installation and Configuration
See the INSTALL file.
Once the plugin has been loaded, you can interact with it using the following
/rb help -- displays a list of available /rb commands
/rb load <filename> -- load (and execute) a ruby script/plugin
/rb unload <filename> -- unload the given ruby script/plugin
/rb list -- show all loaded ruby scripts/plugins
/rb commands -- show all available ruby-based commands
/rb exec <code> -- execute ruby code immediately
/rb about -- display copyright and credits info about the plugin
Additionally, the XChat-Ruby plugin extends the /load and /unload commands, so that if
you specify a file with a '.rb' extension, it will load (or unload) it with the
If you are a Ruby programmer and would like to use this plugin to write your
own plugins in Ruby, this section will attempt to document the XChat/Ruby
API and how to use it. You should also refer to the XChat C API
(http://www.xchat.org/docs/plugin20.html), since it will describe the
API functions and how they work in greater detail. Also, the plugins in
the samples directory will be helpful in learning how to write your own
Typically, creating a ruby plugin involves creating a class that inherits
from XChatRubyPlugin, registering the necessary hooks in the new class's
initialize method, and then defining the hooks and auxiliary methods. At
the very end, instantiate the class; this will start your plugin.
All of these classes are in the XChatRuby module, which may be included
in your plugin source for convenience.
You will rarely need to access the class directly, but there are a few
(singleton) methods of it that you may find useful.
XChatRubyEnvironment.load_plugin( file )
Loads the given (Ruby) source file as a Ruby plugin. The 'file'
parameter must either be an absolute path, or refer to a file
in one of the paths of the Ruby environment's $LOAD_PATH array.
XChatRubyEnvironment.unload_plugin( file )
Unloads the given (Ruby) source file as a Ruby plugin. The 'file'
parameter must be exactly the same as the name given when the
plugin was loaded.
XChatRubyEnvironment.remove_hooks_for( requester )
This will remove all registered hooks for a given plugin (requester).
The XChatRubyPlugin class is the interface for the XChat API. You should
inherit your plugin classes from this class.
All of the 'hook' methods that require a priority should use one of the
XCHAT_PRI_xxx constants for that parameter. Likewise, any hook callback
should return one of the XCHAT_EAT_xxx constants. All of the hook methods
return an opaque XChatHook object, which may be used with the
hook_command( name, priority, hook, help, data )
Registers a command hook, with the given name and help text. The 'hook'
parameter must be a Method object (as returned by the method() function)
and should accept three parameters:
hook_fn( words, words_eol, data )
where 'words' and 'words_eol' are identical to the same parameters as
described in the XChat plugin API.
hook_print( name, priority, hook, data )
Registers a callback to be called when the named print even occurs. The
hook parameter must be a Method object and should accept two parameters:
hook_fn( words, data )
hook_server( name, priority, hook, data )
Registers a callback to be called when the named server event is recieved.
The hook parameter should be a Method object and should accept three
hook_fn( words, words_eol, data )
hook_timer( timeout, hook, data )
Registers a timer, which will call the given hook every 'timeout' milliseconds
until it is removed (with unhook()). The hook should be a Method object and
should accept one parameter:
hook_fn( data )
unhook( hook_id )
Unregisters the previously-registered hook with the given 'id'. The
hook_id parameter should be a XChatHook object that was returned by a
prior call to one of the hook_xxx methods.
Note for print and puts:
The output is only visible to you. Use /say to post messages to the channel.
print( text )
Prints the given text to the current context (currently active channel
or server tab/window).
print( text, channel )
Prints the given text to the first matching channel, or the current
context if no match.
print( text, server, nil )
Prints the given text to the first channel or server context of the
given server, or the current context if no match.
print( text, server, channel )
Prints the given text to the channel with matching channel and server,
or the current context if no match.
puts( text )
puts( text, channel )
puts( text, server, channel )
Just like the "print" functions, but also appends a newline.
print_fmt( text )
print_fmt( text, channel )
print_fmt( text, server, channel )
Just like the "print" functions, but also processes 'text' through the
XChatText.format method (see below).
puts_fmt( text )
puts_fmt( text, channel )
puts_fmt( text, server, channel )
Just like the "puts" functions, but also processes 'text' through the
XChatText.format method (see below).
command( command )
Has XChat process the given command (without the '/').
find_context( channel )
find_context( server, channel )
Returns the context with matching server and channel, or nil if not
If server or channel is nil, the first match of the non-nil argument is
The server name is what is listed in the XChat Network List, including
Returns the current context.
set_context( context )
Sets the current context to context.
get_info( id )
Returns either nil (if the given id doesn't match any known information
parameter), or a string or integer defining the named information parameter.
get_prefs( name )
Returns the named preference item, or nil if the item doesn't exist.
nickcmp( s1, s2 )
Compares the two nicknames (as strcasecmp()), taking into account servers
and so forth.
emit_print( event, ... )
Emits the named print event with the given parameters.
XChat-Ruby 1.2 only supports 16 events.
format( text )
The 'text' parameter may contain formatting codes to define where
text should be bolded, inverted (or underlined), or where the color
should be changed. The formatted text is returned.
Formatting codes are contained in ![...] delimiters. Valid codes
b -- toggle bold
u -- toggle underline
r -- toggle reverse text
i -- toggle italics
o -- turn off all font color and attributes
| -- (the pipe character) -- puts all preceding text in the gutter
c -- reset colors to defaults
cn -- set foreground color to 'n' (see below)
cn,m -- set foreground color to 'n' and background color to 'm'
For the valid 'n' and 'm' color values, you may specify a number
(corresponding to the valid mIRC color indices), or the name of
a color in parentheses.
For the '|' (pipe) code, the preceding text will only be placed in the
gutter if the text is printed (ie, print or puts). If the formatted text
is sent through an IRC command (ie, /msg), the '|' code is ignored.
format( "some ![c(red)b]RED![bc] text" )
This would format the word RED, with a red foreground, in bold.
Valid color names are white, black, blue, green, red, brown, purple,
orange, yellow, ltgreen, teal, ltcyan, ltblue, pink, grey, and ltgrey.
How do you output text containing '!['?
Just format the formatting and output the text in between the formatting
format( "![b]") + "some ![c(red)b]RED![bc] text" + format( "![b]" )
This formats the string "some ![c(red)b]RED![bc] text" in bold.
This class is the interface for the XChat list API. Each list request instantiates
a new XChatRubyList.
XChatRubyList.new( name )
Creates new list of the given name.
Moves to the next item in the list. Returns 0 if the end of the list has been
reached, or 1 if it has moved to a valid item.
str( name )
Returns the given named field of the current record as a string.
int( name )
Returns the given named field of the current record as an integer.