butler 1.8.0

data/lib/butler/irc/socket.rb

@@ -0,0 +1,378 @@
+#--
+# Copyright 2007 by Stefan Rusterholz.
+# All rights reserved.
+# See LICENSE.txt for permissions.
+#++
+
+
+
+require 'thread'
+require 'socket'
+require 'ostructfixed'
+require 'log/comfort'
+require 'ruby/string/chunks'
+
+
+
+class Butler
+	module IRC
+	
+		# ==Description
+		# Butler::IRC::Socket is a TCPSocket, retrofitted for communication with
+		# IRC-Servers.
+		# It provides specialized methods for sending messages to IRC-Server.
+		# All methods are safe to be used with Butler::IRC::* Objects (e.g. all
+		# parameters expecting a nickname will accept an Butler::IRC::User as well).
+		# It will adhere to its limit-settings, which will prevent from sending too
+		# many messages in a too short time to avoid excess flooding.
+		# Butler::IRC::Socket#write is the only synchronized method, since all other
+		# methods build up on it, IRC::Socket should be safe in threaded environments.
+		# Butler::IRC::Socket#read is NOT synchronized, so unless you read from only
+		# a single thread, statistics might get messed up.
+		# Length limits can only be safely guaranteed by specialized write methods,
+		# Butler::IRC::Socket#write will just warn and send the overlength message.
+		# If you are looking for queries (commands that get an answer from the server)
+		# take a look at Butler::IRC::Client.
+		# 
+		# ==Synopsis
+		# irc	= Butler::IRC::Socket.new('irc.freenode.org', :port => 6667, :charset => 'ISO-8859-1')
+		# irc.connect
+		# irc.login('your_nickname', 'YourUser', 'Your realname', ["#channel1", "#channel2"])
+		# irc.join("#channel3")
+		# irc.part("#channel3")
+		# irc.privmsg("Hi all of you in #channel1!", "#channel1")
+		# irc.close
+		# 
+		# ==Notes
+		# Errno::EHOSTUNREACH: server not reached
+		# Errno::ECONNREFUSED: server is up, but refuses connection
+		# Errno::ECONNRESET:   connection works, server did not yet accept connection, resets after
+		# Errno::EPIPE:        writing to a server-side closed connection, nil on gets, connection was terminated
+		#
+		# ==FIXME
+		# mode commands don't test for length and split up
+		#
+		class Socket
+			VERSION	= "1.0.0"
+
+			include Log::Comfort
+	
+			# server the instance is linked with
+			attr_reader :server
+			# port used for connection
+			attr_reader :port
+			# the own host (nil if not supported)
+			attr_reader :host
+			# end-of-line used for communication
+			attr_reader :eol
+	
+			# contains various counters, such as :received, :sent (lines)
+			attr_reader :count
+	
+			# contains limits for the protocol, burst times/counts etc.
+			attr_reader :limit
+			
+			OptionsDefault = {
+				:port => 6667,
+				:eol  => "\r\n",
+				:host => nil,
+			}
+			
+			# Initialize properties, doesn't connect automatically
+			# options:
+			# * :server: ip/domain of server (overrides a given server parameter)
+			# * :port:   port to connect on, defaults to 6667
+			# * :eol:    what character sequence terminates messages, defaults to \r\n
+			# * :host:   what host address to bind to, defaults to nil
+			#
+			def initialize(server, options={})
+				options       = OptionsDefault.merge(options)
+				@log_device   = options.delete(:log)
+				@server       = server # options.delete(:server)
+				@port         = options.delete(:port)
+				@eol          = options.delete(:eol).dup.freeze
+				@host         = options[:host] ? options.delete(:host).dup.freeze : options.delete(:host)
+				@last_sent    = Time.new()
+				@count        = Hash.new(0)
+				@limit        = OpenStruct.new({
+					:message_length => 300, # max. length of a text message (e.g. in notice, privmsg) sent to server
+					:raw_length     => 400, # max. length of a raw message sent to server
+					:burst          => 4,   # max. messages that can be sent with send_delay (0 = infinite)
+					:burst2         => 20,  # max. messages that can be sent with send_delay (0 = infinite)
+					:send_delay     => 0.1, # minimum delay between each message
+					:burst_delay    => 1.5, # delay after a burst
+					:burst2_delay   => 15,  # delay after a burst2
+				})
+				@limit.each { |key, default|
+					@limit[key] = options.delete(key) if options.has_key?(key)
+				}
+				@mutex        = Mutex.new
+				@socket       = nil
+				@connected    = false
+				raise ArgumentError, "Unknown arguments: #{options.keys.inspect}" unless options.empty?
+			end
+		
+			# connects to the server
+			def connect
+				@socket	= TCPSocket.open(@server, @port) #, @host)
+				info("Connected to #{@server}:#{@port} from #{@host || '<default>'}")
+			rescue ArgumentError => error
+				if @host then
+					warn("host-parameter is not supported by your ruby version. Parameter discarted.")
+					@host = nil
+					retry
+				else
+					raise
+				end
+			rescue Exception
+				error("Connection failed.")
+				raise
+			else
+				@connected		= true
+			end
+	
+			# get next message (eol already chomped) from server, blocking, returns nil if closed
+			def read
+				@count[:read]   += 1
+				if m = @socket.gets(@eol) then
+					m.chomp(@eol)
+				else
+					nil
+				end
+			end
+	
+			# Send a raw message to irc, eol will be appended
+			# Use specialized methods instead if possible since they will releave
+			# you from several tasks like translating newlines, take care of overlength
+			# messages etc.
+			# FIXME, wrong methodname, write implies nothing is appended
+			def write(data)
+				@mutex.synchronize {
+					warn("Raw too long (#{data.length} instead of #{@limit[:raw_length]})") if (data.length > @limit.raw_length)
+					now	= Time.now
+		
+					# keep delay between single (bursted) messages
+					sleeptime = @limit.send_delay-(now-@last_sent)
+					if sleeptime > 0 then
+						sleep(sleeptime)
+						now += sleeptime
+					end
+					
+					# keep delay after a burst (1)
+					if (@count[:burst] >= @limit[:burst]) then
+						sleeptime = @limit.burst_delay-(now-@last_sent)
+						if sleeptime > 0 then
+							sleep(sleeptime)
+							now += sleeptime
+						end
+						@count[:burst]	= 0
+					end
+		
+					# keep delay after a burst (2)
+					if (@count[:burst2] >= @limit[:burst2]) then
+						sleeptime = @limit.burst2_delay-(now-@last_sent)
+						if sleeptime > 0 then
+							sleep(sleeptime)
+							now += sleeptime
+						end
+						@count[:burst2]	= 0
+					end
+		
+					# send data and update data
+					@last_sent       = Time.new
+					@socket.write(data+@eol)
+					@count[:burst]  += 1
+					@count[:burst2] += 1
+					@count[:sent]   += 1
+				}
+			rescue IOError
+				error("Writing #{data.inspect} failed")
+				raise
+			end 
+	
+			# log into the irc-server (and connect if necessary)
+			def login(nickname, username, realname)
+				connect unless @connected
+				write("NICK #{nickname}")
+				write("USER #{username} 0 * :#{realname}")
+			end
+	
+			# identify nickname to nickserv
+			# FIXME, figure out what the server supports, possibly requires it
+			# to be moved to Butler::IRC::Client (to allow ghosting, nickchange, identify)
+			def identify(password)
+				write("NS :IDENTIFY #{password}")
+			end
+			
+			# FIXME, figure out what the server supports, possibly requires it
+			def ghost(nickname, password)
+				write("NS :GHOST #{nickname} #{password}")
+			end
+			
+			def normalize_message(message, limit=:message_length)
+				messages	= []
+				message.split(/\n/).each { |line|
+					messages.concat(line.chunks(@limit[limit]))
+				}
+				messages
+			end
+	
+			# sends a privmsg to given user or channel (or multiple)
+			# messages containing newline or exceeding @limit[:message_length] are automatically splitted
+			# into multiple messages.
+			def privmsg(message, *recipients)
+				normalize_message(message).each { |message|
+					recipients.each { |recipient|
+						write("PRIVMSG #{recipient} :#{message}")
+					}
+				}
+			end
+	
+			# same as privmsg except it's formatted for ACTION
+			def action(message, *recipients)
+				normalize_message(message).each { |message|
+					recipients.each { |recipient|
+						write("PRIVMSG #{recipient} :"+(1.chr)+"ACTION "+message+(1.chr))
+					}
+				}
+			end
+	
+			# sends a notice to receiver (or multiple if receiver is array of receivers)
+			# formatted=true allows usage of ![]-format commands (see IRCmessage.getFormatted)
+			# messages containing newline automatically get splitted up into multiple messages.
+			# Too long messages will be tokenized into fitting sized messages (see @limit[:message_length])
+			def notice(message, *recipients)
+				normalize_message(message).each { |message|
+					recipients.each { |recipient|
+						write("NOTICE #{recipient} :#{message}")
+					}
+				}
+			end
+	
+			# send a pong
+			def pong(*args)
+				if args.empty? then
+					write("PONG")
+				else
+					write("PONG #{args.join(' ')}")
+				end
+			end
+	
+			# join specified channels
+			# use an array [channel, password] to join password-protected channels
+			# returns the channels joined.
+			def join(*channels)
+				channels.map { |channel, password|
+					if password then
+						write("JOIN #{channel} #{password}")
+					else
+						write("JOIN #{channel}")
+					end
+					channel
+				}
+			end
+	
+			# part specified channels
+			# FIXME, better way to implement the reason? use a block (yay)?
+			# returns the channels parted from.
+			def part(reason=nil, *channels)
+				if channels.empty?
+					channels = [reason]
+					reason   = nil
+				end
+				reason ||= "leaving"
+
+				# some servers still can't process lists of channels in part
+				channels.each { |channel|
+					write("PART #{channel} #{reason}")
+				}
+			end
+	
+			# set your own nick
+			# does NO verification/validation of any kind
+			def nick(nick)
+				write("NICK #{nick}")
+			end
+	
+			# set your status to away with reason 'reason'
+			def away(reason="")
+				return back if reason.empty?
+				write("AWAY :#{reason}")
+			end
+	
+			# reset your away status to back
+			def back
+				write("AWAY")
+			end
+	
+			# kick user in channel with reason
+			def kick(user, channel, reason)
+				write("KICK #{channel} #{user} :#{reason}")
+			end
+			
+			# Give Op to user in channel
+			# User can be a nick or IRC::User, either one or an array.
+			def op(channel, *users)
+				write("MODE #{channel} +#{'o'*users.length} #{users*' '}")
+			end
+	
+			# Take Op from user in channel
+			# User can be a nick or IRC::User, either one or an array.
+			def deop(channel, *users)
+				write("MODE #{channel} -#{'o'*users.length} #{users*' '}")
+			end
+	
+			# Give voice to user in channel
+			# User can be a nick or IRC::User, either one or an array.
+			def voice(channel, *users)
+				write("MODE #{channel} +#{'v'*users.length} #{users*' '}")
+			end
+	
+			# Take voice from user in channel.
+			# User can be a nick or IRC::User, either one or an array.
+			def devoice(channel, *users)
+				write("MODE #{channel} -#{'v'*users.length} #{users*' '}")
+			end
+	
+			# Set ban in channel to mask
+			def ban(mask, channel)
+				write("MODE #{channel} +b #{mask}")
+			end
+	
+			# Send a "who" to channel
+			def who(channel)
+				write("WHO #{channel}")
+			end
+	
+			# Send a "whois" to server
+			def whois(nick)
+				write("WHOIS #{nick}")
+			end
+	
+			# send the quit message to the server
+			# if you set close to true it will also close the socket
+			def quit(reason="leaving", close=false)
+				write("QUIT :#{reason}")
+				close() if close
+			end
+	
+			# closes the connection to the irc-server
+			def close
+				raise "Socket not open" unless @socket
+				@socket.close unless @socket.closed?
+			end
+			
+			def inspect # :nodoc:
+				"#<%s:0x%08x %s:%s from %s using '%s', stats: %s>" %  [
+					self.class,
+					object_id << 1,
+					@server,
+					@port,
+					@host || "<default>",
+					@eol.inspect[1..-2],
+					@count.inspect
+				]
+			end
+		end
+	end
+end

