butler 1.8.0

data/lib/butler/irc/topic.rb

@@ -0,0 +1,15 @@
+class Butler
+	module IRC
+		Topic = Struct.new(:text, :set_by, :set_at) unless defined? Topic
+		class Topic
+			def inspect
+				"#<%s %s --%s on %s>" %  [
+					self.class,
+					text,
+					set_by,
+					set_at.strftime("%Y-%m-%d %H:%M")
+				]
+			end
+		end
+	end
+end

data/lib/butler/irc/user.rb

@@ -0,0 +1,265 @@
+#--
+# Copyright 2007 by Stefan Rusterholz.
+# All rights reserved.
+# See LICENSE.txt for permissions.
+#++
+
+
+
+class Butler
+	module IRC
+		# Enumerable: channels (IRC::Channel instances) the user is known to be in
+		class User
+			module Flags
+				ADMIN = 1
+				IRCOP = 2
+				AOP   = 4
+				OP    = 8
+				VOICE = 16
+				UOP   = 32
+			end
+			include Flags
+	
+			USER_STATUS		= [:unknown, :myself, :online, :out_of_sight, :offline, :mutated]
+			
+			PREFIXES      = Hash.new(0)
+			PREFIXES["@"] = OP
+			PREFIXES["+"] = VOICE
+			PREFIXES["-"] = UOP
+	
+			include Comparable
+			include Enumerable
+	
+			#nickname of a user
+			attr_reader :nick
+
+			#username of a user
+			attr_reader :user
+
+			#hostpart of a user
+			attr_reader :host
+
+			#realname of a user
+			attr_reader :real
+
+			#users last known status (:unknown, :online, :out_of_sight, :offline)
+			attr_reader :status
+	
+			#lowercase nickname
+			attr_reader :compare
+	
+			def initialize(users, channels, nick=nil, user=nil, host=nil, real=nil)
+				@nick, @user, @host, @real = nil
+				@users        = users
+				@nick         = nick.to_str.strip_user_prefixes.freeze if nick
+				@user         = user.freeze if user
+				@host         = host.freeze if host
+				@real         = real.freeze if real
+	
+				@compare      = @nick ? @nick.downcase : "\xff"
+				@all_channels = channels
+				@channels     = {} # downcased channelname => flags
+				@status       = :unknown
+				@is_away      = false
+				@away_message = ""
+			end
+
+			# Iterate over all users in this channel
+			def each
+				@channels.each_value { |channel| yield @all_channels[channel] }
+			end	
+			
+			def channels
+				@all_channels.map_names(*@channels.keys)
+			end
+			
+			def channel_names
+				@channels.keys
+			end
+	
+			# update userdata (set user, host, real if they are nil)
+			def update(user=nil, host=nil, real=nil) #:nodoc:
+				raise ArgumentError, "Non assignable new value for user" if @user and user and @user != user
+				raise ArgumentError, "Non assignable new value for host" if @host and host and @host != host
+				raise ArgumentError, "Non assignable new value for real" if @real and real and @real != real
+				@user = user.freeze if user
+				@host = host.freeze if host
+				@real = real.freeze if real
+				self
+			end
+	
+			# set users nickname (should only be used by Butler::IRC::Parser)
+			def nick=(nick) #:nodoc:
+				nick = nick.to_str.strip_user_prefixes
+				raise ArgumentError, "Invalid nickname #{nick}" unless nick.valid_nickname?
+				@users.lock.synchronize {
+					old_index = @compare
+					@nick     = nick
+					@compare  = @nick.downcase
+					@users.rehash(old_index, @compare)
+				}
+			end
+	
+			# set user-status (should only be used by Butler::IRC::Parser)
+			def status=(status) #:nodoc:
+				raise ArgumentError, "Invalid status #{status}" unless USER_STATUS.include?(status)
+				@status	= status unless @status == :myself
+			end
+	
+			# set away status (should only be used by Butler::IRC::Parser)
+			def away=(is_away) #:nodoc:
+				@is_away = is_away
+			end
+	
+			# check if user has op (+o) in given channel (String or Butler::IRC::Channel)		
+			def op?(in_channel)
+				!(@channels[in_channel.to_str.downcase] & OP).zero?
+			end
+	
+			# check if user has voice (+v) in given channel (String or Butler::IRC::Channel)		
+			def voice?(in_channel)
+				!(@channels[in_channel.to_str.downcase] & VOICE).zero?
+			end
+	
+			# check if user has uop (+u) in given channel (String or Butler::IRC::Channel)		
+			def uop?(in_channel)
+				!(@channels[in_channel.to_str.downcase] & UOP).zero?
+			end
+			
+			def in_channel?(channel)
+				@channels.has_key?(channel.to_str.downcase)
+			end
+	
+			# check if user is away
+			def is_away?
+				@is_away
+			end
+	
+			# retrieve away message
+			def away_message
+				@away_message
+			end
+	
+			# set away message (should only be used by Butler::IRC::Parser)
+			def away_message=(message) #:nodoc:
+				@away_message	= message.freeze
+			end
+	
+			def common_channels(with_other_user)
+				@channels.keys & with_other_user.channel_names
+			end
+			
+			def common_channels?(with_other_user)
+				!common_channels(with_other_user).empty?
+			end
+	
+			# FIXME
+			# add a channel to the user (should only be used by Butler::IRC::Parser)
+			def add_channel(channel, reason)
+				@channels[channel.to_str.downcase] ||= 0
+				if @status != :myself && [:out_of_sight, :unknown, :offline].include?(@status) && common_channels?(@users.myself) then
+					self.status	= :online
+				end
+				self
+			end
+	
+			# FIXME
+			# remove a channel from the user (should only be used by Butler::IRC::Parser)
+			def delete_channel(channel, reason)
+				@channels.delete(channel.to_str.downcase)
+				if @channels.empty? && ![:out_of_sight, :unknown, :myself].include?(@status) then
+					self.status	= :out_of_sight
+				end
+			end
+	
+			# FIXME
+			def add_flags(channel, flags)
+				channel = channel.to_str.downcase
+				raise ArgumentError, "User #{self} is not listed in #{channel}" unless @channels.include?(channel)
+				@channels[channel] |= flags
+			end
+	
+			# FIXME
+			def delete_flags(channel, flags)
+				channel = channel.to_str.downcase
+				raise ArgumentError, "User #{self} is not listed in #{channel}" unless @channels.include?(channel)
+				@channels[channel] &= ~flags
+			end
+			
+			# FIXME
+			def quit
+				@channels.each { |channel, _| delete_channel(channel, :quit) }
+				self.status	= :offline
+				@users.delete(self, :quit)
+			end
+	
+			# FIXME
+			def kill
+				@channels.each { |channel, _| delete_channel(channel, :kill) }
+				self.status	= :offline
+				@users.delete(self, :kill)
+			end
+	
+			# Returns the (frozen!) nickname of the user
+			def to_s
+				@nick
+			end
+
+			# :nodoc: string representation of Butler::IRC::User (nickname)
+			def to_str
+				@compare
+			end
+			
+			# same Butler::IRC::User?
+			# FIXME, might require stricter comparison for IRC::User objects
+			def ==(other)
+				if other.kind_of?(User) then
+					(
+						(!(@nick && other.nick) || @compare == other.compare) &&
+						(!(@user && other.user) || @user == other.user) &&
+						(!(@host && other.host) || @host == other.host) &&
+						(!(@real && other.real) || @real == other.real)
+					)
+				else
+					@compare == other.to_str.downcase
+				end
+			end
+			
+			# Matching nickname to a regular expression.
+			# Same as User#to_s =~ /regular expression/
+			def =~(regex)
+				@nick =~ regex
+			end
+	
+			# Lowercase String-comparison of nicknames.
+			# accepts everything that responds to :to_str
+			def ===(other)
+				@nick && @compare === other
+			end
+	
+			# Compares nicknames
+			def <=>(other)
+				@compare <=> other.to_str.downcase
+			end
+	
+			def inspect
+				"#<%s:0x%x %s!%s@%s (%s)>" %  [self.class, object_id, @nick || "?", @user || "?", @host || "?", @real || "?"]
+			end
+			
+			undef_method(:dup)
+			undef_method(:clone)
+		end # User
+	end
+end
+
+class Fixnum
+	# Return a String containing the user-prefixes for a flagset, e.g.
+	# (Flags::OP | Flags::Voice).to_user_prefixes # => "@-"
+	def to_user_prefixes
+		result = ""
+		Butler::IRC::User::PREFIXES.each { |char, value|
+			result += char unless (self & value).zero?
+		}
+		return result
+	end
+end

