Module: Cinch::Plugin::ClassMethods

Defined in:
lib/cinch/plugin.rb

Defined Under Namespace

Classes: Hook, Listener, Match, Timer

Instance Method Summary collapse

Instance Method Details

#__hooks(type = nil, events = nil) ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (Hash) 


145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
 
# File 'lib/cinch/plugin.rb', line 145

def __hooks(type = nil, events = nil)
  @__cinch_hooks ||= Hash.new{|h,k| h[k] = []}

  if type.nil?
    hooks = @__cinch_hooks
  else
    hooks = @__cinch_hooks[type]
  end

  if events.nil?
    return hooks
  else
    events = [*events]
    if hooks.is_a?(Hash)
      hooks = hooks.map { |k, v| v }
    end
    return hooks.select { |hook| (events & hook.for).size > 0 }
  end
end

#__plugin_name ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:



139
140
141
 
# File 'lib/cinch/plugin.rb', line 139

def __plugin_name
  @__cinch_name || self.name.split("::").last.downcase
end

#__register_with_bot(bot, instance) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.



167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
 
# File 'lib/cinch/plugin.rb', line 167

def __register_with_bot(bot, instance)
  plugin_name = __plugin_name

  (@__cinch_listeners || []).each do |listener|
    bot.debug "[plugin] #{plugin_name}: Registering listener for type `#{listener.event}`"
    bot.on(listener.event, [], instance) do |message, plugin, *args|
      if plugin.respond_to?(listener.method)
        plugin.class.__hooks(:pre, :listen_to).each {|hook| plugin.__send__(hook.method, message)}
        plugin.__send__(listener.method, message, *args)
        plugin.class.__hooks(:post, :listen_to).each {|hook| plugin.__send__(hook.method, message)}
      end
    end
  end

  if (@__cinch_matches ||= []).empty?
    @__cinch_matches << Match.new(plugin_name, true, true, :execute)
  end

  prefix = @__cinch_prefix || bot.config.plugins.prefix
  suffix = @__cinch_suffix || bot.config.plugins.suffix

  @__cinch_matches.each do |pattern|
    _prefix = pattern.use_prefix ? prefix : nil
    _suffix = pattern.use_suffix ? suffix : nil

    pattern_to_register = Pattern.new(_prefix, pattern.pattern, _suffix)
    react_on = @__cinch_react_on || :message

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

    bot.on(react_on, pattern_to_register, instance, pattern) do |message, plugin, pattern, *args|
      if plugin.respond_to?(pattern.method)
        method = plugin.method(pattern.method)
        arity = method.arity - 1
        if arity > 0
          args = args[0..arity - 1]
        elsif arity == 0
          args = []
        end
        plugin.class.__hooks(:pre, :match).each {|hook| plugin.__send__(hook.method, message)}
        method.call(message, *args)
        plugin.class.__hooks(:post, :match).each {|hook| plugin.__send__(hook.method, message)}
      end
    end
  end

  (@__cinch_ctcps || []).each do |ctcp|
    bot.debug "[plugin] #{plugin_name}: Registering CTCP `#{ctcp}`"
    bot.on(:ctcp, ctcp, instance, ctcp) do |message, plugin, ctcp, *args|
      plugin.class.__hooks(:pre, :ctcp).each {|hook| plugin.__send__(hook.method, message)}
      plugin.__send__("ctcp_#{ctcp.downcase}", message, *args)
      plugin.class.__hooks(:post, :ctcp).each {|hook| plugin.__send__(hook.method, message)}
    end
  end

  (@__cinch_timers || []).each do |timer|
    bot.debug "[plugin] #{__plugin_name}: Registering timer with interval `#{timer.interval}` for method `#{timer.method}`"
    bot.on :connect do
      next if timer.registered
      timer.registered = true
      Thread.new do
        bot.debug "registering timer..."
        loop do
          sleep timer.interval
          if instance.respond_to?(timer.method)
            l = lambda {
              begin
                instance.__send__(timer.method)
              rescue => e
                bot.logger.log_exception(e)
              end
            }

            if timer.threaded
              Thread.new do
                l.call
              end
            else
              l.call
            end
          end
        end
      end
    end
  end

  if @__cinch_help_message
    bot.debug "[plugin] #{plugin_name}: Registering help message"
    help_pattern = Pattern.new(prefix, "help #{plugin_name}", suffix)
    bot.on(:message, help_pattern, @__cinch_help_message) do |message, help_message|
      message.reply(help_message)
    end
  end
end

#ctcp(command) ⇒ Object 



58
59
60
 
# File 'lib/cinch/plugin.rb', line 58

def ctcp(command)
  (@__cinch_ctcps ||= []) << command.to_s.upcase
end

#help(message) ⇒ void

