butler 1.8.0

data/lib/butler/irc/channels.rb

@@ -0,0 +1,96 @@
+#--
+# Copyright 2007 by Stefan Rusterholz.
+# All rights reserved.
+# See LICENSE.txt for permissions.
+#++
+
+
+
+require 'butler/irc/string'
+require 'butler/irc/channel'
+require 'butler/irc/users'
+require 'thread'
+
+
+
+class Butler
+	module IRC
+		CHANNEL_SIGNALS	= [
+			:joined,	# myself joined a channel
+			:parted,	# myself parted the channel
+			:kicked,	# myself got kicked from the channel
+			:quitted,	# myself has quit
+			:left, 		# same as :parted || :kicked || :quitted
+			:join,		# the user joined the channel
+			:part,		# the user parted the channel
+			:kick,		# the user got kicked from the channel
+			:quit,		# the user has quit
+			:leave,		# same as :part || :kick || :quit
+			:topic,		# topic has changed
+			:mode,		# mode has changed
+		]
+	
+		# Butler::IRC::Channel represents a channel in IRC.
+		class Channels
+			include Enumerable
+	
+			def initialize(client)
+				@all		= {}
+				@client = client
+				@users  = nil
+				@lock   = Mutex.new
+			end
+
+			def users=(users)
+				raise "Can't set @users twice" if @users
+				@users = users
+			end
+	
+			# Will return the single instance representing the channel
+			# with name 'channel'.
+			def create(channel, *args)
+				@lock.synchronize {
+					channel	= self[channel] || Channel.new(@users, channel, *args)
+					@all[channel.to_str]	= channel
+				}
+			end
+	
+			# Iterates through all known channels (@all)
+			def each(&block)
+				@all.each_value(&block)
+			end
+	
+			# returns channelcount
+			def length
+				@all.length
+			end
+			
+			# returns the lowercased channelnames
+			def channel_names
+				@all.keys
+			end
+			
+			# returns all channels with that name (names should
+			# be normalized to lowercased name)
+			# 
+			def map_names(*names)
+				@all.values_at(*names)
+			end
+	
+			# Remove a channel from the channels-list
+			def delete(channel)
+				@all.delete(channel.to_str.downcase)
+			end
+	
+			# Remove user from all channels
+			def delete_user(user, reason) #:nodoc:
+				@all.each_value { |channel| channel.delete_user(user, reason) }
+			end
+	
+			# Get the channel with name 'channel'
+			def [](channel)
+				@all[channel.to_str.downcase]
+			end
+		end
+	end
+end

data/lib/butler/irc/client.rb