data/lib/butler/irc/users.rb

@@ -0,0 +1,112 @@
+#--
+# Copyright 2007 by Stefan Rusterholz.
+# All rights reserved.
+# See LICENSE.txt for permissions.
+#++
+
+
+
+require 'butler/irc/channels'
+require 'butler/irc/string'
+require 'butler/irc/user'
+require 'thread'
+
+
+
+class Butler
+	module IRC
+		# Enumerable: all known & visible users
+		class Users
+			include Enumerable
+	
+			# the user that represents the clients user
+			attr_reader :myself
+			# provides a global (within Butler::IRC::User) mutex
+			attr_reader :lock
+	
+			def initialize(client)
+				@client   = client
+				@users    = {}
+				@lost     = {}
+				@lock     = Mutex.new
+				@myself   = nil
+				@channels = nil
+			end
+			
+			def channels=(channels)
+				raise "Can't set @channels twice" if @channels
+				@channels = channels
+			end
+
+			def map_nicks(*nicks)
+				@users.values_at(*nicks)
+			end
+	
+			def create_myself(nick, user, real)
+				@myself = create(nick, nil, nil, nil)
+				@myself.status	= :myself
+			end
+			
+			def create(nick, *args)
+				@lock.synchronize {
+					new_user	= User.new(self, @channels, nick, *args)
+					old_user	= self[nick]
+					if old_user == new_user then
+						old_user.update(*args)
+						old_user
+
+					elsif !old_user then
+						@users[new_user.compare]	= new_user
+
+					# if old user was out of sight the new user overrides the old
+					elsif old_user.status == :out_of_sight || old_user.status == :unknown then
+						@users.delete(old_user.compare)
+						@users[new_user.compare]	= new_user
+
+					else # Should NOT happen
+						old_user.status = :mutated
+						@users.delete(old_user.compare)
+						@users[new_user.compare]	= new_user
+						raise "A user mutated #{old_user.inspect} -> #{new_user.inspect}"
+					end
+				}
+			end
+			
+			# list clones (comparing all known users)
+			def clones(strong=false, min=2)
+				sieve	= Hash.new { |h,k| h[k] = [] }
+				if strong then
+					each { |user|
+						sieve["#{user.user}@#{user.host}"] << user if (user.host && user.user)
+					}
+				else
+					each { |user|
+						sieve[user.host] << user if user.host
+					}
+				end
+				sieve.reject { |host, users| users.length < min }
+			end
+	
+			def each(&block)
+				@users.each_value(&block)
+			end
+			
+			def rehash(old_index, new_index)
+				@users[new_index]	= @users.delete(old_index)
+			end
+			
+			def delete(user, reason)
+				@users.delete(user.to_str.downcase)
+			end
+			
+			def delete_channel(channel, reason)
+				@users.each_value { |user| user.delete_channel(channel, reason) }
+			end
+			
+			# get a user by nick (may include user prefixes)
+			def [](nick)
+				@users[nick.to_str.strip_user_prefixes.downcase]
+			end
+		end
+	end
+end

