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, #Sanitize, #Target, #Timer, #Unformat, #User, #debug, #error, #exception, #fatal, #incoming, #info, #log, #outgoing, #rescue_exception, sanitize, #warn

Instance Attribute Details

#bot ⇒ Bot (readonly)

Returns:



463
464
465
 
# File 'lib/cinch/plugin.rb', line 463

def bot
  @bot
end

#handlers ⇒ Array<Handler> (readonly)

Returns handlers.

Returns:



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

def handlers
  @handlers
end

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

Returns:



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

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.



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

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



500
501
502
 
# File 'lib/cinch/plugin.rb', line 500

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. 



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

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

#shared ⇒ Object 



504
505
506
 
# File 'lib/cinch/plugin.rb', line 504

def shared
  @bot.config.shared
end

#synchronize(name) { ... }

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:



493
494
495
 
# File 'lib/cinch/plugin.rb', line 493

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

#unregister ⇒ Object

Since:

  • 2.0.0



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

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