Class: Cinch::Bot

Inherits:
User show all
Includes:
Helpers
Defined in:
lib/cinch/bot.rb

Overview

Version:

  • 2.0.0

Instance Attribute Summary collapse

Attributes inherited from User

#authname, #away, #data, #host, #idle, #in_whois, #last_nick, #monitored, #online, #realname, #secure, #signed_on_at, #synced, #unknown, #user

Attributes inherited from Target

#name

Helper methods collapse

Events & Plugins collapse

Bot Control collapse

Channel Control collapse

Instance Method Summary collapse

Methods included from Helpers

#Channel, #Format, #Sanitize, #Target, #Timer, #Unformat, #User, #debug, #error, #exception, #fatal, #incoming, #info, #log, #outgoing, #rescue_exception, sanitize, #warn

Methods inherited from User

#attr, #authed?, #authname_unsynced, #channels_unsynced, #dcc_send, #end_of_whois, #host_unsynced, #idle_unsynced, #mask, #match, #monitor, #online_unsynced, #oper_unsynced, #realname_unsynced, #refresh, #secure_unsynced, #signed_on_at_unsynced, #to_s, #unknown_unsynced, #unmonitor, #unsync_all, #update_nick, #user_unsynced

Methods included from Syncable

#attr, #attribute_synced?, #mark_as_synced, #sync, #unsync, #unsync_all, #wait_until_synced

Methods inherited from Target

#<=>, #action, #concretize, #ctcp, #eql?, #notice, #safe_action, #safe_notice, #safe_privmsg, #safe_send, #send

Constructor Details

#initialize { ... } ⇒ Bot

Returns a new instance of Bot.

Yields:



335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
 
# File 'lib/cinch/bot.rb', line 335

def initialize(&b)
  @config = Configuration::Bot.new

  @loggers = LoggerList.new
  @loggers << Logger::FormattedLogger.new($stderr, level: @config.default_logger_level)
  @handlers = HandlerList.new
  @semaphores_mutex = Mutex.new
  @semaphores = Hash.new { |h, k| h[k] = Mutex.new }
  @callback = Callback.new(self)
  @channels = []
  @quitting = false
  @modes = []

  @user_list = UserList.new(self)
  @channel_list = ChannelList.new(self)
  @plugins = PluginList.new(self)

  @join_handler = nil
  @join_timer = nil

  super(nil, self)
  instance_eval(&b) if b
end

Instance Attribute Details

#callback ⇒ Callback (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:



102
103
104
 
# File 'lib/cinch/bot.rb', line 102

def callback
  @callback
end

#channel_list ⇒ ChannelList (readonly)

Returns All channels the bot knows about.

Returns:

See Also:

Since:

  • 1.1.0



94
95
96
 
# File 'lib/cinch/bot.rb', line 94

def channel_list
  @channel_list
end

#channels ⇒ Array<Channel> (readonly)

Returns All channels the bot currently is in.

Returns:

  • (Array<Channel>) —

    All channels the bot currently is in



76
77
78
 
# File 'lib/cinch/bot.rb', line 76

def channels
  @channels
end

#config ⇒ Configuration::Bot (readonly)

Returns:

Version:

  • 2.0.0



62
63
64
 
# File 'lib/cinch/bot.rb', line 62

def config
  @config
end

#handlers ⇒ HandlerList (readonly)

The HandlerList, providing access to all registered plugins and plugin manipulation as well as calling handlers.

Returns:

See Also:

Since:

  • 2.0.0



110
111
112
 
# File 'lib/cinch/bot.rb', line 110

def handlers
  @handlers
end

#irc ⇒ IRC (readonly)

The underlying IRC connection

Returns:



67
68
69
 
# File 'lib/cinch/bot.rb', line 67

def irc
  @irc
end

#last_connection_was_successful ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (Boolean) 


98
99
100
 
# File 'lib/cinch/bot.rb', line 98

def last_connection_was_successful
  @last_connection_was_successful
end

#loggers ⇒ LoggerList

The logger list containing all loggers

Returns:

Since:

  • 2.0.0



73
74
75
 
# File 'lib/cinch/bot.rb', line 73

def loggers
  @loggers
end

#modes ⇒ Array<String>

The bot’s modes.

Returns:

Since:

  • 2.0.0



116
117
118
 
# File 'lib/cinch/bot.rb', line 116

def modes
  @modes
end

#nick=(new_nick) ⇒ String #nick ⇒ String

The bot’s nickname.

Overloads:

Returns:



57
58
59
 
# File 'lib/cinch/bot.rb', line 57

def nick
  @nick
end

#plugins ⇒ PluginList (readonly)

Returns The PluginList giving access to (un)loading plugins.

Returns:

Version:

  • 2.0.0



81
82
83
 
# File 'lib/cinch/bot.rb', line 81

