Module: Cinch::Helpers

Included in:
Bot, Callback, Channel, IRC, Plugin, Timer
Defined in:
lib/cinch/helpers.rb

Overview

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.

Type casts collapse

Logging collapse

Formatting collapse

Class Method Details

.sanitize(string) ⇒ String

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.

Parameters:

  • string (String) —

    The string to filter

Returns:

  • (String) —

    The filtered string

Since:

  • 2.2.0



220
221
222
 
# File 'lib/cinch/helpers.rb', line 220

def self.sanitize(string)
  string.gsub(/[\x00-\x08\x10-\x1f\x7f]/, '')
end

Instance Method Details

#Channel(channel) ⇒ Channel

Helper method for turning a String into a #Channel object.

Examples:

on :message, /^please join (#.+)$/ do |m, target|
  Channel(target).join
end

Parameters:

  • channel (String) —

    a channel name

Returns:

Since:

  • 1.0.0



37
38
39
40
 
# File 'lib/cinch/helpers.rb', line 37

def Channel(channel)
  return channel if channel.is_a?(Channel)
  bot.channel_list.find_ensured(channel)
end

#debug(message)

This method returns an undefined value.

Logs a debugging message.

Parameters:

Version:

  • 2.0.0



140
141
142
 
# File 'lib/cinch/helpers.rb', line 140

def debug(message)
  log(message, :debug)
end

#error(message)

This method returns an undefined value.

Logs an error message.

Parameters:

Since:

  • 2.0.0



145
146
147
 
# File 'lib/cinch/helpers.rb', line 145

def error(message)
  log(message, :error)
end

#exception(e)

This method returns an undefined value.

Logs an exception.

Parameters:

  • e (Exception)

Since:

  • 2.0.0



175
176
177
 
# File 'lib/cinch/helpers.rb', line 175

def exception(e)
  log(e.message, :exception, :error)
end

#fatal(message)

This method returns an undefined value.

Logs a fatal message.

Parameters:

Since:

  • 2.0.0



150
151
152
 
# File 'lib/cinch/helpers.rb', line 150

def fatal(message)
  log(message, :fatal)
end

#Format(*settings, string) ⇒ String Also known as: Color

Returns the formatted string.

Examples:

Nested formatting, combining text styles and colors

reply = Format(:underline, "Hello %s! Is your favourite color %s?" % [Format(:bold, "stranger"), Format(:red, "red")])

Parameters:

  • settings (Array<Symbol>) —

    The colors and attributes to apply. When supplying two colors, the first will be used for the foreground and the second for the background.

  • string (String) —

    The string to format.

Returns:

  • (String) —

    the formatted string

Raises:

  • (ArgumentError) —

    When passing more than two colors as arguments.

See Also:

Since:

  • 2.0.0



183
184
185
 
# File 'lib/cinch/helpers.rb', line 183

def Format(*settings, string)
  Formatting.format(*settings, string)
end

#incoming(message)

This method returns an undefined value.

Logs an incoming IRC message.

Parameters:

Since:

  • 2.0.0



165
166
167
 
# File 'lib/cinch/helpers.rb', line 165

def incoming(message)
  log(message, :incoming, :log)
end

#info(message)

This method returns an undefined value.

Logs an info message.

Parameters:

Since:

  • 2.0.0



155
156
157
 
# File 'lib/cinch/helpers.rb', line 155

def info(message)
  log(message, :info)
end

#log(messages, event = :debug, level = event)

This method returns an undefined value.

Logs a message.

Parameters:

  • messages (String, Array) —

    The message(s) to log

  • event (:debug, :incoming, :outgoing, :info, :warn, :exception, :error, :fatal) (defaults to: :debug) —

    The kind of event that triggered the message

  • level (:debug, :info, :warn, :error, :fatal) (defaults to: event) —

    The level of the message

Version:

  • 2.0.0



130
131
132
133
134
135
136
137
 
# File 'lib/cinch/helpers.rb', line 130

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

#outgoing(message)

This method returns an undefined value.

Logs an outgoing IRC message.

Parameters:

Since:

  • 2.0.0



170
171
172
 
# File 'lib/cinch/helpers.rb', line 170

def outgoing(message)
  log(message, :outgoing, :log)
end

#rescue_exception

This method returns an undefined value.

Use this method to automatically log exceptions to the loggers.

Examples:

def my_method
  rescue_exception do
    something_that_might_raise()
  end
end

Since:

  • 2.0.0



121
122
123
124
125
126
127
 
# File 'lib/cinch/helpers.rb', line 121

def rescue_exception
  begin
    yield
  rescue => e
    bot.loggers.exception(e)
  end
end

#Sanitize(string) ⇒ String

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.

Parameters:

  • string (String) —

    The string to filter

Returns:

  • (String) —

    The filtered string

Since:

  • 2.2.0



195
196
197
 
# File 'lib/cinch/helpers.rb', line 195

def Sanitize(string)
  Cinch::Helpers.sanitize(string)
end

#Target(target) ⇒ Target

Helper method for turning a String into a #Target object.

Examples:

on :message, /^message (.+)$/ do |m, target|
  Target(target).send "hi!"
end

Parameters:

  • target (String) —

    a target name

Returns:

Since:

  • 2.0.0



23
24
25
26
 
# File 'lib/cinch/helpers.rb', line 23

def Target(target)
  return target if target.is_a?(Target)
  Target.new(target, bot)
end

#Timer(interval, options = {}, &block) ⇒ Timer

Examples:

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

Used as an instance method in a plugin

match "start timer"
def execute(m)
  Timer(5) { puts "timer fired" }
end

Used as an instance method in a traditional on handler

on :message, "start timer" do
  Timer(5) { puts "timer fired" }
end

Parameters:

  • interval (Numeric) —

    Interval in seconds

  • block (Proc) —

    A proc to execute

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :method (Symbol) — default: :timer —

    Method to call (only if no proc is provided)

  • :threaded (Boolean) — default: true —

    Call method in a thread?

  • :shots (Integer) — default: Float::INFINITY —

    How often should the timer fire?

  • :start_automatically (Boolean) — default: true —

    If true, the timer will automatically start after the bot finished connecting.

  • :stop_automaticall (Boolean) — default: true —

    If true, the timer will automatically stop when the bot disconnects.

Returns:

Since:

  • 2.0.0



93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/cinch/helpers.rb', line 93

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

#Unformat(string) ⇒ String

Deletes all mIRC formatting codes from the string. This strips formatting for bold, underline and so on, as well as color codes. This does include removing the numeric arguments.

Parameters:

  • string (String) —

    The string to filter

Returns:

  • (String) —

    The filtered string

Since:

  • 2.2.0



225
226
227
 
# File 'lib/cinch/helpers.rb', line 225

def Unformat(string)
  Formatting.unformat(string)
end

#User(user) ⇒ User

Helper method for turning a String into an #User object.

Examples:

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

Parameters:

  • user (String) —

    a user’s nickname

Returns:

Since:

  • 1.0.0



52
53
54
55
56
57
58
59
 
# File 'lib/cinch/helpers.rb', line 52

def User(user)
  return user if user.is_a?(User)
  if user == bot.nick
    bot
  else
    bot.user_list.find_ensured(user)
  end
end

#warn(message)

This method returns an undefined value.

Logs a warning message.

Parameters:

Since:

  • 2.0.0



160
161
162
 
# File 'lib/cinch/helpers.rb', line 160

def warn(message)
  log(message, :warn)
end