Modules

Modules

RubIRCd is extensible via the use of dynamic loadable modules. Modules improve server uptime by allowing you to make changes to them while the server is running. Any fixes or new features you add can be saved and then be reloaded at runtime. An example module is included to use as a template so you can see how to create your own modules. I will walk through the format of a module below. But first, I will show you the four commands used for manipulating server modules. All four commands require administrator privileges. The commands are as follows:

• MODLOAD <module> - loads a module
• MODLIST - lists all loaded modules
• MODRELOAD <module> - reloads a module
• MODUNLOAD <module> - unloads a module

All modules live under the modules/ subdirectory. The naming convention for the file is: <module>.rb. The module name must be all lowercase for the file name. Our sample module looks like this:

module Contributed
  # This is just an example module
  class Example
    def initialize
      @command_name = 'example'
      @command_proc = proc { |user, args| on_example(user, args) }
    end

    def plugin_init(caller)
      caller.register_command(@command_name, @command_proc)
    end

    def plugin_finish(caller)
      caller.unregister_command(@command_name)
    end

    attr_reader :command_name

    def on_example(user, args)
      Network.send(user, "This is a test. You sent: #{args}")
    end
  end
end
Contributed::Example.new

All modules should have a unique class and command name. You can also specify the category of the module with the module keyword. There are three types of modules: Standard (core), Optional (part of the distribution, but not core), and Contributed (user created). Other methods can be defined within the module class and called as needed. For example, if you need to open a file and read in its contents on module load, you could call said method in plugin_init() after the command has been registered. If you are writing to a file in the trigger method, you can also flush any writes and close your file handle in plugin_finish() as another example. Additionally, you can specify command aliases (like OPERWALL is to WALLOPS) by adding an instance variable named @command_alias with a value of your alias as a string in the module's initialize method. It would look like this:

    def initialize
      @command_name = 'example'
      @command_alias = 'sample'
      @command_proc = proc { |user, args| on_example(user, args) }
    end

Then you would add the following line in the plugin_init method after the base command is registered:

    def plugin_init(caller)
      caller.register_command(@command_name, @command_proc)
      caller.register_command(@command_alias, @command_proc)
    end

Lastly, remove the command alias from the server command map using the plugin_finish method:

    def plugin_finish(caller)
      caller.unregister_command(@command_name)
      caller.unregister_command(@command_alias)
    end

You can then load your module by issuing /modload <module>. If you want to load your module automatically when the server starts, add it to cfg/modules.yml. Verify that the module has been loaded by using /modlist.