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:

  • All CTCPs



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

def ctcps
  @ctcps
end

#help ⇒ String?

Returns The help message.

Returns:

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

  • All hooks



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

def hooks
  @hooks
end

#listeners ⇒ Array<Listener> (readonly)

Returns All listeners.

Returns:

  • All listeners



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

def listeners
  @listeners
end

#matchers ⇒ Array<Matcher> (readonly)

Returns All matchers.

Returns:

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

  • #plugin_name ⇒ String?

    Returns:

  • #plugin_name=(new_name) ⇒ String

    Parameters:

    Returns:

Returns:

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

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

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

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

  • The suffix



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

def suffix
  @suffix
end

#timers ⇒ Array<Timer> (readonly)

Returns All timers.

Returns:

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

API:

  • private



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:

API:

  • private



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:

  • True if processing should continue

API:

  • private



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.

Since:

  • 2.0.0

Parameters:

Returns:

API:

  • private



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.

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

Parameters:

  • Run the hook before or after a handler?

  • (defaults to: {})

    a customizable set of options

Returns:



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.

Options Hash (options):

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

    The method to execute

Parameters:

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

  • (defaults to: {})

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.

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

Parameters:

  • A pattern

  • (defaults to: {})

    a customizable set of options

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:

    • The option’s name

  • #set(options) ⇒ void

    This method returns an undefined value.

    Examples:

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

    Parameters:

    • 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

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

Parameters:

  • Interval in seconds

  • (defaults to: {})

    a customizable set of options

Returns:



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