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
Represents a Hook as created by {hook}.
@attr [Symbol] type @attr [Array<Symbol>] for @attr [Symbol] method
Represents a Listener as created by {listen_to}.
@attr [Symbol] event @attr [Symbol] method
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
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
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
@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
@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
@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
@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
@version 1.1.1
# File lib/cinch/plugin.rb, line 217 def ctcp(command) @ctcps << command.to_s.upcase end
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
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
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
@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 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
@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
Generated with the Darkfish Rdoc Generator 2.