cinch 1.1.3 → 2.0.0.pre.1

data/lib/cinch/{cache_manager.rb → cached_list.rb}

@@ -1,5 +1,9 @@
 module Cinch
-  class CacheManager
+  # @api private
+  # @since 2.0.0
+  # @version 1.1.0
+  # @note In prior versions, this class was called CacheManager
+  class CachedList
     include Enumerable
 
     def initialize(bot)

data/lib/cinch/callback.rb

@@ -1,4 +1,7 @@
 module Cinch
+  # Class used for encapsulating handlers to prevent them from
+  # overwriting instance variables in {Bot}
+  #
   # @api private
   class Callback
     include Helpers

data/lib/cinch/channel.rb

@@ -1,62 +1,24 @@
 # -*- coding: utf-8 -*-
 require "set"
+require "cinch/target"
 
 module Cinch
-  class Channel
+  # @attr limit
+  # @attr secret
+  # @attr moderated
+  # @attr invite_only
+  # @attr key
+  #
+  # @version 2.0.0
+  class Channel < Target
     include Syncable
-    @channels = {}
-
-    class << self
-      # Finds or creates a channel.
-      #
-      # @param [String] name name of a channel
-      # @param [Bot] bot a bot
-      # @return [Channel]
-      # @see Bot#Channel
-      # @deprecated See {Bot#channel_manager} and {ChannelManager#find_ensured} instead
-      # @note This method does not work properly if running more than one bot
-      # @note This method will be removed in Cinch 2.0.0
-      def find_ensured(name, bot)
-        $stderr.puts "Deprecation warning: Beginning with version 1.1.0, Channel.find_ensured should not be used anymore."
-        puts caller
-
-        downcased_name = name.irc_downcase(bot.irc.isupport["CASEMAPPING"])
-        @channels[downcased_name] ||= bot.channel_manager.find_ensured(name)
-      end
-
-      # Finds a channel.
-      #
-      # @param [String] name name of a channel
-      # @return [Channel, nil]
-      # @deprecated See {Bot#channel_manager} and {ChannelManager#find} instead
-      # @note This method does not work properly if running more than one bot
-      # @note This method will be removed in Cinch 2.0.0
-      def find(name)
-        $stderr.puts "Deprecation warning: Beginning with version 1.1.0, Channel.find should not be used anymore."
-        puts caller
-
-        @channels[name]
-      end
-
-      # @return [Array<Channel>] Returns all channels
-      # @deprecated See {Bot#channel_manager} and {CacheManager#each} instead
-      # @note This method does not work properly if running more than one bot
-      # @note This method will be removed in Cinch 2.0.0
-      def all
-        $stderr.puts "Deprecation warning: Beginning with version 1.1.0, User.all should not be used anymore."
-        puts caller
-
-        @channels.values
-      end
-    end
-
-    # @return [Bot]
-    attr_reader :bot
-
-    # @return [String] the channel's name
-    attr_reader :name
+    include Helpers
 
-    # @return [Array<User>] all users in the channel
+    # Users are represented by a Hash, mapping individual users to an
+    # array of modes (e.g. "o" for opped).
+    #
+    # @return [Hash<User => Array<String>>] all users in the channel
+    # @version 1.1.0
     attr_reader :users
     synced_attr_reader :users
 
@@ -68,6 +30,16 @@ module Cinch
     attr_reader :bans
     synced_attr_reader :bans
 
+    # @return [Array<User>] all channel owners
+    # @note Only some networks implement this
+    attr_reader :owners
+    synced_attr_reader :owners
+
+    # This attribute describes all modes set in the channel. They're
+    # represented as a Hash, mapping the mode (e.g. "i", "k", …) to
+    # either a value in the case of modes that take an option (e.g.
+    # "k" for the channel key) or true.
+    #
     # @return [Hash<String => Object>]
     attr_reader :modes
     synced_attr_reader :modes
@@ -76,6 +48,7 @@ module Cinch
       @name  = name
       @users = Hash.new {|h,k| h[k] = []}
       @bans  = []
+      @owners = []
 
       @modes = {}
       # TODO raise if not a channel
