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



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

def ctcps
  @ctcps
end

#help ⇒ String?

Returns The help message.

Returns:

  • (String, nil) —

    The help message



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

def help
  @help
end

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

Returns All hooks.

Returns:

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

    All hooks



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

def hooks
  @hooks
end

#listeners ⇒ Array<Listener> (readonly)

Returns All listeners.

Returns:



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

def listeners
  @listeners
end

#matchers ⇒ Array<Matcher> (readonly)

Returns All matchers.

Returns:

  • (Array<Matcher>) —

    All matchers



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

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



43
44
45
 
# File 'lib/cinch/plugin.rb', line 43

def plugin_name
  @plugin_name
end

#prefix ⇒ String, ...

Returns The prefix.

Returns:

  • (String, Regexp, Proc) —

    The prefix



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

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



34
35
36
 
# File 'lib/cinch/plugin.rb', line 34

def react_on
  @react_on
end

#required_options ⇒ Array<Symbol>

Returns Required plugin options.

Returns:

  • (Array<Symbol>) —

    Required plugin options



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

def required_options
  @required_options
end

#suffix ⇒ String, ...

Returns The suffix.

Returns:

  • (String, Regexp, Proc) —

    The suffix



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

def suffix
  @suffix
end

#timers ⇒ Array<Timer> (readonly)

Returns All timers.

Returns:

  • (Array<Timer>) —

    All timers



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

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) 


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

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

  if events.nil?
    return hooks
  else
    events = [*events]
    hooks = hooks.map { |_k, v| v } if hooks.is_a?(Hash)
    hooks = hooks.reject { |hook| (events & hook.for).empty? }
  end

  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



317
318
319
320
321
322
323
324
325
326
327
328
 
# File 'lib/cinch/plugin.rb', line 317

def call_hooks(type, event, group, instance, args)
  stop = __hooks(type, event, group).find do |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
  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



334
335
336
337
338
 
# File 'lib/cinch/plugin.rb', line 334

def check_for_missing_options(bot)
  @required_options.reject do |option|
    bot.config.plugins.options[self].key?(option)
  end
end

#ctcp(command) ⇒ Object

Version:

  • 1.1.1



242
243
244
 
# File 'lib/cinch/plugin.rb', line 242

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



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

def hook(type, options = {})
  options = { for: %i[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
 
# File 'lib/cinch/plugin.rb', line 231

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

  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:



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 197

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)
  options[:react_on] = options[:react_on].to_s.to_sym if options[:react_on]
  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



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

def set(*args)
  case args.size
  when 1
    # {:key => value, ...}
    args.first.each do |key, value|
      send("#{key}=", value)
    end
  when 2
    # key, value
    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



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

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

  timer
end