Module: Cinch::Plugin

Includes:
Helpers
Defined in:
lib/cinch/plugin.rb

Overview

This class represents the core of the plugin functionality of Cinch. It provides both the methods for users to write their own plugins as well as for the Cinch framework to use them.

The ClassMethods module, which will get included automatically in all classes that include Cinch::Plugin, includes all class methods that the user will use for creating plugins.

Most of the instance methods are for use by the Cinch framework and part of the private API, but some will also be used by plugin authors, mainly #config, #synchronize and #bot.

Defined Under Namespace

Modules: ClassMethods

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Methods included from Helpers

#Channel, #Format, #Target, #Timer, #User, #debug, #error, #exception, #fatal, #incoming, #info, #log, #outgoing, #rescue_exception, #warn

Instance Attribute Details

- (Bot) bot (readonly)

Returns:



427
428
429
 
# File 'lib/cinch/plugin.rb', line 427

def bot
  @bot
end

- (Array<Handler>) handlers (readonly)

Handlers

Returns:



430
431
432
 
# File 'lib/cinch/plugin.rb', line 430

def handlers
  @handlers
end

- (Array<Cinch::Timer>) timers (readonly)

Returns:



433
434
435
 
# File 'lib/cinch/plugin.rb', line 433

def timers
  @timers
end

Instance Method Details

- __register

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.

This method returns an undefined value.



412
413
414
415
416
417
418
419
420
421
422
423
424
 
# File 'lib/cinch/plugin.rb', line 412

def __register
  missing = self.class.check_for_missing_options(@bot)
  unless missing.empty?
    @bot.loggers.warn "[plugin] #{self.class.plugin_name}: Could not register plugin because the following options are not set: #{missing.join(", ")}"
    return
  end

  __register_listeners
  __register_matchers
  __register_ctcps
  __register_timers
  __register_help
end

- (Hash) config

Provides access to plugin-specific options.

Returns:

  • (Hash) —

    A hash of options



468
469
470
 
# File 'lib/cinch/plugin.rb', line 468

def config
  @bot.config.plugins.options[self.class] || {}
end

- (Object) initialize(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. 



439
440
441
442
443
444
445
 
# File 'lib/cinch/plugin.rb', line 439

def initialize(bot)
  @bot = bot
  @handlers = []
  @timers   = []
  # @storage  = bot.config.storage.backend.new(@bot.config.storage, self)
  __register
end

- (Object) shared 



472
473
474
 
# File 'lib/cinch/plugin.rb', line 472

def shared
  @bot.config.shared
end

- synchronize(*args) { ... }

Since Cinch uses threads, all handlers can be run simultaneously, even the same handler multiple times. This also means, that your code has to be thread-safe. Most of the time, this is not a problem, but if you are accessing stored data, you will most likely have to synchronize access to it. Instead of managing all mutexes yourself, Cinch provides a synchronize method, which takes a name and block.

Synchronize blocks with the same name share the same mutex, which means that only one of them will be executed at a time.

Examples:

configure do |c|
  …
  @i = 0
end

on :channel, /^start counting!/ do
  synchronize(:my_counter) do
    10.times do
      val = @i
      # at this point, another thread might've incremented :i already.
      # this thread wouldn't know about it, though.
      @i = val + 1
    end
  end
end
configure do |c|
  …
  @i = 0
end

on :channel, /^start counting!/ do
  synchronize(:my_counter) do
    10.times do
      val = @i
      # at this point, another thread might've incremented :i already.
      # this thread wouldn't know about it, though.
      @i = val + 1
    end
  end
end

Parameters:

  • name (String, Symbol) —

    a name for the synchronize block.

  • name (String, Symbol) —

    a name for the synchronize block.

Yields:

Returns:

  • (void)
  • (void) 


461
462
463
 
# File 'lib/cinch/plugin.rb', line 461

def synchronize(*args, &block)
  @bot.synchronize(*args, &block)
end

- (Object) unregister

Since:

  • 2.0.0



448
449
450
451
452
453
454
455
456
457
458
 
# File 'lib/cinch/plugin.rb', line 448

def unregister
  @bot.loggers.debug "[plugin] #{self.class.plugin_name}: Unloading plugin"
  @timers.each do |timer|
    timer.stop
  end

  handlers.each do |handler|
    handler.stop
    handler.unregister
  end
end