def plugins
  @plugins
end

#quitting ⇒ Boolean (readonly)

Returns whether the bot is in the process of disconnecting.

Returns:

  • (Boolean) —

    whether the bot is in the process of disconnecting



84
85
86
 
# File 'lib/cinch/bot.rb', line 84

def quitting
  @quitting
end

#user_list ⇒ UserList (readonly)

Returns All users the bot knows about.

Returns:

See Also:

Since:

  • 1.1.0



89
90
91
 
# File 'lib/cinch/bot.rb', line 89

def user_list
  @user_list
end

Instance Method Details

#bot ⇒ self

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (self)

Since:

  • 2.0.0



362
363
364
365
 
# File 'lib/cinch/bot.rb', line 362

def bot
  # This method is needed for the Helpers interface
  self
end

#configure {|config| ... } ⇒ void

This method returns an undefined value.

This method is used to set a bot’s options. It indeed does nothing else but yielding #config, but it makes for a nice DSL.

Yield Parameters:

  • config (Struct) —

    the bot’s config



217
218
219
 
# File 'lib/cinch/bot.rb', line 217

def configure
  yield @config
end

#generate_next_nick!(base = nil) ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Try to create a free nick, first by cycling through all available alternatives and then by appending underscores.

Parameters:

  • base (String) (defaults to: nil) —

    The base nick to start trying from

Returns:

Since:

  • 2.0.0



449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
 
# File 'lib/cinch/bot.rb', line 449

def generate_next_nick!(base = nil)
  nicks = @config.nicks || []

  if base
    # if `base` is not in our list of nicks to try, assume that it's
    # custom and just append an underscore
    if !nicks.include?(base)
      new_nick = base + "_"
    else
      # if we have a base, try the next nick or append an
      # underscore if no more nicks are left
      new_index = nicks.index(base) + 1
      new_nick = nicks[new_index] || base + "_"
    end
  else
    # if we have no base, try the first possible nick
    new_nick = @config.nicks ? @config.nicks.first : @config.nick
  end

  @config.nick = new_nick
end

#helpers { ... } ⇒ void

This method returns an undefined value.

Define helper methods in the context of the bot.

Yields:

  • Expects a block containing method definitions



124
125
126
 
# File 'lib/cinch/bot.rb', line 124

def helpers(&b)
  @callback.instance_eval(&b)
end

#inspect ⇒ String

Returns:



472
473
474
 
# File 'lib/cinch/bot.rb', line 472

def inspect
  "#<Bot nick=#{@name.inspect}>"
end

#join(channel, key = nil) ⇒ Channel

Join a channel.

Parameters:

Returns:

See Also:



306
307
308
309
310
311
 
# File 'lib/cinch/bot.rb', line 306

def join(channel, key = nil)
  channel = Channel(channel)
  channel.join(key)

  channel
end

#on(event, regexp = //, *args) {|args| ... } ⇒ Handler

Registers a handler.

