Class: Butler::IRC::Client

Inherits:
Object
  • Object
show all
Includes:
Log::Comfort
Defined in:
lib/butler/irc/client.rb

Overview

Description

Wraps Butler::IRC::Socket, providing methods to be aware of the environment. It parses messages, keeps track of users and channels, is aware of events, responds to pings, provides simple methods for requests (e.g. whois, banlist, …) and offers dispatchers for messages and scheduled events. Butler::IRC::Client uses a separated thread for reading and dispatching.

Synopsis

irc_client  = Butler::IRC::Client.new('irc.server.com', :port => 6667, :server_charset => 'utf-8')

irc_client.subscribe(:QUIT) { |listener, message| “#messagemessage.frommessage.from.nick has left us…” }

puts "Whois 'nickname':", irc_client.whois("nickname")
puts *irc_client.banlist("#channel")
irc_client.event_loop { |message|
  case message
    when /#{irc_client.myself.nick}[,:]/
      message.answer("#{message.from.nick}, you spoke to me?")
    when :JOIN
      message.from.notice("Welcome to #{message.channel}!")
  end
  puts "received: #{message}"
}
puts "If this point is reached, client has ended"

Direct Known Subclasses

Bot

Defined Under Namespace

Modules: Filter Classes: Listener, Terminate

Constant Summary collapse

DefaultTimeout =

The timeout defaults

{
  :login   => 150,
}
DefaultOptions =

Defaults for the opts argument in Butler::Bot.new

{
  :client_charset  => 'utf-8',
  :server_charset  => 'utf-8',
  :channel_charset => {},
  :timeout         => {},
}

Instance Attribute Summary collapse

Attributes included from Log::Comfort

#logger

Instance Method Summary collapse

Methods included from Log::Comfort

#debug, #error, #exception, #fail, #info, #log, #warn

Constructor Details

#initialize(server, options = {}, &on_disconnect) ⇒ Client

Returns a new instance of Client.



104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/butler/irc/client.rb', line 104

def initialize(server, options={}, &on_disconnect)
  options          = DefaultOptions.merge(options)
  @logger          = nil
  @users           = Users.new(self)
  @channels        = Channels.new(self)
  @users.channels  = @channels
  @channels.users  = @users
  @parser          = Parser.new(self, @users, @channels, "rfc2812", "generic")
  
  @client_charset  = options.delete(:client_charset)
  @server_charset  = options.delete(:server_charset)
  # proc needed because @server_charset might change
  @channel_charset = Hash.new { |h,k| @server_charset }.merge(options.delete(:channel_charset))
  
  @timeout         = DefaultTimeout.merge(options.delete(:timeout))

  @irc             = Socket.new(options.delete(:server) || server, options) # the socket, all methods to the socket are wrapped
  
  @listen          = Hash.new { |h,k| h[k] = [] }
  @listener        = {}
  @event_loop      = Queue.new
  @dispatch_lock   = Mutex.new
  @thread_read     = nil
  @myself          = @users.myself
  
  subscribe(:PING, 100) { |listener, message| @irc.pong(message.pong) }
end

Instance Attribute Details

#channel_charset ⇒ Object (readonly)

The charsets of individual channel, only set if they differ from server_charset



93
94
95
 
# File 'lib/butler/irc/client.rb', line 93

def channel_charset
  @channel_charset
end

#channels ⇒ Object (readonly)

Returns the value of attribute channels.



95
96
97
 
# File 'lib/butler/irc/client.rb', line 95

def channels
  @channels
end

#client_charset ⇒ Object

The charset the client uses



85
86
87
 
# File 'lib/butler/irc/client.rb', line 85

def client_charset
  @client_charset
end

#irc ⇒ Object (readonly)

The Butler::IRC::Socket, most send commands have to be used on this



99
100
101
 
# File 'lib/butler/irc/client.rb', line 99

def irc
  @irc
end

#myself ⇒ Object (readonly)

The user representing the bot



102
103
104
 
# File 'lib/butler/irc/client.rb', line 102

def myself
  @myself
end

#server_charset ⇒ Object

The charset the server needs messages sent to him and sends message to this client in.



89
90
91
 
# File 'lib/butler/irc/client.rb', line 89

def server_charset
  @server_charset
end

#users ⇒ Object (readonly)

Returns the value of attribute users.



96
97
98
 
# File 'lib/butler/irc/client.rb', line 96

def users
  @users
end

Instance Method Details

#event_loop(priority = -1)) ⇒ Object 



319
320
321
322
323
324
325
326
327
328
 
# File 'lib/butler/irc/client.rb', line 319

def event_loop(priority=-1)
  if block_given?
    filter(nil, priority, @event_loop)
    while message = @event_loop.shift; yield(message); end
  else
    sleep
  end
ensure
  @event_loop.unsubscribe if block_given?
end

#filter(symbol, priority = 0, queue = Queue.new) ⇒ Object

listens for all Messages with symbol (optionally passing a test given as block) and pushes them onto the Queue returns the Queue, extended with Filter. You are responsible to unsubscribe it (call Queue#unsubscribe on it)

Raises:

  • (ArgumentError) 


192
193
194
195
196
197
198
199
200
201
202
 
# File 'lib/butler/irc/client.rb', line 192

def filter(symbol, priority=0, queue=Queue.new)
  raise ArgumentError, "Invalid Queue #{queue}:#{queue.class}" unless queue.respond_to?(:push)
  listener = if block_given? then
    subscribe(symbol, priority) { |l, message| queue.push(message) if yield(message) }
  else
    subscribe(symbol, priority) { |l, message| queue.push(message) }
  end
  queue.extend Filter
  queue.listener = listener
  queue
end

#inspect ⇒ Object

:nodoc:



350
351
352
353
354
355
356
 
# File 'lib/butler/irc/client.rb', line 350

def inspect # :nodoc:
  "#<%s:0x%08x irc=%s>" %  [
    self.class,
    object_id << 1,
    @irc.inspect
  ]
end

#join(*args) ⇒ Object

Same as IRC::Socket#join, but will do a who on every joined channel



230
231
232
233
234
 
# File 'lib/butler/irc/client.rb', line 230

def join(*args)
  @irc.join(*args).each { |channel|
    @irc.who(channel)
  }
end

#load_command_set(*sets) ⇒ Object

Load an additional command-set for @parser



133
134
135
 
# File 'lib/butler/irc/client.rb', line 133

def load_command_set(*sets)
  @parser.commands.load(*sets)
end

#login(nick, user, real) ⇒ Object

login under nick, user, real



205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
 
# File 'lib/butler/irc/client.rb', line 205

def (nick, user, real)
  queue, nick_change = nil, nil
  number = 0
  timeout(@timeout[:login]) {
    @irc.connect
    @users.create_myself(nick, user, real)
    @myself = @users.myself
    queue = filter(:RPL_WELCOME)
    filter(:ERR_NOMOTD, 0, queue)
    nick_change = subscribe(:ERR_NICKNAMEINUSE) {
      change = "[#{number+=1}]#{nick}"
      @irc.nick(change)
      @myself.nick = change
    }
    @thread_read = Thread.new(&method(:thread_read))
    @irc.(nick, user, real)
    queue.shift
  }
  true
ensure
  queue.unsubscribe if queue
  nick_change.unsubscribe if nick_change
end

#on_disconnect(reason) ⇒ Object 



316
317
 
# File 'lib/butler/irc/client.rb', line 316

def on_disconnect(reason)
end

#process(message) ⇒ Object

process a Butler::IRC::Message, normally fed from thread_read.



335
336
337
338
339
340
341
342
343
344
345
346
347
348
 
# File 'lib/butler/irc/client.rb', line 335

def process(message)
  message = @parser.server_message(message)
  message.transcode!(@channel_charset[message.channel], @client_charset)
  @dispatch_lock.synchronize {
    @listen[nil].each { |listener| listener.callback.call(listener, message) }
    if @listen.has_key?(message.symbol)
      @listen[message.symbol].each { |listener| listener.callback.call(listener, message, *listener.args) }
    end
  }
rescue Terminate, Errno::EPIPE => error
  raise error # on these errors we got to get out of the loop
rescue Exception => error
  exception(error) # those errors are logged, reading goes on
end

#quit(reason = nil) ⇒ Object

Sends quit message to server, terminates connection



284
285
286
287
288
 
# File 'lib/butler/irc/client.rb', line 284

def quit(reason=nil)
  @irc.quit(reason)
  terminate
  @irc.close
end

#subscribe(symbol = nil, priority = 0, id = nil, *args, &callback) ⇒ Object

callback is called whenever a message with Message#symbol == symbol (or on every message if symbol is nil) priority may be any numeric, higher priority is dispatched to first, lower priority later returns an Butler::IRC::Client::Listener



142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
 
# File 'lib/butler/irc/client.rb', line 142

def subscribe(symbol=nil, priority=0, id=nil, *args, &callback)
  id              ||= callback
  raise "#{id} already subscribed" if @listener.has_key?(id)
  listener          = Listener.new(priority, callback, args) { |item|
    @dispatch_lock.synchronize {
      @listener.delete(id)
      @listen[symbol].delete(item)
      @listen.delete(symbol) if @listen[symbol].empty?
    }
  }
  @dispatch_lock.synchronize {
    @listener[id]     = listener
    @listen[symbol]  << listener
    @listen[symbol].sort_by { |l| -l.priority }
  }
  listener
end

#terminate(stop_reading = true) ⇒ Object

terminate all processing and reading, see Client#quit



292
293
294
295
 
# File 'lib/butler/irc/client.rb', line 292

def terminate(stop_reading=true)
  @thread_read.raise Terminate if stop_reading and @thread_read and @thread_read.alive?
  terminate_event_loop
end

#terminate_event_loop ⇒ Object 



330
331
332
 
# File 'lib/butler/irc/client.rb', line 330

def terminate_event_loop
  @event_loop.push(nil) if @event_loop
end

#thread_read ⇒ Object

this thread is responsible for reading the servers messages and dispatching them to responders normally this thread is alive as long as the client is connected to the server



300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
 
# File 'lib/butler/irc/client.rb', line 300

def thread_read
  while message = @irc.read; process(message); end
  on_disconnect(:disconnect)
rescue Terminate => e   # got the termination signal
  info("Terminating read thread")
  on_disconnect(:quit)
rescue Errno::EPIPE => error  # irc server closed connection
  exception(error)
  on_disconnect(:disconnect)
rescue Exception => error
  exception(error)
  on_disconnect(:error)
ensure
  @irc.close
end

#unsubscribe(id) ⇒ Object

unsubscribe a listener by id



161
162
163
164
165
166
167
 
# File 'lib/butler/irc/client.rb', line 161

def unsubscribe(id)
  @dispatch_lock.synchronize {
    @listener.delete(id)
    @listen[symbol].delete(item)
    @listen.delete(symbol) if @listen[symbol].empty?
  }
end

#wait_for(symbol, timeout = nil, &test) ⇒ Object

blocks current thread until a Message with symbol (optionally passing a test given as block) is received, returns the message received that matches. returns nil if it times out before a match



173
174
175
176
177
178
179
180
181
182
183
184
185
186
 
# File 'lib/butler/irc/client.rb', line 173

def wait_for(symbol, timeout=nil, &test)
  timeout(timeout) {
    queue    = Queue.new
    listener = subscribe(symbol) { |l, m| queue.push(m) }
    begin
      message = queue.shift
    end until block_given? ? yield(message) : true
    message
  }
rescue Timeout::Error
  return nil
ensure
  listener.unsubscribe
end

#whois(user) ⇒ Object

Do a whois on nick Returns an Butler::IRC::Whois-Struct

Raises:

  • (ArgumentError) 


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
 
# File 'lib/butler/irc/client.rb', line 238

def whois(user)
  nick = user.to_str.strip_user_prefixes
  raise ArgumentError, "Invalid nick #{nick.inspect}" unless nick.valid_nickname?
  queue = Queue.new
  whois  = Whois.new
  whois.exists = true
  [
    :RPL_WHOISUSER,
    :RPL_WHOISSERVER,
    :RPL_WHOISIDLE,
    :RPL_ENDOFWHOIS,
    :RPL_UNIQOPIS,
    :RPL_WHOISCHANNELS,
    :RPL_IDENTIFIED_TO_SERVICES,
    :ERR_NOSUCHNICK,
    :RPL_REGISTERED_INFO
  ].each { |reply| filter(reply, 1, queue) }
  @irc.whois(nick)
  until (message = queue.shift).symbol == :RPL_ENDOFWHOIS
    case message.symbol
      when :ERR_NOSUCHNICK
        whois.exists     = false
      when :RPL_WHOISUSER
        whois.exists     = true
        whois.nick       = message.nick
        whois.user       = message.user
        whois.host       = message.host
        whois.real       = message.real
      when :RPL_WHOISSERVER
      when :RPL_WHOISIDLE
        whois.exists     = true
        whois.signon     = message.signon_time
        whois.idle       = message.seconds_idle
      when :RPL_UNIQOPIS
      when :RPL_WHOISCHANNELS
        whois.exists     = true
        whois.channels   = message.channels
      when :RPL_REGISTERED_INFO
        whois.exists     = true
        whois.registered = true
    end
  end
  return whois
end