data/lib/butler/irc/string.rb

@@ -0,0 +1,186 @@
+#--
+# Copyright 2007 by Stefan Rusterholz.
+# All rights reserved.
+# See LICENSE.txt for permissions.
+#++
+
+
+
+#	provides IRC-related methods for string-class
+class String
+	# Colors Lookup-table for mirc_translated_color
+	COLORS = {
+		'white'    => 0,
+		'black'    => 1,
+		'blue'     => 2,
+		'green'    => 3,
+		'red'      => 4,
+		'brown'    => 5,
+		'purple'   => 6,
+		'orange'   => 7,
+		'yellow'   => 8,
+		'ltgreen'  => 9,
+		'teal'     => 10,
+		'ltcyan'   => 11,
+		'ltblue'   => 12,
+		'pink'     => 13,
+		'grey'     => 14,
+		'ltgrey'   => 15
+	}
+
+	# returns whether or not a string represents a valid channelname
+	def valid_channelname?
+		self =~ /\A[&#!\+][^\x07\x0A\x0D,: ]{1,50}\z/
+	end
+
+	# returns if the the string represents a valid nickname
+	# this method does not take care of prefixes lik "@", "+", "-"
+	# see valid_user? for this funktionality or strip_user_prefixes
+	def valid_nickname?
+		#self =~ /\A[0-9A-Za-z_][0-9A-Za-z_\-\|\\\[\]\{\}\^\`]*\z/
+		self =~ /\A[0-9A-Za-z_\-\|\\\[\]\{\}\^\`]+\z/
+	end
+	
+	# the same as valid_nickname? except that preceding @, + or - are ignored
+	def valid_user?
+		strip_user_prefixes.valid_nickname?
+	end
+
+	# removes indicators from nicknames and channelnames
+	def strip_user_prefixes
+		prefixes	= Butler::IRC::User::PREFIXES.dup
+		index		= 0
+		while (prefixes.has_key?(self[index,1]))
+			prefixes.delete(self[index,1])
+			index	+= 1
+		end
+		return self[index..-1]
+	end
+
+	# returns prefixes found in front of a nickname
+	# Sequential parsing since @@nickname is not valid.
+	def user_prefixes
+		prefixes	= Butler::IRC::User::PREFIXES.dup
+		index		= 0
+		found		= 0
+		while (prefixes.has_key?(self[index,1]))
+			found |= prefixes.delete(self[index,1])
+			index	+= 1
+		end
+		return found
+	end
+
+	# Converts string representation of user-prefixes to binary flags
+	def to_flags
+		result	= 0
+		0.upto(self.length) { |index|
+			result |= Butler::IRC::User::PREFIXES[self[index,1]]
+		}
+		return result
+	end
+
+	# returns a string with formating codes in mirc-format stripped
+	def mirc_stripped
+		return self.gsub(/(?:[\x02\x0f\x12\x1f\x1d\x09]|\cc\d{1,2}(?:,\d{1,2})?)/, "")
+	end
+	
+=begin rdoc
+	provides mirc formatting:
+	![b]:		bold
+	![i]:		italic
+	![u]:		underline
+	![r]:		reverse
+	![c]:		reset color
+	![cm]:		set color, m=0-15 or (COLOR_CONSTANT)
+	![cm,n]:	set color, m is foreground, n is background, m,n=0-15 or (COLOR_CONSTANT)
+	![o]:		reset all effects
+	
+	Samples:
+		![bc(blue)]Bold blue text![o] and normal again
+		![bc2]Bold blue text![o] and normal again (same as above)
+		![bc(white),(black)]White bold text on black background![o]
+		![bi]Bold italic text![o]
+
+	Valid colors are:
+		white   (mirc-code: 0)
+		black   (mirc-code: 1)
+		blue    (mirc-code: 2)
+		green   (mirc-code: 3)
+		red     (mirc-code: 4)
+		brown   (mirc-code: 5)
+		purple  (mirc-code: 6)
+		orange  (mirc-code: 7)
+		yellow  (mirc-code: 8)
+		ltgreen (mirc-code: 9)
+		teal    (mirc-code: 10)
+		ltcyan  (mirc-code: 11)
+		ltblue  (mirc-code: 12)
+		pink    (mirc-code: 13)
+		grey    (mirc-code: 14)
+		ltgrey  (mirc-code: 15)
+
+	
+	Note: not every font/size combination displays bold/italic text.
+=end
+	def mirc_formatted # FIXME - copied code, ugly & slow
+		self.gsub( /!\[(.*?)\]/ ) do |match|
+			codes = $1.downcase
+			repl = ""
+			i = 0
+			while i < codes.length
+				case codes[i].chr
+					when 'b'
+						repl << 2.chr
+					when 'o'
+						repl << 15.chr
+					when 'r'
+						repl << 18.chr
+					when 'u'
+						repl << 31.chr
+					when 'i'
+						repl << 29.chr
+					when '|'
+						repl << 9.chr
+					when 'c'
+						bg = nil
+						
+						i, fg = mirc_translated_color( i+1, codes )
+						i, bg = mirc_translated_color( i+1, codes ) if i < codes.length && codes[i].chr == ','
+						
+						repl << "" << ( fg || "" )
+						repl << "," << bg if bg
+						
+						i -= 1
+				end
+					
+				i += 1
+			end
+			repl
+		end
+	end
+
+	# helper method for mirc_formatted, extracts color portions from ![c(color)] statements
+	def mirc_translated_color( i, s )
+		return [ i, nil ] if i >= s.length
+		
+		if s[i].chr == '('
+			j = s.index( ')', i )
+			return [ j+1, "%02d" % COLORS[ s[i+1..j-1].downcase ] ]
+		end
+		
+		j = i
+		j += 1 while j < s.length && s[j].chr =~ /[0-9]/
+		j += 1 if j == s.length
+		return [ j, "%02d" % s[i..j-1].to_i ]
+	end
+end #String
+
+if __FILE__ == $0 then
+	require 'test/unit'
+	class TestIRCString < Test::Unit::TestCase
+		def test_user
+			assert("foobar".valid_nickname?)
+			assert(!"{foobar}".valid_nickname?)
+		end
+	end
+end