Class: Cinch::Bot

Inherits:

User

Object
Target
User
Cinch::Bot

show all

Includes:

Helpers

Defined in:

lib/cinch/bot.rb

Overview

Version:

2.0.0

Instance Attribute Summary (collapse)

- (Callback) callback readonly private
- (ChannelList) channel_list readonly
All channels the bot knows about.
- (Array<Channel>) channels readonly
All channels the bot currently is in.
- (Configuration::Bot) config readonly
- (HandlerList) handlers readonly
The HandlerList, providing access to all registered plugins and plugin manipulation as well as calling handlers.
- (IRC) irc readonly
The underlying IRC connection.
- (Boolean) last_connection_was_successful private
- (LoggerList) loggers
The logger list containing all loggers.
- (Array<String>) modes
The bot’s modes.
- (String) nick
The bot’s nickname.
- (PluginList) plugins readonly
The PluginList giving access to (un)loading plugins.
- (Boolean) quitting readonly
Whether the bot is in the process of disconnecting.
- (UserList) user_list readonly
All users the bot knows about.

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)

- helpers { ... }
Define helper methods in the context of the bot.
- synchronize(name) { ... }
Since Cinch uses threads, all handlers can be run simultaneously, even the same handler multiple times.

Events & Plugins (collapse)

- (Handler) on(event, regexp = //, *args) {|*args| ... }
Registers a handler.

Bot Control (collapse)

- configure {|config| ... }
This method is used to set a bot’s options.
- quit(message = nil)
Disconnects from the server.
- start(plugins = true)
Connects the bot to a server.
- (Object) stop

Channel Control (collapse)

- (Channel) join(channel, key = nil)
Join a channel.
- (Channel) part(channel, reason = nil)
Part a channel.

Instance Method Summary (collapse)

- (self) bot private
- (String) generate_next_nick!(base = nil) private
Try to create a free nick, first by cycling through all available alternatives and then by appending underscores.
- (Bot) initialize { ... } constructor
A new instance of Bot.
- (String) inspect
- oper(password, user = nil)
Gain oper privileges.
- set_mode(mode)
Sets a mode on the bot.
- (String) set_nick(nick) private
Used for updating the bot’s nick from within the IRC parser.
- (Boolean) strict?
True if the bot reports ISUPPORT violations as exceptions.
- unset_mode(mode)
Unsets a mode on the bot.

Constructor Details

- (`Bot`) initialize { ... }

A new instance of Bot

Yields:

# File 'lib/cinch/bot.rb', line 340

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:

(Callback)



103
104
105

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

def callback
  @callback
end

- (`ChannelList`) channel_list (readonly)

All channels the bot knows about.

Returns:

(ChannelList) —
All channels the bot knows about.

See Also:

ChannelList

Since:

1.1.0



95
96
97

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

def channel_list
  @channel_list
end

- (`Array<Channel>`) channels (readonly)

All channels the bot currently is in

Returns:

(Array<Channel>) —
All channels the bot currently is in



77
78
79

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

def channels
  @channels
end

- (`Configuration::Bot`) config (readonly)

Returns:

(Configuration::Bot)

Version:

2.0.0



63
64
65

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

def config
  @config
end

- (`HandlerList`) handlers (readonly)

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

Returns:

(HandlerList)

See Also:

HandlerList

Since:

2.0.0



111
112
113

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

def handlers
  @handlers
end

- (`IRC`) irc (readonly)

The underlying IRC connection

Returns:

(IRC)



68
69
70

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

def irc
  @irc
end

- (`Boolean`) last_connection_was_successful

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)



99
100
101

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

def last_connection_was_successful
  @last_connection_was_successful
end

- (`LoggerList`) loggers

The logger list containing all loggers

Returns:

(LoggerList)

Since:

2.0.0



74
75
76

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

def loggers
  @loggers
end

- (`Array<String>`) modes

The bot’s modes.

Returns:

(Array<String>)

Since:

2.0.0



117
118
119

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

def modes
  @modes
end

- (`String`) nick=(new_nick) - (`String`) nick

The bot’s nickname.

Overloads:

- (String) nick=(new_nick)
Returns:
- (String)
Raises:
- (Exceptions::NickTooLong) —
  Raised if the bot is operating in strict mode and the new nickname is too long
- (String) nick
Returns:
- (String)

Returns:

(String)



57
58
59

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

def nick
  @nick
end

- (`PluginList`) plugins (readonly)

The PluginList giving access to (un)loading plugins

Returns:

(PluginList) —
The PluginList giving access to (un)loading plugins

Version:

2.0.0



82
83
84

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

def plugins
  @plugins
end

- (`Boolean`) quitting (readonly)

Whether the bot is in the process of disconnecting

Returns:

(Boolean) —
whether the bot is in the process of disconnecting



85
86
87

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

def quitting
  @quitting
end

- (`UserList`) user_list (readonly)

All users the bot knows about.

Returns:

(UserList) —
All users the bot knows about.