@@ -90,13 +63,21 @@ module Cinch
           unsync(attr)
           case attr
           when :users
-            @bot.raw "NAMES #@name"
+            @bot.irc.send "NAMES #@name"
           when :topic
-            @bot.raw "TOPIC #@name"
+            @bot.irc.send "TOPIC #@name"
           when :bans
-            @bot.raw "MODE #@name +b"
+            @bot.irc.send "MODE #@name +b"
+          when :owners
+            if @bot.irc.network.owner_list_mode
+              @bot.irc.send "MODE #@name +#{@bot.irc.network.owner_list_mode}"
+            else
+              # the current IRCd does not support channel owners, so
+              # just mark the empty array as synced
+              mark_as_synced(:owners)
+            end
           when :modes
-            @bot.raw "MODE #@name"
+            @bot.irc.send "MODE #@name"
           end
         end
       }
@@ -106,37 +87,60 @@ module Cinch
 
     # @param [User, String] user An {User}-object or a nickname
     # @return [Boolean] Check if a user is in the channel
+    # @since 1.1.0
+    # @version 1.1.2
     def has_user?(user)
-      user = @bot.user_manager.find_ensured(user) unless user.is_a?(User)
-      @users.has_key?(user)
+      @users.has_key?(User(user))
     end
 
-
     # @return [Boolean] true if `user` is opped in the channel
+    # @since 1.1.0
     def opped?(user)
-      user = @bot.user_manager.find_ensured(user) unless user.is_a?(User)
-      @users[user].include? "o"
+      @users[User(user)].include? "o"
     end
 
     # @return [Boolean] true if `user` is half-opped in the channel
+    # @since 1.1.0
     def half_opped?(user)
-      user = @bot.user_manager.find_ensured(user) unless user.is_a?(User)
-      @users[user].include? "h"
+      @users[User(user)].include? "h"
     end
 
     # @return [Boolean] true if `user` is voiced in the channel
+    # @since 1.1.0
     def voiced?(user)
-      user = @bot.user_manager.find_ensured(user) unless user.is_a?(User)
-      @users[user].include? "v"
+      @users[User(user)].include? "v"
+    end
+
+    # @endgroup
+
+    # @group User groups
+    # @return [Array<User>] All ops in the channel
+    # @since 2.0.0
+    def ops
+      @users.select {|user, modes| modes.include?("o")}.keys
     end
 
+    # @return [Array<User>] All half-ops in the channel
+    # @since 2.0.0
+    def half_ops
+      @users.select {|user, modes| modes.include?("h")}.keys
+    end
+
+    # @return [Array<User>] All voiced users in the channel
+    # @since 2.0.0
+    def voiced
+      @users.select {|user, modes| modes.include?("v")}.keys
+    end
+
+    # @return [Array<User>] All admins in the channel
+    # @since 2.0.0
+    def admins
+      @users.select {|user, modes| modes.include?("a")}.keys
+    end
     # @endgroup
 
     # @return [Number] The maximum number of allowed users in the
     #   channel. 0 if unlimited.
-    attr_accessor :limit
-    undef_method "limit"
-    undef_method "limit="
     def limit
       @modes["l"].to_i
     end
@@ -150,9 +154,6 @@ module Cinch
     end
 
     # @return [Boolean] true if the channel is secret (+s)
-    attr_accessor :secret
-    undef_method "secret"
-    undef_method "secret="
     def secret
       @modes["s"]
     end
@@ -166,17 +167,13 @@ module Cinch
       end
     end
 
-    # @return [Boolean] true if the channel is moderated (only users
-    #   with +o and +v are able to send messages)
-    attr_accessor :moderated
-    undef_method "moderated"
-    undef_method "moderated="
+    # @return [Boolean] true if the channel is moderated
     def moderated
       @modes["m"]
     end
     alias_method :moderated?, :moderated
 
-    def moderated=(val)
+    def moderated=(bool)
       if bool
         mode "+m"
       else
@@ -185,9 +182,6 @@ module Cinch
     end
 
     # @return [Boolean] true if the channel is invite only (+i)
