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

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Helpers

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

Instance Attribute Details

#bot ⇒ Bot (readonly)

Returns:



465
466
467
 
# File 'lib/cinch/plugin.rb', line 465

def bot
  @bot
end

#handlers ⇒ Array<Handler> (readonly)

Returns handlers.

Returns:



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

def handlers
  @handlers
end

#timers ⇒ Array<Cinch::Timer> (readonly)

Returns:



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

def timers
  @timers
end

Class Method Details

.included(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. 



511
512
513
 
# File 'lib/cinch/plugin.rb', line 511

def self.included(by)
  by.extend ClassMethods
end

Instance Method Details

#__register ⇒ void

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.



450
451
452
453
454
455
456
457
458
459
460
461
462
 
# File 'lib/cinch/plugin.rb', line 450

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

#config ⇒ Hash

Provides access to plugin-specific options.

Returns:

  • (Hash) —

    A hash of options



502
503
504
 
# File 'lib/cinch/plugin.rb', line 502

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

#initialize(bot) ⇒ 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. 



474
475
476
477
478
479
 
# File 'lib/cinch/plugin.rb', line 474

def initialize(bot)
  @bot = bot
  @handlers = []
  @timers = []
  __register
end

#shared ⇒ Object 



506
507
508
 
# File 'lib/cinch/plugin.rb', line 506

def shared
  @bot.config.shared
end

#synchronize(name) { ... } ⇒ void

This method returns an undefined value.

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

Parameters:

  • name (String, Symbol) —

    a name for the synchronize block.

Yields:



495
496
497
 
# File 'lib/cinch/plugin.rb', line 495

def synchronize(name, &block)
  @bot.synchronize(name, &block)
end

#unregister ⇒ Object

Since:

  • 2.0.0



482
483
484
485
486
487
488
489
490
491
492
 
# File 'lib/cinch/plugin.rb', line 482

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