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

- (Array<String>) ctcps (readonly)

All CTCPs

Returns:

  • (Array<String>) —

    All CTCPs



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

def ctcps
  @ctcps
end

- (String?) help

The help message

Returns:

  • (String, nil) —

    The help message



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

def help
  @help
end

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

All hooks

Returns:

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

    All hooks



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

def hooks
  @hooks
end

- (Array<Listener>) listeners (readonly)

All listeners

Returns:



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

def listeners
  @listeners
end

- (Array<Matcher>) matchers (readonly)

All matchers

Returns:

  • (Array<Matcher>) —

    All matchers



52
53
54
 
# File 'lib/cinch/plugin.rb', line 52

def matchers
  @matchers
end

- (String?) plugin_name - (String) plugin_name=(new_name)

The name of the plugin.

Overloads:

Returns:

  • (String, nil) —

    The name of the plugin



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

def plugin_name
  @plugin_name
end

- (String, ...) prefix

The prefix

Returns:

  • (String, Regexp, Proc) —

    The prefix



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

def prefix
  @prefix
end

- (Array<:message, :channel, :private>) react_on

The list of events to react on

Returns:

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

    The list of events to react on



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

def react_on
  @react_on
end

- (Array<Symbol>) required_options

Required plugin options

Returns:

  • (Array<Symbol>) —

    Required plugin options



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

def required_options
  @required_options
end

- (String, ...) suffix

The suffix

Returns:

  • (String, Regexp, Proc) —

    The suffix



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

def suffix
  @suffix
end

- (Array<Timer>) timers (readonly)

All timers

Returns:

  • (Array<Timer>) —

    All timers



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

def timers
  @timers
end

Instance Method Details

- (Hash) __hooks(type = nil, events = nil)

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) 


269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
 
# File 'lib/cinch/plugin.rb', line 269

def __hooks(type = nil, events = 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
    return hooks.select { |hook| (events & hook.for).size > 0 }
  end
end

- (Boolean) call_hooks(type, event, instance, args)

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.

True if processing should continue

Returns:

  • (Boolean) —

    True if processing should continue



289
290
291
292
293
294
295
296
297
298
299
300
 
# File 'lib/cinch/plugin.rb', line 289

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

- (Array<Symbol>?) check_for_missing_options(bot)

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



306
307
308
309
310
 
# File 'lib/cinch/plugin.rb', line 306

def check_for_missing_options(bot)
  @required_options.select { |option|
    !bot.config.plugins.options[self].has_key?(option)
  }
end

- (Object) ctcp(command)

Version:

  • 1.1.1



217
218
219
 
# File 'lib/cinch/plugin.rb', line 217

def ctcp(command)
  @ctcps << command.to_s.upcase
end

- (Hook) hook(type, options = {})

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: true —

    The method to execute.

Returns:

Since:

  • 1.1.0



259
260
261
262
263
264
265
 
# File 'lib/cinch/plugin.rb', line 259

def hook(type, options = {})
  options = {:for => [:match, :listen_to, :ctcp], :method => :hook}.merge(options)
  hook = Hook.new(type, options[:for], options[:method])
  __hooks(type) << hook

  hook
end

- (Array<Listener>) listen_to(*types, options = {})

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:



204
205
206
207
208
209
210
211
212
213
214
 
# File 'lib/cinch/plugin.rb', line 204

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

- (Matcher) match(pattern, options = {})

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.

Returns:



184
185
186
187
188
189
190
191
192
193
 
# File 'lib/cinch/plugin.rb', line 184

def match(pattern, options = {})
  options = {:use_prefix => true, :use_suffix => true, :method => :execute, :group => nil, :prefix => nil, :suffix => nil, :react_on => nil}.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))
  @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



150
151
152
153
154
155
156
157
158
159
160
161
162
163
 
# File 'lib/cinch/plugin.rb', line 150

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) timer(interval, options = {})

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



241
242
243
244
245
246
247
 
# File 'lib/cinch/plugin.rb', line 241

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

  timer
end