module Cinch::Helpers
The Helpers module contains a number of methods whose purpose is to make writing plugins easier by hiding parts of the API. The {#Channel} helper, for example, provides an easier way for turning a String object into a {Channel} object than directly using {ChannelList}: Compare `Channel(“#some_channel”)` with `bot.channel_list.find_ensured(“#some_channel”)`.
The Helpers module automatically gets included in all plugins.
Public Class Methods
Deletes all characters in the ranges 0–8, 10–31 as well as the character 127, that is all non-printable characters and newlines.
This method is useful for filtering text from external sources before sending it to IRC.
Note that this method does not gracefully handle mIRC color codes, because it will leave the numeric arguments behind. If your text comes from IRC, you may want to filter it through {#Unformat} first. If you want to send sanitized input that includes your own formatting, first use this method, then add your formatting.
There exist methods for sending messages that automatically call this method, namely {Target#safe_msg}, {Target#safe_notice}, and {Target#safe_action}.
@param [String] string The string to filter @return [String] The filtered string @since 2.2.0
# File lib/cinch/helpers.rb, line 219 def self.sanitize(string) string.gsub(/[\x00-\x08\x10-\x1f\x7f]/, '') end
Public Instance Methods
Helper method for turning a String into a {Channel} object.
@param [String] channel a channel name @return [Channel] a {Channel} object @example
on :message, /^please join (#.+)$/ do |m, target| Channel(target).join end
@since 1.0.0
# File lib/cinch/helpers.rb, line 36 def Channel(channel) return channel if channel.is_a?(Channel) bot.channel_list.find_ensured(channel) end
(see Cinch::Formatting.format)
# File lib/cinch/helpers.rb, line 182 def Format(*settings, string) Formatting.format(*settings, string) end
(see .sanitize)
# File lib/cinch/helpers.rb, line 194 def Sanitize(string) Cinch::Helpers.sanitize(string) end
Helper method for turning a String into a {Target} object.
@param [String] target a target name @return [Target] a {Target} object @example
on :message, /^message (.+)$/ do |m, target| Target(target).send "hi!" end
@since 2.0.0
# File lib/cinch/helpers.rb, line 22 def Target(target) return target if target.is_a?(Target) Target.new(target, bot) end
@example Used as a class method in a plugin
timer 5, method: :some_method def some_method Channel("#cinch-bots").send(Time.now.to_s) end
@example Used as an instance method in a plugin
match "start timer" def execute(m) Timer(5) { puts "timer fired" } end
@example Used as an instance method in a traditional `on` handler
on :message, "start timer" do Timer(5) { puts "timer fired" } end
@param [Numeric] interval Interval in seconds @param [Proc] block A proc to execute @option options [Symbol] :method (:timer) Method to call (only
if no proc is provided)
@option options [Boolean] :threaded (true) Call method in a
thread?
@option options [Integer] :shots (Float::INFINITY) How often
should the timer fire?
@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 2.0.0
# File lib/cinch/helpers.rb, line 92 def Timer(interval, options = {}, &block) options = {:method => :timer, :threaded => true, :interval => interval}.merge(options) block ||= self.method(options[:method]) timer = Cinch::Timer.new(bot, options, &block) timer.start if self.respond_to?(:timers) timers << timer end timer end
(see Cinch::Formatting.unformat)
# File lib/cinch/helpers.rb, line 224 def Unformat(string) Formatting.unformat(string) end
Helper method for turning a String into an {User} object.
@param [String] user a user's nickname @return [User] an {User} object @example
on :message, /^tell me everything about (.+)$/ do |m, target| user = User(target) m.reply "%s is named %s and connects from %s" % [user.nick, user.name, user.host] end
@since 1.0.0
# File lib/cinch/helpers.rb, line 51 def User(user) return user if user.is_a?(User) if user == bot.nick bot else bot.user_list.find_ensured(user) end end
(see Cinch::Logger#debug)
# File lib/cinch/helpers.rb, line 139 def debug(message) log(message, :debug) end
(see Cinch::Logger#error)
# File lib/cinch/helpers.rb, line 144 def error(message) log(message, :error) end
(see Cinch::Logger#exception)
# File lib/cinch/helpers.rb, line 174 def exception(e) log(e.message, :exception, :error) end
(see Cinch::Logger#fatal)
# File lib/cinch/helpers.rb, line 149 def fatal(message) log(message, :fatal) end
(see Cinch::Logger#incoming)
# File lib/cinch/helpers.rb, line 164 def incoming(message) log(message, :incoming, :log) end
(see Cinch::Logger#info)
# File lib/cinch/helpers.rb, line 154 def info(message) log(message, :info) end
(see Cinch::Logger#log)
# File lib/cinch/helpers.rb, line 129 def log(messages, event = :debug, level = event) if self.is_a?(Cinch::Plugin) messages = Array(messages).map {|m| "[#{self.class}] " + m } end @bot.loggers.log(messages, event, level) end
(see Cinch::Logger#outgoing)
# File lib/cinch/helpers.rb, line 169 def outgoing(message) log(message, :outgoing, :log) end
Use this method to automatically log exceptions to the loggers.
@example
def my_method rescue_exception do something_that_might_raise() end end
@return [void] @since 2.0.0
# File lib/cinch/helpers.rb, line 120 def rescue_exception begin yield rescue => e bot.loggers.exception(e) end end
(see Cinch::Logger#warn)
# File lib/cinch/helpers.rb, line 159 def warn(message) log(message, :warn) end