@@ -0,0 +1,351 @@
+require 'butler/irc/channels'
+require 'butler/irc/parser'
+require 'butler/irc/socket'
+require 'butler/irc/users'
+require 'log/comfort'
+require 'timeout'
+require 'thread'
+
+class Butler
+	module IRC
+		# Reply for Butler::IRC::Client#whois
+		Whois	= Struct.new(:exists, :nick, :user, :host, :real, :registered, :channels, :server, :idle, :signon)
+	
+		# == 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| "#{message.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"
+		#
+		class Client
+			class Terminate < RuntimeError; end
+			# Created by Butler::IRC::Client#subscribe() and similar methods
+			Listener = Struct.new(:priority, :callback, :args, :unsubscriber) unless defined? Listener
+			class Listener
+				alias set_priority priority=
+				private :set_priority
+				private :unsubscriber
+
+				def initialize(priority, callback, args=[], &unsubscriber)
+					super(priority, callback, args, unsubscriber)
+				end
+
+				# will remove this listener from the clients dispatcher forever
+				def unsubscribe
+					unsubscriber.call(self)
+				end
+
+				# set the priority of this listener
+				# see Butler::IRC::Client#subscribe() for infos about priority
+				def priority=(value)
+					set_priority(value)
+					container.sort_by { |l| -l.priority }
+				end
+			end
+			module Filter # :nodoc:
+				attr_accessor :listener
+				def unsubscribe
+					listener.unsubscribe
+				end
+			end
+			
+			# The timeout defaults
+			DefaultTimeout = {
+				:login   => 150,
+			}
+
+			# Defaults for the opts argument in Butler::Bot.new
+			DefaultOptions = {
+				:client_charset  => 'utf-8',
+				:server_charset  => 'utf-8',
+				:channel_charset => {},
+				:timeout         => {},
+			}
+
+			# The charset the client uses
+			attr_accessor :client_charset
+
+			# The charset the server needs messages sent to him and sends message to
+			# this client in.
+			attr_accessor :server_charset
+			
+			# The charsets of individual channel, only set if they differ from
+			# server_charset
+			attr_reader   :channel_charset
+			
+			attr_reader   :channels
+			attr_reader   :users
+			
+			# The Butler::IRC::Socket, most send commands have to be used on this
+			attr_reader   :irc
+
+			# The user representing the bot
+			attr_reader   :myself
+	
+			def initialize(server, options={}, &on_disconnect)
+				options          = DefaultOptions.merge(options)
+				@users           = Users.new(self)
+				@channels        = Channels.new(self)
+				@users.channels  = @channels
+				@channels.users  = @users
+				@parser          = Parser.new(self, @users, @channels)
+	
+				@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(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
+			
+			# 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
+			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
+
+			# unsubscribe a listener by id
+			def unsubscribe(id)
+				@dispatch_lock.synchronize {
+					@listener.delete(id)
+					@listen[symbol].delete(item)
+					@listen.delete(symbol) if @listen[symbol].empty?
+				}
+			end
+			
+			# 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
+			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
+			
+			# 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)
+			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
+	
+			# login under nick, user, real
+			def login(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.login(nick, user, real)
+					queue.shift
+				}
+				true
+			ensure
+				queue.unsubscribe if queue
+				nick_change.unsubscribe if nick_change
+			end
+			
+			# Same as IRC::Socket#join, but will do a who on every joined channel
+			def join(*args)
+				@irc.join(*args).each { |channel|
+					@irc.who(channel)
+				}
+			end
+			
+			# Do a whois on nick
+			# Returns an Butler::IRC::Whois-Struct
+			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
+
+			# Sends quit message to server, terminates connection
+			def quit(reason=nil)
+				@irc.quit(reason)
+				terminate
+				@irc.close
+			end
+	
+			# terminate all processing and reading,
+			# see Client#quit
+			def terminate(stop_reading=true)
+				@thread_read.raise Terminate if stop_reading and @thread_read and @thread_read.alive?
+				terminate_event_loop
+			end
+	
+			# 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
+			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
+			
+			def on_disconnect(reason)
+			end
+			
+			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
+			
+			def terminate_event_loop
+				@event_loop.push(nil) if @event_loop
+			end
+			
+			# process a Butler::IRC::Message, normally fed from thread_read.
+			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
+			
+			def inspect # :nodoc:
+				"#<%s:0x%08x irc=%s>" %  [
+					self.class,
+					object_id << 1,
+					@irc.inspect
+				]
+			end
+		end # Client
+	end # IRC
+end # Butler

data/lib/butler/irc/hostmask.rb

@@ -0,0 +1,53 @@
+#--
+# Copyright 2007 by Stefan Rusterholz.
+# All rights reserved.
+# See LICENSE.txt for permissions.
+#++
+
+
+
+require 'butler/irc/users'
+
+
+
+class Butler
+	module IRC
+		# Provides methods to see if hostmasks match
+		class Hostmask
+			Filter	= [
+				[/([\\\[\]{}^`.-])/, '\\\\\1'],
+				[/\?/,  "."],
+				[/\*/, ".*?"],
+			]
+	
+			# FIXME, not yet correct, escaped * and ?
+			def initialize(mask)
+				@mask    = mask.dup.freeze
+				filtered = Filter.inject('[]{}^`.-') { |s,(a,b)| s.gsub(a,b) }
+				#string.gsub(/[\\\x00-\x1f]/) { |match| ("\\%02x" % match[0]) } #implement later
+				@regex	= Regexp.new("\A#{filtered}\z")
+			end
+	
+			def matches?(mask)
+				mask	= mask.hostmask if mask.kind_of?(User)
+				return !@regex.match(mask.to_str).nil?
+			end
+	
+			def match(mask)
+				mask	= mask.hostmask if mask.kind_of?(User)
+				@regex.match(mask.to_str)
+			end
+	
+			def to_str
+				@mask
+			end
+			alias to_s to_str
+		end
+	
+		class User
+			def hostmask
+				return Hostmask.new("#{@nick||'*'}!#{@user||'*'}@#{@host||'*'}")
+			end
+		end
+	end
+end