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)

Returns All CTCPs.

Returns:

  • (Array<String>) —

    All CTCPs



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

def ctcps
  @ctcps
end

#help ⇒ String?

Returns The help message.

Returns:

  • (String, nil) —

    The help message



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

def help
  @help
end

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

Returns All hooks.

Returns:

  • (Hash{:pre, :post => Array<Hook>}) —

    All hooks



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

def hooks
  @hooks
end

#listeners ⇒ Array<Listener> (readonly)

Returns All listeners.

Returns:



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

def listeners
  @listeners
end

#matchers ⇒ Array<Matcher> (readonly)

Returns All matchers.

Returns:

  • (Array<Matcher>) —

    All matchers



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.

Overloads:

Returns:

  • (String, nil) —

    The name of the plugin



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

def plugin_name
  @plugin_name
end

#prefix ⇒ String, ...

Returns The prefix.

Returns:

  • (String, Regexp, Proc) —

    The prefix



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

def prefix
  @prefix
end

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

Returns The list of events to react on.

Returns:

  • (Array<:message, :channel, :private>) —

    The list of events to react on



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

def react_on
  @react_on
end

#required_options ⇒ Array<Symbol>

Returns Required plugin options.

Returns:

  • (Array<Symbol>) —

    Required plugin options



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

def required_options
  @required_options
end

#suffix ⇒ String, ...

Returns The suffix.

Returns:

  • (String, Regexp, Proc) —

    The suffix



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

def suffix
  @suffix
end

#timers ⇒ Array<Timer> (readonly)

Returns All timers.

Returns:

  • (Array<Timer>) —

    All timers



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.

Returns:

  • (Hash) 


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.

Returns:

  • (Boolean) —

    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.

Parameters:

Returns:

  • (Array<Symbol>, nil)

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.

Parameters:

  • type (: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: :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.

Returns:

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.

Parameters:

  • *types (String, Symbol, Integer) —

    Events to listen to. Available events are all IRC commands in lowercase as symbols, all numeric replies and all events listed in the list of events.

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

Options Hash (options):

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

    The method to execute

Returns:



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.

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.

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

Returns:



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(key, value)

    This method returns an undefined value.

    Parameters:

    • key (Symbol) —

      The option’s name

    • value (Object)
  • #set(options)

    This method returns an undefined value.

    Examples:

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

    Parameters:

    • options (Hash{Symbol => Object}) —

      The options, as key => value associations

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

Parameters:

  • interval (Numeric) —

    Interval in seconds

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

    a customizable set of options

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.

Returns:

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