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)

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



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

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

- debug(message)

Logs a debugging message.

Parameters:

Returns:

  • (void)
  • (void)

Version:

  • 2.0.0

  • 2.0.0



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

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

- error(message)

Logs an error message.

Parameters:

Returns:

  • (void)
  • (void)

Since:

  • 2.0.0

  • 2.0.0



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

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

- exception(e)

Logs an exception.

Parameters:

  • e (Exception)
  • e (Exception)

Returns:

  • (void)
  • (void)

Since:

  • 2.0.0

  • 2.0.0



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

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

- fatal(message)

Logs a fatal message.

Parameters:

Returns:

  • (void)
  • (void)

Since:

  • 2.0.0

  • 2.0.0



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

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

- (String) Format(*args) Also known as: Color

Examples:

Nested formatting, combining text styles and colors

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

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.

  • *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

  • (String) —

    The formatted string

Raises:

  • (ArgumentError) —

    When passing more than two colors as arguments.

  • (ArgumentError) —

    When passing more than two colors as arguments.

See Also:

Since:

  • 2.0.0

  • 2.0.0



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

def Format(*args)
  Formatting.format(*args)
end

- incoming(message)

Logs an incoming IRC message.

Parameters:

Returns:

  • (void)
  • (void)

Since:

  • 2.0.0

  • 2.0.0



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

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

- info(message)

Logs an info message.

Parameters:

Returns:

  • (void)
  • (void)

Since:

  • 2.0.0

  • 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)

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

  • 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

Returns:

  • (void)
  • (void)

Version:

  • 2.0.0

  • 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 self.is_a?(Cinch::Plugin)
    messages = Array(messages).map {|m|
      "[#{self.class}] " + m
    }
  end
  @bot.loggers.log(messages, event, level)
end

- outgoing(message)

Logs an outgoing IRC message.

Parameters:

Returns:

  • (void)
  • (void)

Since:

  • 2.0.0

  • 2.0.0



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

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



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

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



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

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

- (Timer) Timer(interval, options = {}, &block)

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



92
93
94
95
96
97
98
99
100
101
102
103
 
# 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

- (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



51
52
53
54
55
56
57
58
 
# 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

- warn(message)

Logs a warning message.

Parameters:

Returns:

  • (void)
  • (void)

Since:

  • 2.0.0

  • 2.0.0



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

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