-    attr_accessor :invite_only
-    undef_method "invite_only"
-    undef_method "invite_only="
     def invite_only
       @modes["i"]
     end
@@ -202,9 +196,6 @@ module Cinch
     end
 
     # @return [String, nil] The channel's key (aka password)
-    attr_accessor :key
-    undef_method "key"
-    undef_method "key="
     def key
       @modes["k"]
     end
@@ -219,61 +210,82 @@ module Cinch
 
     # @api private
     # @return [void]
-    def sync_modes(all = true)
+    def sync_modes
       unsync :users
       unsync :bans
       unsync :modes
-      @bot.raw "NAMES #@name" if all
-      @bot.raw "MODE #@name +b" # bans
-      @bot.raw "MODE #@name"
+      unsync :owners
+
+      if @bot.irc.isupport["WHOX"]
+        @bot.irc.send "WHO #@name %acfhnru"
+      else
+        @bot.irc.send "WHO #@name"
+      end
+      @bot.irc.send "MODE #@name +b" # bans
+      @bot.irc.send "MODE #@name"
+      if @bot.irc.network.owner_list_mode
+        @bot.irc.send "MODE #@name +#{@bot.irc.network.owner_list_mode}"
+      else
+        mark_as_synced :owners
+      end
     end
 
     # @group Channel Manipulation
 
     # Bans someone from the channel.
     #
-    # @param [Ban, Mask, User, String] target the mask to ban
+    # @param [Mask, String, #mask] target the mask, or an object having a mask, to ban
     # @return [Mask] the mask used for banning
+    # @see #unban #unban for unbanning users
     def ban(target)
       mask = Mask.from(target)
 
-      @bot.raw "MODE #@name +b #{mask}"
+      @bot.irc.send "MODE #@name +b #{mask}"
       mask
     end
 
     # Unbans someone from the channel.
     #
-    # @param [Ban, Mask, User, String] target the mask to unban
+    # @param [Mask, String, #mask] target the mask to unban
     # @return [Mask] the mask used for unbanning
+    # @see #ban #ban for banning users
     def unban(target)
       mask = Mask.from(target)
 
-      @bot.raw "MODE #@name -b #{mask}"
+      @bot.irc.send "MODE #@name -b #{mask}"
       mask
     end
 
+    # Ops a user.
+    #
     # @param [String, User] user the user to op
     # @return [void]
     def op(user)
-      @bot.raw "MODE #@name +o #{user}"
+      @bot.irc.send "MODE #@name +o #{user}"
     end
 
+    # Deops a user.
+    #
     # @param [String, User] user the user to deop
     # @return [void]
     def deop(user)
-      @bot.raw "MODE #@name -o #{user}"
+      @bot.irc.send "MODE #@name -o #{user}"
     end
 
+    # Voices a user.
+    #
     # @param [String, User] user the user to voice
     # @return [void]
     def voice(user)
-      @bot.raw "MODE #@name +v #{user}"
+      @bot.irc.send "MODE #@name +v #{user}"
     end
 
+    # Devoices a user.
+    #
     # @param [String, User] user the user to devoice
     # @return [void]
     def devoice(user)
-      @bot.raw "MODE #@name -v #{user}"
+      @bot.irc.send "MODE #@name -v #{user}"
     end
 
     # Invites a user to the channel.
@@ -281,19 +293,20 @@ module Cinch
     # @param [String, User] user the user to invite
     # @return [void]
     def invite(user)
-      @bot.raw("INVITE #{user} #@name")
+      @bot.irc.send("INVITE #{user} #@name")
     end
 
     # Sets the topic.
     #
     # @param [String] new_topic the new topic
-    # @raise [Exceptions::TopicTooLong]
+    # @raise [Exceptions::TopicTooLong] Raised if the bot is operating
+    #   in {Bot#strict? strict mode} and when the new topic is too long.
     def topic=(new_topic)
       if new_topic.size > @bot.irc.isupport["TOPICLEN"] && @bot.strict?
         raise Exceptions::TopicTooLong, new_topic
       end
 
-      @bot.raw "TOPIC #@name :#{new_topic}"
+      @bot.irc.send "TOPIC #@name :#{new_topic}"
     end
 
     # Kicks a user from the channel.
