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

Class Method 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

Class Method Details

.extended(by) ⇒ Object

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. 



122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/cinch/plugin.rb', line 122

def self.extended(by)
  by.instance_exec do
    @matchers = []
    @ctcps = []
    @listeners = []
    @timers = []
    @help = nil
    @hooks = Hash.new { |h, k| h[k] = [] }
    @prefix = nil
    @suffix = nil
    @react_on = :message
    @required_options = []
    self.plugin_name = nil
  end
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) 


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

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]
    if hooks.is_a?(Hash)
      hooks = hooks.map { |k, v| v }
    end
    hooks = hooks.select { |hook| (events & hook.for).size > 0 }
  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



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

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



340
341
342
343
344
 
# File 'lib/cinch/plugin.rb', line 340

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



246
247
248
 
# File 'lib/cinch/plugin.rb', line 246

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



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

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:



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

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:



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
 
# 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)
  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) ⇒ void #set(options) ⇒ void

This method returns an undefined value.

Set options.

Available options:

- {#help}
- {#plugin_name}
- {#prefix}
- {#react_on}
- {#required_options}
- {#suffix}

Overloads:

  • #set(key, value) ⇒ void

    This method returns an undefined value.

    Parameters:

    • key (Symbol) —

      The option’s name

    • value (Object)
  • #set(options) ⇒ void

    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



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

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

  timer
end