Parameters:

  • event (String, Symbol, Integer) —

    the event to match. For a list of available events, check the Events documentation.

  • regexp (Regexp, Pattern, String) (defaults to: //) —

    every message of the right event will be checked against this argument and the event will only be called if it matches

  • args (Array<Object>) —

    Arguments that should be passed to the block, additionally to capture groups of the regexp.

Yield Parameters:

  • args (Array<String>) —

    each capture group of the regex will be one argument to the block.

Returns:

  • (Handler) —

    The handlers that have been registered



187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
 
# File 'lib/cinch/bot.rb', line 187

def on(event, regexp = //, *args, &block)
  event = event.to_s.to_sym

  pattern = case regexp
  when Pattern
    regexp
  when Regexp
    Pattern.new(nil, regexp, nil)
  else
    if event == :ctcp
      Pattern.generate(:ctcp, regexp)
    else
      Pattern.new(/^/, /#{Regexp.escape(regexp.to_s)}/, /$/)
    end
  end

  handler = Handler.new(self, event, pattern, {args: args, execute_in_callback: true}, &block)
  @handlers.register(handler)

  handler
end

#oper(password, user = nil) ⇒ void

This method returns an undefined value.

Gain oper privileges.

Parameters:

  • password (String)
  • user (String) (defaults to: nil) —

    The username to use. Defaults to the bot’s nickname

Since:

  • 2.1.0



437
438
439
440
 
# File 'lib/cinch/bot.rb', line 437

def oper(password, user = nil)
  user ||= nick
  @irc.send "OPER #{user} #{password}"
end

#part(channel, reason = nil) ⇒ Channel

Part a channel.

Parameters:

Returns:

  • (Channel) —

    The channel that was left

See Also:



319
320
321
322
323
324
 
# File 'lib/cinch/bot.rb', line 319

def part(channel, reason = nil)
  channel = Channel(channel)
  channel.part(reason)

  channel
end

#quit(message = nil) ⇒ void

This method returns an undefined value.

Disconnects from the server.

Parameters:

  • message (String) (defaults to: nil) —

    The quit message to send while quitting



225
226
227
228
229
230
 
# File 'lib/cinch/bot.rb', line 225

def quit(message = nil)
  @quitting = true
  command = message ? "QUIT :#{message}" : "QUIT"

  @irc.send command
end

#set_mode(mode) ⇒ void

This method returns an undefined value.

Sets a mode on the bot.

Parameters:

See Also:

Since:

  • 2.0.0



374
375
376
377
 
# File 'lib/cinch/bot.rb', line 374

def set_mode(mode)
  @modes << mode unless @modes.include?(mode)
  @irc.send "MODE #{nick} +#{mode}"
end

#set_nick(nick) ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Used for updating the bot’s nick from within the IRC parser.

Parameters:

Returns:



405
406
407
 
# File 'lib/cinch/bot.rb', line 405

def set_nick(nick)
  @name = nick
end

#start(plugins = true) ⇒ void

This method returns an undefined value.

Connects the bot to a server.

Parameters:

  • plugins (Boolean) (defaults to: true) —

    Automatically register plugins from ‘@config.plugins.plugins`?



237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
 
# File 'lib/cinch/bot.rb', line 237

def start(plugins = true)
  @reconnects = 0
  @plugins.register_plugins(@config.plugins.plugins) if plugins

  loop do
    @user_list.each do |user|
      user.in_whois = false
      user.unsync_all
    end # reset state of all users

    @channel_list.each do |channel|
      channel.unsync_all
    end # reset state of all channels

    @channels = [] # reset list of channels the bot is in

    @join_handler&.unregister
    @join_timer&.stop

    join_lambda = lambda { @config.channels.each { |channel| Channel(channel).join } }

    if @config.delay_joins.is_a?(Symbol)
      @join_handler = join_handler = on(@config.delay_joins) {
        join_handler.unregister
        join_lambda.call
      }
    else
      @join_timer = Timer.new(self, interval: @config.delay_joins, shots: 1) {
        join_lambda.call
      }
    end

    @modes = []

    @loggers.info "Connecting to #{@config.server}:#{@config.port}"
    @irc = IRC.new(self)
    @irc.start

    if @config.reconnect && !@quitting
      # double the delay for each unsuccesful reconnection attempt
      if @last_connection_was_successful
        @reconnects = 0
        @last_connection_was_successful = false
      else
        @reconnects += 1
      end

      # Throttle reconnect attempts
      wait = 2**@reconnects
      wait = @config.max_reconnect_delay if wait > @config.max_reconnect_delay
      @loggers.info "Waiting #{wait} seconds before reconnecting"
      start_time = Time.now
      while !@quitting && (Time.now - start_time) < wait
        sleep 1
      end
    end
    break unless @config.reconnect && !@quitting
  end
end

#strict? ⇒ Boolean

Returns True if the bot reports ISUPPORT violations as exceptions.

Returns:

  • (Boolean) —

    True if the bot reports ISUPPORT violations as exceptions.



330
331
332
 
# File 'lib/cinch/bot.rb', line 330

def strict?
  @config.strictness == :strict
end

#synchronize(name) { ... } ⇒ void

This method returns an undefined value.

Since Cinch uses threads, all handlers can be run simultaneously, even the same handler multiple times. This also means, that your code has to be thread-safe. Most of the time, this is not a problem, but if you are accessing stored data, you will most likely have to synchronize access to it. Instead of managing all mutexes yourself, Cinch provides a synchronize method, which takes a name and block.

Synchronize blocks with the same name share the same mutex, which means that only one of them will be executed at a time.

Examples:

configure do |c|
  …
  @i = 0
end

on :channel, /^start counting!/ do
  synchronize(:my_counter) do
    10.times do
      val = @i
      # at this point, another thread might've incremented :i already.
      # this thread wouldn't know about it, though.
      @i = val + 1
    end
  end
end

Parameters:

  • name (String, Symbol) —

    a name for the synchronize block.

Yields:



159
160
161
162
163
164
 
# File 'lib/cinch/bot.rb', line 159

def synchronize(name, &block)
  # Must run the default block +/ fetch in a thread safe way in order to
  # ensure we always get the same mutex for a given name.
  semaphore = @semaphores_mutex.synchronize { @semaphores[name] }
  semaphore.synchronize(&block)
end

#unset_mode(mode) ⇒ void

This method returns an undefined value.

Unsets a mode on the bot.

Parameters:

Since:

  • 2.0.0



384
385
386
387
 
# File 'lib/cinch/bot.rb', line 384

def unset_mode(mode)
  @modes.delete(mode)
  @irc.send "MODE #{nick} -#{mode}"
end