See Also:

UserList

Since:

1.1.0



90
91
92

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

def user_list
  @user_list
end

Instance Method Details

- (`self`) bot

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

# File 'lib/cinch/bot.rb', line 367

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



218
219
220

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

def configure
  yield @config
end

- (`String`) generate_next_nick!(base = nil)

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:

(String)

Since:

2.0.0

# File 'lib/cinch/bot.rb', line 454

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



125
126
127

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

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

- (`String`) inspect

Returns:

(String)



481
482
483

# File 'lib/cinch/bot.rb', line 481

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

- (`Channel`) join(channel, key = nil)

Join a channel.

Parameters:

channel (String, Channel) —
either the name of a channel or a Channel object
key (String) (defaults to: nil) —
optionally the key of the channel

Returns:

(Channel) —
The joined channel

See Also:

Channel#join

# File 'lib/cinch/bot.rb', line 311

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

  channel
end

- (`Handler`) on(event, regexp = //, args) {|args| ... }

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 (String) —
each capture group of the regex will be one argument to the block.

Returns:

(Handler) —
The handlers that have been registered

# File 'lib/cinch/bot.rb', line 188

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

# File 'lib/cinch/bot.rb', line 442

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

- (`Channel`) part(channel, reason = nil)

Part a channel.

Parameters:

channel (String, Channel) —
either the name of a channel or a Channel object
reason (String) (defaults to: nil) —
an optional reason/part message

Returns:

(Channel) —
The channel that was left

See Also:

Channel#part

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

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

# File 'lib/cinch/bot.rb', line 226

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:

mode (String)

See Also:

Since:

2.0.0

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

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

- (`String`) set_nick(nick)

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:

nick (String)

Returns:

(String)



410
411
412

# File 'lib/cinch/bot.rb', line 410

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?

# File 'lib/cinch/bot.rb', line 238

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

    @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

- (`Object`) stop

# File 'lib/cinch/bot.rb', line 295

def stop
  # @plugins.each do |plugin|
  #   plugin.storage.save
  #   plugin.storage.unload
  # end
end

- (`Boolean`) strict?

True if the bot reports ISUPPORT violations as exceptions.

Returns:

(Boolean) —
True if the bot reports ISUPPORT violations as exceptions.



335
336
337

# File 'lib/cinch/bot.rb', line 335

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:

# File 'lib/cinch/bot.rb', line 160

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:

mode (String)

Since:

2.0.0

# File 'lib/cinch/bot.rb', line 389

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

Class: Cinch::Bot

Overview

Instance Attribute Summary (collapse)

Attributes inherited from User

Attributes inherited from Target

Helper methods (collapse)

Events & Plugins (collapse)

Bot Control (collapse)

Channel Control (collapse)

Instance Method Summary (collapse)

Methods included from Helpers

Methods inherited from User

Methods included from Syncable

Methods inherited from Target

Constructor Details

- (Bot) initialize { ... }

Instance Attribute Details

- (Callback) callback (readonly)

- (ChannelList) channel_list (readonly)

- (Array<Channel>) channels (readonly)

- (Configuration::Bot) config (readonly)

- (HandlerList) handlers (readonly)

- (IRC) irc (readonly)

- (Boolean) last_connection_was_successful

- (LoggerList) loggers

- (Array<String>) modes

- (String) nick=(new_nick) - (String) nick

- (PluginList) plugins (readonly)

- (Boolean) quitting (readonly)

- (UserList) user_list (readonly)

Instance Method Details

- (self) bot

- configure {|config| ... }

- (String) generate_next_nick!(base = nil)

- helpers { ... }

- (String) inspect

- (Channel) join(channel, key = nil)

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

- oper(password, user = nil)

- (Channel) part(channel, reason = nil)

- quit(message = nil)

- set_mode(mode)

- (String) set_nick(nick)

- start(plugins = true)

- (Object) stop

- (Boolean) strict?

- synchronize(name) { ... }

- unset_mode(mode)

- (`Bot`) initialize { ... }

- (`Callback`) callback (readonly)

- (`ChannelList`) channel_list (readonly)

- (`Array<Channel>`) channels (readonly)

- (`Configuration::Bot`) config (readonly)

- (`HandlerList`) handlers (readonly)

- (`IRC`) irc (readonly)

- (`Boolean`) last_connection_was_successful

- (`LoggerList`) loggers

- (`Array<String>`) modes

- (`String`) nick=(new_nick) - (`String`) nick

- (`PluginList`) plugins (readonly)

- (`Boolean`) quitting (readonly)

- (`UserList`) user_list (readonly)

- (`self`) bot

- (`String`) generate_next_nick!(base = nil)

- (`String`) inspect

- (`Channel`) join(channel, key = nil)

- (`Handler`) on(event, regexp = //, args) {|args| ... }

- (`Channel`) part(channel, reason = nil)

- (`String`) set_nick(nick)

- (`Object`) stop

- (`Boolean`) strict?