DOC

XChat-Ruby Plugin v. 1.1

Jamis Buck <jgb3@email.byu.edu>
6 June 2003
===============================

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.


Usage
-----

Once the plugin has been loaded, you can interact with it using the following
commands:

  /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
XChat-Ruby plugin.


Plugin Documentation
--------------------

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
plugins.

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.

  class XChatRubyEnvironment
  --------------------------

  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).

  class XChatRubyPlugin
  ---------------------

  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
  unhook() function.
  
    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
        parameters:

          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.

    print( text )
        Prints the given text to the currently active tab/window.  No newline
        is appended.

    print( text, channel )
        Prints the given text to the first tab/window displaying the given channel.
        No newline is appended.

    print( text, server, channel )
        Prints the given text to the first tab/window displaying the given channel for
        the given server.  No newline is appended.

    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 '/').

    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.

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

          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.

        For example:

          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.


  class XChatRubyList
  -------------------

  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.

    next
        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.