@@ -307,7 +320,7 @@ module Cinch
         raise Exceptions::KickReasonTooLong, reason
       end
 
-      @bot.raw("KICK #@name #{user} :#{reason}")
+      @bot.irc.send("KICK #@name #{user} :#{reason}")
     end
 
     # Sets or unsets modes. Most of the time you won't need this but
@@ -318,7 +331,7 @@ module Cinch
     # @example
     #   channel.mode "+n"
     def mode(s)
-      @bot.raw "MODE #@name #{s}"
+      @bot.irc.send "MODE #@name #{s}"
     end
 
     # Causes the bot to part from the channel.
@@ -326,7 +339,7 @@ module Cinch
     # @param [String] message the part message.
     # @return [void]
     def part(message = nil)
-      @bot.raw "PART #@name :#{message}"
+      @bot.irc.send "PART #@name :#{message}"
     end
 
     # Joins the channel
@@ -338,20 +351,21 @@ module Cinch
       if key.nil? and self.key != true
         key = self.key
       end
-      @bot.raw "JOIN #{[@name, key].compact.join(" ")}"
+      @bot.irc.send "JOIN #{[@name, key].compact.join(" ")}"
     end
 
     # @endgroup
 
     # @api private
-    # @return [void]
+    # @return [User] The added user
     def add_user(user, modes = [])
       @in_channel = true if user == @bot
       @users[user] = modes
+      user
     end
 
     # @api private
-    # @return [void]
+    # @return [User, nil] The removed user
     def remove_user(user)
       @in_channel = false if user == @bot
       @users.delete(user)
@@ -365,96 +379,6 @@ module Cinch
       @users.clear
     end
 
-    # @group Sending messages
-
-    # Send a message to the channel.
-    #
-    # @param [String] message the message
-    # @return [void]
-    # @see #safe_send
-    def send(message)
-      @bot.msg(@name, message)
-    end
-    alias_method :privmsg, :send
-    alias_method :msg, :send
-
-    # Send a notice to the channel.
-    #
-    # @param [String] message the message
-    # @return [void]
-    def notice(message)
-      @bot.notice(@name, message)
-    end
-
-    # Like {#safe_send} but for notices.
-    #
-    # @param (see #safe_send)
-    # @return (see #safe_send)
-    # @see #safe_send
-    # @todo (see #safe_send)
-    def safe_notice(message)
-      @bot.safe_notice(@name, message)
-    end
-
-    # Send a message to the channel, but remove any non-printable
-    # characters. The purpose of this method is to send text from
-    # untrusted sources, like other users or feeds.
-    #
-    # Note: this will **break** any mIRC color codes embedded in the
-    # string.
-    #
-    # @param (see #send)
-    # @return (see #send)
-    # @see #send
-    # @todo Handle mIRC color codes more gracefully.
-    def safe_send(message)
-      @bot.safe_msg(@name, message)
-    end
-    alias_method :safe_privmsg, :safe_send
-    alias_method :safe_msg, :safe_send
-
-
-
-    # Send a CTCP to the channel.
-    #
-    # @param [String] message the ctcp message
-    # @return [void]
-    def ctcp(message)
-      send "\001#{message}\001"
-    end
-
-    # Invoke an action (/me) in the channel.
-    #
-    # @param [String] message the message
-    # @return [void]
-    # @see #safe_action
-    def action(message)
-      @bot.action(@name, message)
-    end
-
-    # Invoke an action (/me) in the channel but remove any
-    # non-printable characters. The purpose of this method is to send
-    # text from untrusted sources, like other users or feeds.
-    #
-    # Note: this will **break** any mIRC color codes embedded in the
-    # string.
-    #
-    # @param (see #action)
-    # @return (see #action)
-    # @see #action
-    # @todo Handle mIRC color codes more gracefully.
-    def safe_action(message)
-      @bot.safe_action(@name, message)
-    end
-
-    # @endgroup
-
-    # @return [Boolean]
-    def ==(other)
-      @name == other.to_s
-    end
-    alias_method :eql?, "=="
-
     # @return [Fixnum]
     def hash
       @name.hash