Module: Cinch::Plugin::ClassMethods

Defined in:
lib/cinch/plugin.rb

Overview

The ClassMethods module includes all methods that the user will need for creating plugins for the Cinch framework: Setting options (see #set and the attributes) as well as methods for configuring the actual pattern matching (#match, #listen_to).

Furthermore, the attributes allow for programmatically inspecting plugins.

Defined Under Namespace

Classes: Hook, Listener, Matcher, Timer

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#ctcps ⇒ Array<String> (readonly) 



62
63
64
 
# File 'lib/cinch/plugin.rb', line 62

def ctcps
  @ctcps
end

#help ⇒ String? 



65
66
67
 
# File 'lib/cinch/plugin.rb', line 65

def help
  @help
end

#hooks ⇒ Hash{:pre, :post => Array<Hook>} (readonly) 



29
30
31
 
# File 'lib/cinch/plugin.rb', line 29

def hooks
  @hooks
end

#listeners ⇒ Array<Listener> (readonly) 



56
57
58
 
# File 'lib/cinch/plugin.rb', line 56

def listeners
  @listeners
end

#matchers ⇒ Array<Matcher> (readonly) 



53
54
55
 
# File 'lib/cinch/plugin.rb', line 53

def matchers
  @matchers
end

#plugin_name ⇒ String? #plugin_name=(new_name) ⇒ String

The name of the plugin.



41
42
43
 
# File 'lib/cinch/plugin.rb', line 41

def plugin_name
  @plugin_name
end

#prefix ⇒ String, ... 



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

def prefix
  @prefix
end

#react_on ⇒ Array<:message, :channel, :private> 



32
33
34
 
# File 'lib/cinch/plugin.rb', line 32

def react_on
  @react_on
end

#required_options ⇒ Array<Symbol> 



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

def required_options
  @required_options
end

#suffix ⇒ String, ... 



71
72
73
 
# File 'lib/cinch/plugin.rb', line 71

def suffix
  @suffix
end

#timers ⇒ Array<Timer> (readonly) 



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

def timers
  @timers
end

Instance Method Details

#__hooks(type = nil, events = nil, group = 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. 



299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
 
# File 'lib/cinch/plugin.rb', line 299

def __hooks(type = nil, events = nil, group = nil)
  if type.nil?
    hooks = @hooks
  else
    hooks = @hooks[type]
  end

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

  return hooks.select { |hook| hook.group.nil? || hook.group == group }
end

#call_hooks(type, event, group, instance, args) ⇒ Boolean

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 True if processing should continue.



321
322
323
324
325
326
327
328
329
330
331
332
 
# File 'lib/cinch/plugin.rb', line 321

def call_hooks(type, event, group, instance, args)
  stop = __hooks(type, event, group).find { |hook|
    # stop after the first hook that returns false
    if hook.method.respond_to?(:call)
      instance.instance_exec(*args, &hook.method) == false
    else
      instance.__send__(hook.method, *args) == false
    end
  }

  !stop
end

#check_for_missing_options(bot) ⇒ Array<Symbol>?

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.

Since:

  • 2.0.0



338
339
340
341
342
 
# File 'lib/cinch/plugin.rb', line 338

def check_for_missing_options(bot)
  @required_options.select { |option|
    !bot.config.plugins.options[self].has_key?(option)
  }
end

#ctcp(command) ⇒ Object

Version:

  • 1.1.1



244
245
246
 
# File 'lib/cinch/plugin.rb', line 244

def ctcp(command)
  @ctcps << command.to_s.upcase
end

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

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

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: :hook —

    The method to execute.

  • :group (Symbol) — default: nil —

    The match group to execute the hook for. Hooks belonging to the nil group will execute for all matches.

Since:

  • 1.1.0



289
290
291
292
293
294
295
 
# File 'lib/cinch/plugin.rb', line 289

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

  hook
end

#listen_to(*types, options = {}) ⇒ Array<Listener>

Events to listen to.

Options Hash (options):

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

    The method to execute



231
232
233
234
235
236
237
238
239
240
241
 
# File 'lib/cinch/plugin.rb', line 231

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

  listeners = types.map {|type| Listener.new(type.to_s.to_sym, options[:method])}
  @listeners.concat listeners

  listeners
end

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

TODO:

Document match/listener grouping

Set a match pattern.

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.

  • :use_suffix (Boolean) — default: true —

    If true, the plugin suffix will automatically be appended to the pattern.

  • prefix (String, Regexp, Proc) — default: nil —

    A prefix overwriting the per-plugin prefix.

  • suffix (String, Regexp, Proc) — default: nil —

    A suffix overwriting the per-plugin suffix.

  • react_on (Symbol, Fixnum) — default: :message —

    The event to react on.

  • :group (Symbol) — default: nil —

    The group the match belongs to.

  • :strip_colors (Boolean) — default: false —

    Strip colors from message before attempting match



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
 
# File 'lib/cinch/plugin.rb', line 195

def match(pattern, options = {})
  options = {
    :use_prefix => true,
    :use_suffix => true,
    :method => :execute,
    :group => nil,
    :prefix => nil,
    :suffix => nil,
    :react_on => nil,
    :strip_colors => false,
  }.merge(options)
  if options[:react_on]
    options[:react_on] = options[:react_on].to_s.to_sym
  end
  matcher = Matcher.new(pattern, *options.values_at(:use_prefix,
                                                    :use_suffix,
                                                    :method,
                                                    :group,
                                                    :prefix,
                                                    :suffix,
                                                    :react_on,
                                                    :strip_colors))
  @matchers << matcher

  matcher
end

#set(key, value) #set(options)

This method returns an undefined value.

Set options.

Available options:

Overloads:

  • #set(options)

    This method returns an undefined value.

    Examples:

    set(:help   => "the help message",
    :prefix => "^")

Since:

  • 2.0.0



159
160
161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/cinch/plugin.rb', line 159

def set(*args)
  case args.size
  when 1
    # {:key => value, ...}
    args.first.each do |key, value|
      self.send("#{key}=", value)
    end
  when 2
    # key, value
    self.send("#{args.first}=", args.last)
  else
    raise ArgumentError # TODO proper error message
  end
end

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

Examples:

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

Options Hash (options):

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

    Method to call (only if no proc is provided)

  • :shots (Integer) — default: Float::INFINITY —

    How often should the timer fire?

  • :threaded (Boolean) — default: true —

    Call method in a thread?

  • :start_automatically (Boolean) — default: true —

    If true, the timer will automatically start after the bot finished connecting.

  • :stop_automaticall (Boolean) — default: true —

    If true, the timer will automatically stop when the bot disconnects.

Since:

  • 1.1.0



268
269
270
271
272
273
274
 
# File 'lib/cinch/plugin.rb', line 268

def timer(interval, options = {})
  options = {:method => :timer, :threaded => true}.merge(options)
  timer = Timer.new(interval, options, false)
  @timers << timer

  timer
end