data/lib/butler/plugin.rb

@@ -0,0 +1,249 @@
+#--
+# Copyright 2007 by Stefan Rusterholz.
+# All rights reserved.
+# See LICENSE.txt for permissions.
+#++
+
+
+
+require 'butler/plugin/configproxy'
+require 'butler/plugin/onhandlers'
+require 'butler/plugin/mapper'
+require 'butler/plugin/matcher'
+require 'butler/plugin/trigger'
+require 'log/comfort'
+require 'ostructfixed'
+require 'ruby/exception/detailed'
+require 'scriptfile'
+require 'templater'
+
+
+
+class Butler
+	class Plugin
+		class <<self
+			attr_reader :about
+			attr_reader :base
+			attr_reader :name
+			attr_reader :butler
+			attr_reader :config
+			attr_reader :help
+			attr_reader :path
+			attr_reader :strings
+			attr_reader :summary
+			attr_reader :usage
+	
+			# this method is called to initialize the plugin-class,
+			# do not override
+			def load_plugin(butler, base, path) # :nodoc:
+				@butler    = butler
+				@base      = base.dup.freeze
+				@name      = File.basename(base).freeze
+				@commands  = []
+				@listener  = []
+				@config    = ConfigProxy.new(@butler.config, "plugin.#{name}")
+	
+				if File.directory?(path) then
+					raise "Not supported yet" # FIXME
+					@path      = OpenStruct.new(
+						:data      => (@path+"/data").freeze,
+						:strings   => (@path+"/strings").freeze,
+						:requires  => (@path+"/requires").freeze
+					)
+				else
+					data         = YAML.load(ScriptFile.read(path)) || {}
+					@strings     = data[:strings] || {}
+					@about       = data[:about]   || {}
+					@help        = data[:help]    || {}
+					mappers      = data[:map]     || {}
+					@summary     = data[:summary] || {}
+					triggers     = data[:trigger] || nil
+					@usage       = data[:usage]   || {}
+					@path        = OpenStruct.new(
+						:data     => nil,
+						:strings  => nil,
+						:requires => nil
+					)
+				end
+
+				{:usage=>[@usage],:strings=>@strings.values,:help=>@help.values}.each { |key,tmpls|
+					tmpls.each { |tmpl|
+						create_templates(tmpl, key)
+					}
+				}
+				
+				mappers.each { |meth, expressions|
+					map(meth, expressions)
+				}
+				trigger(triggers) if triggers
+				
+				info("Loaded plugin '#{@base}' (#{self})")
+			end
+			
+			def create_templates(tmpl, name)
+				tmpl.each { |key,value|
+					begin
+						tmpl[key] = Templater.new(value)
+					rescue Exception => e
+						e.extend Exception::Detail
+						e.prepend "Could not map #{key} in #{@base} (#{name})."
+						exception(e)
+					end
+				}
+			end
+			
+			# initialize a configuration
+			def configuration(settings)
+				settings.each { |key, value|
+					@config[key] = value unless @config.has_key?(key)
+				}
+			end
+
+			# Will create an instance of the plugin and call usage on it
+			def plugin_usage(message, data={})
+				new(message).usage(data)
+			end
+
+			def on_load
+			end
+		
+			def trigger(commands)
+				commands = { "en" => commands } unless commands.kind_of?(Hash)
+				commands.each { |lang, command|
+					trigger = Trigger.new(self, lang, command)
+					@butler.add_command(trigger)
+					@commands << trigger
+				}
+			end
+
+			def map(meth, expressions)
+				expressions = { "en" => expressions } unless expressions.kind_of?(Hash)
+				expressions.each { |lang, expression|
+					mapper = Mapper.new(self, meth, lang, expression)
+					@butler.add_command(mapper)
+					@commands << mapper
+				}
+			end
+			
+			def every(*args, &block)
+				@butler.scheduler.every(*args, &block)
+			end
+
+			def at(*args, &block)
+				@butler.scheduler.at(*args, &block)
+			end
+
+			def timed(*args, &block)
+				@butler.scheduler.timed(*args, &block)
+			end
+
+			def subscribe(*args, &block)
+				listener = @butler.subscribe(*args, &block)
+				@listener << listener
+				listener
+			end
+
+			def on_unload
+			end
+
+			def unload_plugin
+				info("Unloading plugin '#{@base}' (#{self})")
+				@commands.each { |command| @butler.delete_command(command) }
+				@listener.each { |listener| listener.unsubscribe }
+			end
+			
+		end
+		
+		include Log::Comfort
+		extend Log::Comfort
+		
+		attr_reader :butler
+		attr_reader :message
+		
+		def initialize(message)
+			@butler  = plugin.butler
+			@message = message
+		end
+
+		alias plugin class
+
+		# gets the arguments and downcases if possible
+		def arguments(*params)
+			args = @message.arguments[*params]
+			if args.kind_of?(Array) then
+				args.map { |arg| arg.downcase }
+			elsif args then
+				args.downcase
+			else
+				nil
+			end
+		end
+
+		def localize(index, data={})
+			string   = plugin.strings[index]
+			string &&= (string[@message.language] || string["en"])
+			return "Unknown String '#{index}'" unless string
+			string.result(self, data)
+		end
+		alias _ localize
+
+		def usage(data={})
+			string = plugin.usage
+			if string = string[@message.language] || string["en"] then
+				("Usage '#{plugin.name}': #{@message.invocation}"+string.result(self, data)).mirc_formatted
+			else
+				"No usage provided"
+			end
+		end
+		
+		def unknown(n=-1)
+			"Unknown argument #{@message.arguments[n]} for #{@message.arguments[0...n].join(' ')}"
+		end
+		
+		# Only works if @message is set and conditions of Messag#answer are met.
+		# If string is a Symbol it considers it a key for localization, looks it up
+		# and translates it using vars as variables for the string interpolation.
+		# The string is subsequently mirc_formatted (see String#mirc_formatted).
+		# Besides that it works like Message#answer.
+		def answer(string, vars={})
+			string = localize(string, vars) if string.kind_of?(Symbol)
+			@message.answer(string.mirc_formatted)
+		end
+
+		# == About
+		# Sends a privmsg (localized and formatted) to any number of recipients
+		# (Users or Channels)
+		#
+		# == Synopsis
+		#   privmsg(:greet, "#some_channel", :from => @butler.myself.nick)
+		#
+		# == Description
+		# If string is a Symbol it considers it a key for localization, looks it up
+		# and translates it using the last argument as variables for the string
+		# interpolation, iff the last argument is a Hash.
+		# The string is subsequently mirc_formatted (see String#mirc_formatted).
+		def privmsg(string, *args)
+			vars   = args.last.kind_of?(Hash) ? args.pop : {}
+			string = localize(string, vars) if string.kind_of?(Symbol)
+			@butler.privmsg(string.mirc_formatted, *args)
+		end
+
+		# == About
+		# Sends a notice (localized and formatted) to any number of recipients
+		# (Users or Channels)
+		#
+		# == Synopsis
+		#   notice(:greet, "#some_channel", :from => @butler.myself.nick)
+		#
+		# == Description
+		# If string is a Symbol it considers it a key for localization, looks it up
+		# and translates it using the last argument as variables for the string
+		# interpolation, iff the last argument is a Hash.
+		# The string is subsequently mirc_formatted (see String#mirc_formatted).
+		def notice(string, *args)
+			vars   = args.last.kind_of?(Hash) ? args.pop : {}
+			string = localize(string, vars) if string.kind_of?(Symbol)
+			@butler.notice(string.mirc_formatted, *args)
+		end
+	end
+end