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



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

def self.sanitize(string)
  string.gsub(/[\x00-\x08\x0a-\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



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

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

#debug(message) ⇒ void

This method returns an undefined value.

Logs a debugging message.

Parameters:

Version:

  • 2.0.0



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

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

#error(message) ⇒ void

This method returns an undefined value.

Logs an error message.

Parameters:

Since:

  • 2.0.0



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

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

#exception(e) ⇒ void

This method returns an undefined value.

Logs an exception.

Parameters:

  • e (Exception)

Since:

  • 2.0.0



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

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

#fatal(message) ⇒ void

This method returns an undefined value.

Logs a fatal message.

Parameters:

Since:

  • 2.0.0



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

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



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

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

#incoming(message) ⇒ void

This method returns an undefined value.

Logs an incoming IRC message.

Parameters:

Since:

  • 2.0.0



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

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

#info(message) ⇒ void

This method returns an undefined value.

Logs an info message.

Parameters:

Since:

  • 2.0.0



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

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

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

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



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

def log(messages, event = :debug, level = event)
  if is_a?(Cinch::Plugin)
    messages = Array(messages).map { |m|
      "[#{self.class}] " + m
    }
  end
  @bot.loggers.log(messages, event, level)
end

#outgoing(message) ⇒ void

This method returns an undefined value.

Logs an outgoing IRC message.

Parameters:

Since:

  • 2.0.0



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

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

#rescue_exception ⇒ void

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



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

def rescue_exception
  yield
rescue => e
  bot.loggers.exception(e)
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



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

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



24
25
26
27
 
# 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) ⇒ 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



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

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

  if 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



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

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



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

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) ⇒ void

This method returns an undefined value.

Logs a warning message.

Parameters:

Since:

  • 2.0.0



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

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