module Cinch::Plugin

This class represents the core of the plugin functionality of Cinch. It provides both the methods for users to write their own plugins as well as for the Cinch framework to use them.

The {ClassMethods} module, which will get included automatically in all classes that include `Cinch::Plugin`, includes all class methods that the user will use for creating plugins.

Most of the instance methods are for use by the Cinch framework and part of the private API, but some will also be used by plugin authors, mainly {#config}, {#synchronize} and {#bot}.

Attributes

bot[R]

@return [Bot]

handlers[R]

@return [Array<Handler>] handlers

timers[R]

@return [Array<Cinch::Timer>]

Public Class Methods

included(by) click to toggle source

@api private

# File lib/cinch/plugin.rb, line 509
def self.included(by)
  by.extend ClassMethods
end
new(bot) click to toggle source

@api private

# File lib/cinch/plugin.rb, line 472
def initialize(bot)
  @bot = bot
  @handlers = []
  @timers   = []
  __register
end

Public Instance Methods

__register() click to toggle source

@return [void] @api private

# File lib/cinch/plugin.rb, line 448
def __register
  missing = self.class.check_for_missing_options(@bot)
  unless missing.empty?
    @bot.loggers.warn "[plugin] #{self.class.plugin_name}: Could not register plugin because the following options are not set: #{missing.join(", ")}"
    return
  end

  __register_listeners
  __register_matchers
  __register_ctcps
  __register_timers
  __register_help
end
config() click to toggle source

Provides access to plugin-specific options.

@return [Hash] A hash of options

# File lib/cinch/plugin.rb, line 500
def config
  @bot.config.plugins.options[self.class] || {}
end
shared() click to toggle source
# File lib/cinch/plugin.rb, line 504
def shared
  @bot.config.shared
end
synchronize(name, &block) click to toggle source

(see Bot#synchronize)

# File lib/cinch/plugin.rb, line 493
def synchronize(name, &block)
  @bot.synchronize(name, &block)
end
unregister() click to toggle source

@since 2.0.0

# File lib/cinch/plugin.rb, line 480
def unregister
  @bot.loggers.debug "[plugin] #{self.class.plugin_name}: Unloading plugin"
  @timers.each do |timer|
    timer.stop
  end

  handlers.each do |handler|
    handler.stop
    handler.unregister
  end
end

Private Instance Methods

__register_ctcps() click to toggle source
# File lib/cinch/plugin.rb, line 363
def __register_ctcps
  self.class.ctcps.each do |ctcp|
    @bot.loggers.debug "[plugin] #{self.class.plugin_name}: Registering CTCP `#{ctcp}`"
    new_handler = Handler.new(@bot, :ctcp, Pattern.generate(:ctcp, ctcp)) do |message, *args|
      if self.class.call_hooks(:pre, :ctcp, nil, self, [message])
        __send__("ctcp_#{ctcp.downcase}", message, *args)
        self.class.call_hooks(:post, :ctcp, nil, self, [message])
      else
        @bot.loggers.debug "[plugin] #{self.class.plugin_name}: Dropping message due to hook"
      end
    end

    @handlers << new_handler
    @bot.handlers.register(new_handler)
  end
end
__register_help() click to toggle source
# File lib/cinch/plugin.rb, line 430
def __register_help
  prefix = self.class.prefix || @bot.config.plugins.prefix
  suffix = self.class.suffix || @bot.config.plugins.suffix
  if self.class.help
    @bot.loggers.debug "[plugin] #{self.class.plugin_name}: Registering help message"
    help_pattern = Pattern.new(prefix, "help #{self.class.plugin_name}", suffix)
    new_handler = Handler.new(@bot, :message, help_pattern) do |message|
      message.reply(self.class.help)
    end

    @handlers << new_handler
    @bot.handlers.register(new_handler)
  end
end
__register_listeners() click to toggle source
# File lib/cinch/plugin.rb, line 345
def __register_listeners
  self.class.listeners.each do |listener|
    @bot.loggers.debug "[plugin] #{self.class.plugin_name}: Registering listener for type `#{listener.event}`"
    new_handler = Handler.new(@bot, listener.event, Pattern.new(nil, //, nil)) do |message, *args|
      if self.class.call_hooks(:pre, :listen_to, nil, self, [message])
        __send__(listener.method, message, *args)
        self.class.call_hooks(:post, :listen_to, nil, self, [message])
      else
        @bot.loggers.debug "[plugin] #{self.class.plugin_name}: Dropping message due to hook"
      end
    end

    @handlers << new_handler
    @bot.handlers.register(new_handler)
  end
end
__register_matchers() click to toggle source
# File lib/cinch/plugin.rb, line 392
def __register_matchers
  prefix = self.class.prefix || @bot.config.plugins.prefix
  suffix = self.class.suffix || @bot.config.plugins.suffix

  self.class.matchers.each do |matcher|
    _prefix = matcher.use_prefix ? matcher.prefix || prefix : nil
    _suffix = matcher.use_suffix ? matcher.suffix || suffix : nil

    pattern_to_register = Pattern.new(_prefix, matcher.pattern, _suffix)
    react_on = matcher.react_on || self.class.react_on || :message

    @bot.loggers.debug "[plugin] #{self.class.plugin_name}: Registering executor with pattern `#{pattern_to_register.inspect}`, reacting on `#{react_on}`"

    new_handler = Handler.new(@bot,
                              react_on,
                              pattern_to_register,
                              group: matcher.group,
                              strip_colors: matcher.strip_colors) do |message, *args|
      method = method(matcher.method)
      arity = method.arity - 1
      if arity > 0
        args = args[0..arity - 1]
      elsif arity == 0
        args = []
      end
      if self.class.call_hooks(:pre, :match, matcher.group, self, [message])
        method.call(message, *args)
        self.class.call_hooks(:post, :match, matcher.group, self, [message])
      else
        @bot.loggers.debug "[plugin] #{self.class.plugin_name}: Dropping message due to hook"
      end
    end
    @handlers << new_handler
    @bot.handlers.register(new_handler)
  end
end
__register_timers() click to toggle source
# File lib/cinch/plugin.rb, line 381
def __register_timers
  @timers = self.class.timers.map {|timer_struct|
    @bot.loggers.debug "[plugin] #{self.class.plugin_name}: Registering timer with interval `#{timer_struct.interval}` for method `#{timer_struct.options[:method]}`"

    block = self.method(timer_struct.options[:method])
    options = timer_struct.options.merge(interval: timer_struct.interval)
    Cinch::Timer.new(@bot, options, &block)
  }
end