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

sanitize(string) click to toggle source

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

Channel(channel) click to toggle source

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
Color(*settings, string)
Alias for: Format
Format(*settings, string) click to toggle source

(see Formatting.format)

# File lib/cinch/helpers.rb, line 183
def Format(*settings, string)
  Formatting.format(*settings, string)
end
Also aliased as: Color
Sanitize(string) click to toggle source

(see .sanitize)

# File lib/cinch/helpers.rb, line 195
def Sanitize(string)
  Cinch::Helpers.sanitize(string)
end
Target(target) click to toggle source

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

@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
Unformat(string) click to toggle source

(see Formatting.unformat)

# File lib/cinch/helpers.rb, line 225
def Unformat(string)
  Formatting.unformat(string)
end
User(user) click to toggle source

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
debug(message) click to toggle source

(see Logger#debug)

# File lib/cinch/helpers.rb, line 140
def debug(message)
  log(message, :debug)
end
error(message) click to toggle source

(see Logger#error)

# File lib/cinch/helpers.rb, line 145
def error(message)
  log(message, :error)
end
exception(e) click to toggle source

(see Logger#exception)

# File lib/cinch/helpers.rb, line 175
def exception(e)
  log(e.message, :exception, :error)
end
fatal(message) click to toggle source

(see Logger#fatal)

# File lib/cinch/helpers.rb, line 150
def fatal(message)
  log(message, :fatal)
end
incoming(message) click to toggle source

(see Logger#incoming)

# File lib/cinch/helpers.rb, line 165
def incoming(message)
  log(message, :incoming, :log)
end
info(message) click to toggle source

(see Logger#info)

# File lib/cinch/helpers.rb, line 155
def info(message)
  log(message, :info)
end
log(messages, event = :debug, level = event) click to toggle source

(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
outgoing(message) click to toggle source

(see Logger#outgoing)

# File lib/cinch/helpers.rb, line 170
def outgoing(message)
  log(message, :outgoing, :log)
end
rescue_exception() { || ... } click to toggle source

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
warn(message) click to toggle source

(see Logger#warn)

# File lib/cinch/helpers.rb, line 160
def warn(message)
  log(message, :warn)
end