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:



329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
 
# File 'lib/cinch/bot.rb', line 329

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



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

def callback
  @callback
end

#channel_list ⇒ ChannelList (readonly)

Returns All channels the bot knows about.

Returns:

See Also:

Since:

  • 1.1.0



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

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



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

def channels
  @channels
end

#config ⇒ Configuration::Bot (readonly)

Returns:

Version:

  • 2.0.0



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

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



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

def handlers
  @handlers
end

#irc ⇒ IRC (readonly)

The underlying IRC connection

Returns:



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

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) 


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

def last_connection_was_successful
  @last_connection_was_successful
end

#loggers ⇒ LoggerList

The logger list containing all loggers

Returns:

Since:

  • 2.0.0



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

def loggers
  @loggers
end

#modes ⇒ Array<String>

The bot’s modes.

Returns:

Since:

  • 2.0.0



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

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



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

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



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

def quitting
  @quitting
end

#user_list ⇒ UserList (readonly)

Returns All users the bot knows about.

Returns:

See Also:

Since:

  • 1.1.0



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

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



356
357
358
359
 
# File 'lib/cinch/bot.rb', line 356

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



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

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



442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
 
# File 'lib/cinch/bot.rb', line 442

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 { ... }

This method returns an undefined value.

Define helper methods in the context of the bot.

Yields:

  • Expects a block containing method definitions



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

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

#inspect ⇒ String

Returns:



465
466
467
 
# File 'lib/cinch/bot.rb', line 465

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

#join(channel, key = nil) ⇒ Channel

Join a channel.

Parameters:

Returns:

See Also:



300
301
302
303
304
305
 
# File 'lib/cinch/bot.rb', line 300

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



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

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)

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



430
431
432
433
 
# File 'lib/cinch/bot.rb', line 430

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:



313
314
315
316
317
318
 
# File 'lib/cinch/bot.rb', line 313

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



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

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



368
369
370
371
 
# File 'lib/cinch/bot.rb', line 368

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:



399
400
401
 
# File 'lib/cinch/bot.rb', line 399

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?



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

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(&:unsync_all) # reset state of all channels

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

    @join_handler&.unregister
    @join_timer&.stop

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

    if @config.delay_joins.is_a?(Symbol)
      @join_handler = join_handler = on(@config.delay_joins) do
        join_handler.unregister
        join_lambda.call
      end
    else
      @join_timer = Timer.new(self, interval: @config.delay_joins, shots: 1) do
        join_lambda.call
      end
    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
      sleep 1 while !@quitting && (Time.now - start_time) < wait
    end
  end while @config.reconnect && !@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.



324
325
326
 
# File 'lib/cinch/bot.rb', line 324

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:



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

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



378
379
380
381
 
# File 'lib/cinch/bot.rb', line 378

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