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 220 def self.sanitize(string) string.gsub(/[\x00-\x08\x0a-\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 39 def Channel(channel) return channel if channel.is_a?(Channel) bot.channel_list.find_ensured(channel) end
(see Formatting.format
)
# File lib/cinch/helpers.rb, line 183 def Format(*settings, string) Formatting.format(*settings, string) end
(see .sanitize)
# File lib/cinch/helpers.rb, line 195 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 24 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 97 def Timer(interval, options = {}, &block) options = { method: :timer, threaded: true, interval: interval }.merge(options) block ||= method(options[:method]) timer = Cinch::Timer.new(bot, options, &block) timer.start timers << timer if respond_to?(:timers) timer end
(see Formatting.unformat
)
# File lib/cinch/helpers.rb, line 225 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 55 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 Logger#debug
)
# File lib/cinch/helpers.rb, line 140 def debug(message) log(message, :debug) end
(see Logger#error
)
# File lib/cinch/helpers.rb, line 145 def error(message) log(message, :error) end
(see Logger#exception
)
# File lib/cinch/helpers.rb, line 175 def exception(e) log(e.message, :exception, :error) end
(see Logger#fatal
)
# File lib/cinch/helpers.rb, line 150 def fatal(message) log(message, :fatal) end
(see Logger#incoming
)
# File lib/cinch/helpers.rb, line 165 def incoming(message) log(message, :incoming, :log) end
(see Logger#info
)
# File lib/cinch/helpers.rb, line 155 def info(message) log(message, :info) end
(see Logger#log
)
# File lib/cinch/helpers.rb, line 130 def log(messages, event = :debug, level = event) if is_a?(Cinch::Plugin) messages = Array(messages).map do |m| "[#{self.class}] " + m end end @bot.loggers.log(messages, event, level) end
(see Logger#outgoing
)
# File lib/cinch/helpers.rb, line 170 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 123 def rescue_exception yield rescue StandardError => e bot.loggers.exception(e) end
(see Logger#warn
)
# File lib/cinch/helpers.rb, line 160 def warn(message) log(message, :warn) end