Class/Module Index [+]

Quicksearch

Cinch::Plugin::ClassMethods

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.

@attr plugin_name

Constants

Hook

Represents a Hook as created by {hook}.

@attr [Symbol] type @attr [Array<Symbol>] for @attr [Symbol] method

Listener

Represents a Listener as created by {listen_to}.

@attr [Symbol] event @attr [Symbol] method

Matcher

Represents a Matcher as created by {match}.

@attr [String, Regexp, Proc] pattern @attr [Boolean] use_prefix @attr [Boolean] use_suffix @attr [Symbol] method @attr [Symbol] group

Timer

Represents a Timer as created by {timer}.

@note This is not the same as a {Cinch::Timer} object, which

will allow controlling and inspecting actually running
timers. This class only describes a Timer that still has to
be created.

@attr [Numeric] interval @attr [Symbol] method @attr [Hash] options @attr [Boolean] registered

Attributes

ctcps[R]

@return [Array<String>] All CTCPs

help[RW]

@return [String, nil] The help message

hooks[R]

@return [Hash{:pre, :post => Array<Hook>}] All hooks

listeners[R]

@return [Array<Listener>] All listeners

matchers[R]

@return [Array<Matcher>] All matchers

plugin_name[R]

The name of the plugin. @overload plugin_name

@return [String, nil]

@overload plugin_name=(new_name)

@param [String, nil] new_name
@return [String]

@return [String, nil] The name of the plugin

prefix[RW]

@return [String, Regexp, Proc] The prefix

react_on[RW]

@return [Array<:message, :channel, :private>] The list of events to react on

required_options[RW]

@return [Array<Symbol>] Required plugin options

suffix[RW]

@return [String, Regexp, Proc] The suffix

timers[R]

@return [Array<Timer>] All timers

Public Class Methods

extended(by) click to toggle source

@api private

# File lib/cinch/plugin.rb, line 111
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

Public Instance Methods

__hooks(type = nil, events = nil) click to toggle source

@return [Hash] @api private

# 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
call_hooks(type, event, instance, args) click to toggle source

@return [Boolean] True if processing should continue @api private

# 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
check_for_missing_options(bot) click to toggle source

@param [Bot] bot @return [Array<Symbol>, nil] @since 2.0.0 @api private

# 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
ctcp(command) click to toggle source

@version 1.1.1

# File lib/cinch/plugin.rb, line 217
def ctcp(command)
  @ctcps << command.to_s.upcase
end
hook(type, options = {}) click to toggle source

Defines a hook which will be run before or after a handler is executed, depending on the value of `type`.

@param [:pre, :post] type Run the hook before or after

a handler?

@option options [Array<:match, :listen_to, :ctcp>] :for ([:match, :listen_to, :ctcp])

Which kinds of events to run the hook for.

@option options [Symbol] :method (true) The method to execute. @return [Hook] @since 1.1.0

# 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
listen_to(*types) click to toggle source

Events to listen to. @overload listen_to(*types, options = {})

@param [String, Symbol, Integer] *types Events to listen to. Available
  events are all IRC commands in lowercase as symbols, all numeric
  replies and all events listed in the {file:docs/events.md list of events}.
@param [Hash] options
@option options [Symbol] :method (:listen) The method to
  execute
@return [Array<Listener>]
# 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
match(pattern, options = {}) click to toggle source

Set a match pattern.

@param [Regexp, String] pattern A pattern @option options [Symbol] :method (:execute) The method to execute @option options [Boolean] :use_prefix (true) If true, the

plugin prefix will automatically be prepended to the
pattern.

@option options [Boolean] :use_suffix (true) If true, the

plugin suffix will automatically be appended to the
pattern.

@option options [String, Regexp, Proc] prefix (nil) A prefix

overwriting the per-plugin prefix.

@option options [String, Regexp, Proc] suffix (nil) A suffix

overwriting the per-plugin suffix.

@option options [Symbol, Fixnum] react_on (:message) The

{file:docs/events.md event} to react on.

@option options [Symbol] :group (nil) The group the match belongs to. @return [Matcher] @todo Document match/listener grouping

# 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
plugin_name=(new_name) click to toggle source

@return [String]

# File lib/cinch/plugin.rb, line 43
def plugin_name=(new_name)
  if new_name.nil? && self.name
    @plugin_name = self.name.split("::").last.downcase
  else
    @plugin_name = new_name
  end
end
set(*args) click to toggle source

Set options.

Available options:

- {#help}
- {#plugin_name}
- {#prefix}
- {#react_on}
- {#required_options}
- {#suffix}

@overload set(key, value)

@param [Symbol] key The option's name
@param [Object] value
@return [void]

@overload set(options)

@param [Hash{Symbol => Object}] options The options, as key => value associations
@return [void]
@example
  set(:help   => "the help message",
      :prefix => "^")

@return [void] @since 2.0.0

# 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(interval, options = {}) click to toggle source

@example

timer 5, method: :some_method
def some_method
  Channel("#cinch-bots").send(Time.now.to_s)
end

@param [Numeric] interval Interval in seconds @option options [Symbol] :method (:timer) Method to call (only

if no proc is provided)

@option options [Integer] :shots (Float::INFINITY) How often

should the timer fire?

@option options [Boolean] :threaded (true) Call method in a

thread?

@option options [Boolean] :start_automatically (true) If true,

the timer will automatically start after the bot finished
connecting.

@option options [Boolean] :stop_automaticall (true) If true,

the timer will automatically stop when the bot disconnects.

@return [Timer] @since 1.1.0

# 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

[Validate]

Generated with the Darkfish Rdoc Generator 2.