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?, #dcc_send, #end_of_whois, #mask, #match, #monitor, #refresh, #to_s, #unmonitor, #unsync_all, #update_nick

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:



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

def initialize(&b)
  @loggers = LoggerList.new
  @loggers << Logger::FormattedLogger.new($stderr)

  @config           = Configuration::Bot.new
  @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 block_given?
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:



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

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



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

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

#configure {|config| ... }

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



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

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
      if nicks[new_index]
        new_nick = nicks[new_index]
      else
        new_nick = base + "_"
      end
    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 { ... }

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:



475
476
477
 
# File 'lib/cinch/bot.rb', line 475

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

#join(channel, key = nil) ⇒ Channel

Join a channel.

Parameters:

Returns:

See Also:



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

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)

  return handler
end

#oper(password, user = nil)

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



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

def oper(password, user = nil)
  user ||= self.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:



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

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

  channel
end

#quit(message = nil)

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)

This method returns an undefined value.

Sets a mode on the bot.

Parameters:

See Also:

Since:

  • 2.0.0



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

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:



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

def set_nick(nick)
  @name = nick
end

#start(plugins = true)

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
 
# File 'lib/cinch/bot.rb', line 237

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

  begin
    @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 if @join_handler
    @join_timer.stop if @join_timer

    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
  end while @config.reconnect and not @quitting
end

#strict? ⇒ Boolean

Returns True if the bot reports ISUPPORT violations as exceptions.

Returns:

  • (Boolean) —

    True if the bot reports ISUPPORT violations as exceptions.



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

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

#synchronize(name) { ... }

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)

This method returns an undefined value.

Unsets a mode on the bot.

Parameters:

Since:

  • 2.0.0



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

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