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

#ctcpsArray<String> (readonly)

Returns All CTCPs.

Returns:

  • (Array<String>)

    All CTCPs


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

def ctcps
  @ctcps
end

#helpString?

Returns The help message.

Returns:

  • (String, nil)

    The help message


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

def help
  @help
end

#hooksHash{: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

#listenersArray<Listener> (readonly)

Returns All listeners.

Returns:


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

def listeners
  @listeners
end

#matchersArray<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_nameString? #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

#prefixString, ...

Returns The prefix.

Returns:

  • (String, Regexp, Proc)

    The prefix


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

def prefix
  @prefix
end

#react_onArray<: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_optionsArray<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

#suffixString, ...

Returns The suffix.

Returns:

  • (String, Regexp, Proc)

    The suffix


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

def suffix
  @suffix
end

#timersArray<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