Class: Butler::IRC::Client

Inherits:
Object
  • Object
show all
Includes:
Log::Comfort
Defined in:
lib/butler/irc/client.rb,
lib/butler/irc/client/filter.rb,
lib/butler/irc/client/listener.rb,
lib/butler/irc/client/listenerlist.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
      irc_client.irc.notice("Welcome to #{message.channel}!", message.from)
  end
  puts "received: #{message}"
}
puts "If this point is reached, client has ended"

Defined Under Namespace

Modules: Filter Classes: Listener, ListenerList, 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

Arguments:

* server: the server to connect to



98
99
100
101
102
103
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
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/butler/irc/client.rb', line 98

def initialize(server, options={}, &on_disconnect)
	options              = DefaultOptions.merge(options)
	@disconnect_callback = 
	@logger              = nil
	@users               = UserList.new(self)
	@channels            = ChannelList.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
	
	@listener            = ListenerList.new
	@event_loop          = Queue.new
	@thread_read         = nil
	@myself              = @users.myself
	
	subscribe(:PING, 100) { |listener, message| @irc.pong(message.pong) }
	subscribe(:ISUPPORT) { |listener, message|
		isupport = {}
		@parser.isupport.to_hash.each { |key, value|
			isupport[key.to_s] = value
		}
		message.support.each { |key,value|
			isupport[key.downcase] = value
		}
		if message.support.has_key?("PREFIX") then
			isupport["prefixes"] = message.support["PREFIX"].values.join('')
		end
		@parser.reset(isupport)
		@irc.write_with_eol("CAPAB IDENTIFY-MSG") if @parser.isupport.capab and !@parser.msg_identify
	}
	subscribe(:RPL_IDENTIFY_MSG) { |listener, message|
		@parser.msg_identify = true
	}
end

Instance Attribute Details

#channel_charset ⇒ Object (readonly)

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



76
77
78
 
# File 'lib/butler/irc/client.rb', line 76

def channel_charset
  @channel_charset
end

#channels ⇒ Object (readonly)

The channels the client participates



79
80
81
 
# File 'lib/butler/irc/client.rb', line 79

def channels
  @channels
end

#client_charset ⇒ Object

The charset the client uses



68
69
70
 
# File 'lib/butler/irc/client.rb', line 68

def client_charset
  @client_charset
end

#disconnect_callback ⇒ Object

A callback invoked on disconnects, accepts one argument: reason, which can be

* :quit:       you told the client to quit
* :disconnect: the server disconnected your client
* :error:      an error occurred in the read-thread (shouldn't happen)



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

def disconnect_callback
  @disconnect_callback
end

#irc ⇒ Object (readonly)

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



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

def irc
  @irc
end

#myself ⇒ Object (readonly)

The user representing the bot



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

def myself
  @myself
end

#server_charset ⇒ Object

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



72
73
74
 
# File 'lib/butler/irc/client.rb', line 72

def server_charset
  @server_charset
end

#users ⇒ Object (readonly)

The users visible to the client



82
83
84
 
# File 'lib/butler/irc/client.rb', line 82

def users
  @users
end

Instance Method Details

#dispatch(message) ⇒ Object

dispatch a message



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

def dispatch(message)
	message.transcode!(@channel_charset[message.channel], @client_charset)
	@listener.synchronized_each_for(message.symbol) { |listener|
		listener.call(message)
	}
end

#event_loop(priority = -1)) ⇒ Object 



324
325
326
327
328
329
330
331
332
333
 
# File 'lib/butler/irc/client.rb', line 324

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) 


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

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:



356
357
358
359
360
361
362
 
# File 'lib/butler/irc/client.rb', line 356

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



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

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

#load_command_set(*sets) ⇒ Object

Load an additional command-set for @parser



143
144
145
 
# File 'lib/butler/irc/client.rb', line 143

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

#login(nick, user, real, serverpass = nil) ⇒ Object

login under nick, user, real



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

def (nick, user, real, serverpass=nil)
	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, serverpass)
		queue.shift
	}
	true
ensure
	queue.unsubscribe if queue
	nick_change.unsubscribe if nick_change
end

#on_disconnect(reason) ⇒ Object

Called on disconnects, see disconnect_callback attribute documentation



320
321
322
 
# File 'lib/butler/irc/client.rb', line 320

def on_disconnect(reason)
	@disconnect_callback.call(reasons) if @disconnect_callback
end

#process(message) ⇒ Object

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



340
341
342
343
344
345
346
 
# File 'lib/butler/irc/client.rb', line 340

def process(message)
	dispatch(@parser.server_message(message))
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



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

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

#subscribe(symbols = nil, priority = 0, *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



152
153
154
155
156
 
# File 'lib/butler/irc/client.rb', line 152

def subscribe(symbols=nil, priority=0, *args, &callback)
	listener = Listener.new(symbols, priority, *args, &callback)
	@listener.subscribe(listener)
	listener
end

#subscribe_listener(listener) ⇒ Object

subscribe a Listener instance (or anything that emulates its interface)



159
160
161
 
# File 'lib/butler/irc/client.rb', line 159

def subscribe_listener(listener)
	@listener.subscribe(listener)
end

#terminate(stop_reading = true) ⇒ Object

terminate all processing and reading, see Client#quit



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

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 



335
336
337
 
# File 'lib/butler/irc/client.rb', line 335

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



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

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

#unsubscribe(listener) ⇒ Object

unsubscribe a listener



164
165
166
 
# File 'lib/butler/irc/client.rb', line 164

def unsubscribe(listener)
	@listener.unsubscribe(listener)
end

#wait_for(symbol, timeout = nil, opt = {}, &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



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

def wait_for(symbol, timeout=nil, opt={}, &test)
	listener = nil
	timeout(timeout) {
		queue    = Queue.new
		listener = subscribe(symbol) { |l, m| queue.push(m) }
		opt[:prepare].call if opt.has_key?(:prepare)
		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) 


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

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