This method returns an undefined value.

Define a help message which will be returned on “&lt;prefix&gt;help &lt;pluginname&gt;”.

Parameters:



67
68
69
 
# File 'lib/cinch/plugin.rb', line 67

def help(message)
  @__cinch_help_message = message
end

#hook(type, options = {}) ⇒ void

This method returns an undefined value.

Defines a hook which will be run before or after a handler is executed, depending on the value of ‘type`.

Parameters:

  • type (Symbol<:pre, :post>) —

    Run the hook before or after a handler?

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :for (Array<:match, :listen_to, :ctcp>) — default: [:match, :listen_to, :ctcp] —

    Which kinds of events to run the hook for.

  • :method (Symbol) — default: true —

    The method to execute.



132
133
134
135
 
# File 'lib/cinch/plugin.rb', line 132

def hook(type, options = {})
  options = {:for => [:match, :listen_to, :ctcp], :method => :hook}.merge(options)
  __hooks(type) << Hook.new(type, options[:for], options[:method])
end

#listen_to(*types, options = {}) ⇒ void

Events to listen to.

This method returns an undefined value.

Parameters:

  • *types (String, Symbol, Integer) —

    Events to listen to. Available events are all IRC commands in lowercase as symbols, all numeric replies, and the following:

    - :channel (a channel message)
- :private (a private message)
- :message (both channel and private messages)
- :error   (IRC errors)
- :ctcp    (ctcp requests)
  • options (Hash) (defaults to: {})

Options Hash (options):

  • :method (Symbol) — default: :listen —

    The method to execute



45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/cinch/plugin.rb', line 45

def listen_to(*types)
  options = {:method => :listen}
  if types.last.is_a?(Hash)
    options.merge!(types.pop)
  end

  @__cinch_listeners ||= []

  types.each do |type|
    @__cinch_listeners << Listener.new(type, options[:method])
  end
end

#match(pattern, options = {}) ⇒ void

This method returns an undefined value.

Set a match pattern.

Parameters:

  • pattern (Regexp, String) —

    A pattern

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :method (Symbol) — default: :execute —

    The method to execute

  • :use_prefix (Boolean) — default: true —

    If true, the plugin prefix will automatically be prepended to the pattern.



23
24
25
26
27
 
# File 'lib/cinch/plugin.rb', line 23

def match(pattern, options = {})
  options = {:use_prefix => true, :use_suffix => true, :method => :execute}.merge(options)
  @__cinch_matches ||= []
  @__cinch_matches << Match.new(pattern, options[:use_prefix], options[:use_suffix], options[:method])
end

#plugin(name) ⇒ void

This method returns an undefined value.

Define the plugin name.

Parameters:



104
105
106
 
# File 'lib/cinch/plugin.rb', line 104

def plugin(name)
  @__cinch_name = name
end

#prefix(prefix = nil, &block) ⇒ void

This method returns an undefined value.

Set the plugin prefix.

Parameters:

  • prefix (String) (defaults to: nil)

Raises:

  • (ArgumentError) 


75
76
77
78
 
# File 'lib/cinch/plugin.rb', line 75

def prefix(prefix = nil, &block)
  raise ArgumentError if prefix.nil? && block.nil?
  @__cinch_prefix = prefix || block
end

#react_on(target) ⇒ void

This method returns an undefined value.

Set which kind of messages to react on (i.e. call Cinch::Plugin#execute)

Parameters:

  • target (Symbol<:message, :channel, :private>) —

    React to all, only public or only private messages?



96
97
98
 
# File 'lib/cinch/plugin.rb', line 96

def react_on(target)
  @__cinch_react_on = target
end

#suffix(suffix = nil, &block) ⇒ void

This method returns an undefined value.

Set the plugin suffix.

Parameters:

  • suffix (String) (defaults to: nil)

Raises:

  • (ArgumentError) 


84
85
86
87
 
# File 'lib/cinch/plugin.rb', line 84

def suffix(suffix = nil, &block)
  raise ArgumentError if suffix.nil? && block.nil?
  @__cinch_suffix = suffix || block
end

#timer(interval, options = {}) ⇒ void

This method returns an undefined value.

Examples:

timer 5, method: :some_method
def some_method
  Channel("#cinch-bots").send(Time.now.to_s)
end

Parameters:

  • interval (Number) —

    Interval in seconds

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :method (Symbol) — default: :timer —

    Method to call

  • :threaded (Boolean) — default: true —

    Call method in a thread?



117
118
119
120
121
 
# File 'lib/cinch/plugin.rb', line 117

def timer(interval, options = {})
  options = {:method => :timer, :threaded => true}.merge(options)
  @__cinch_timers ||= []
  @__cinch_timers << Timer.new(interval, options[:method], options[:threaded], false)
end