cinch 1.1.3 → 2.0.0.pre.1

data/lib/cinch/target.rb

@@ -0,0 +1,144 @@
+module Cinch
+  # @since 2.0.0
+  class Target
+    include Comparable
+
+    # @return [String]
+    attr_reader :name
+    # @return [Bot]
+    attr_reader :bot
+    def initialize(name, bot)
+      @name = name
+      @bot  = bot
+    end
+
+    # Sends a NOTICE to the target.
+    #
+    # @param [#to_s] text the message to send
+    # @return [void]
+    # @see #safe_notice
+    def notice(text)
+      msg(text, true)
+    end
+
+    # Sends a PRIVMSG to the target.
+    #
+    # @param [#to_s] text the message to send
+    # @param [Boolean] notice Use NOTICE instead of PRIVMSG?
+    # @return [void]
+    # @see #safe_msg
+    def msg(text, notice = false)
+      text = text.to_s
+      split_start = @bot.config.message_split_start || ""
+      split_end   = @bot.config.message_split_end   || ""
+      command = notice ? "NOTICE" : "PRIVMSG"
+
+      text.split(/\r\n|\r|\n/).each do |line|
+        maxlength = 510 - (":" + " #{command} " + " :").size
+        maxlength = maxlength - @bot.mask.to_s.length - @name.to_s.length
+        maxlength_without_end = maxlength - split_end.bytesize
+
+        if line.bytesize > maxlength
+          splitted = []
+
+          while line.bytesize > maxlength_without_end
+            pos = line.rindex(/\s/, maxlength_without_end)
+            r = pos || maxlength_without_end
+            splitted << line.slice!(0, r) + split_end.tr(" ", "\u00A0")
+            line = split_start.tr(" ", "\u00A0") + line.lstrip
+          end
+
+          splitted << line
+          splitted[0, (@bot.config.max_messages || splitted.size)].each do |string|
+            string.tr!("\u00A0", " ") # clean string from any non-breaking spaces
+            @bot.irc.send("#{command} #@name :#{string}")
+          end
+        else
+          @bot.irc.send("#{command} #@name :#{line}")
+        end
+      end
+    end
+    alias_method :send, :msg
+    alias_method :privmsg, :msg
+
+    # Like {#msg}, but remove any non-printable characters from
+    # `text`. The purpose of this method is to send text of untrusted
+    # sources, like other users or feeds.
+    #
+    # Note: this will **break** any mIRC color codes embedded in the
+    # string.
+    #
+    # @return (see #msg)
+    # @param (see #msg)
+    # @see #msg
+    # @todo Handle mIRC color codes more gracefully.
+    def safe_msg(text, notice = false)
+      msg(Cinch::Utilities::String.filter_string(text), notice)
+    end
+    alias_method :safe_privmsg, :safe_msg
+    alias_method :safe_send, :safe_msg
+
+    # Like {#safe_msg} but for notices.
+    #
+    # @return (see #safe_msg)
+    # @param (see #safe_msg)
+    # @see #safe_notice
+    # @see #notice
+    # @todo (see #safe_msg)
+    def safe_notice(text)
+      safe_msg(text, true)
+    end
+
+    # Invoke an action (/me) in/to the target.
+    #
+    # @param [#to_s] text the message to send
+    # @return [void]
+    # @see #safe_action
+    def action(text)
+      @bot.irc.send("PRIVMSG #@name :\001ACTION #{text}\001")
+    end
+
+    # Like {#action}, but remove any non-printable characters from
+    # `text`. 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(text)
+      action(Cinch::Utilities::String.filter_string(text))
+    end
+
+    # Send a CTCP to the target.
+    #
+    # @param [#to_s] message the ctcp message
+    # @return [void]
+    def ctcp(message)
+      send "\001#{message}\001"
+    end
+
+    # @return [Boolean]
+    def eql?(other)
+      self == other
+    end
+
+    # @param [Target, String]
+    # @return [-1, 0, 1, nil]
+    def <=>(other)
+      casemapping = @bot.irc.isupport["CASEMAPPING"]
+      left = @name.irc_downcase(casemapping)
+
+      if other.is_a?(Target)
+        left <=> other.name.irc_downcase(casemapping)
+      elsif other.is_a?(String)
+        left <=> other.irc_downcase(casemapping)
+      else
+        nil
+      end
+    end
+  end
+end

data/lib/cinch/timer.rb

@@ -0,0 +1,145 @@
+require "cinch/helpers"
+
+module Cinch
+  # Timers are used for executing code in the future, either
+  # repeatedly or only once.
+  #
+  # In Cinch, two ways for creating timers are available:
+  #
+  # - The first way is by declaring them for a plugin, in which case
+  #   they will start as soon as the bot connects to a server.
+  #
+  # - The second way is to dynamically create new timers in response
+  #   to user input. A common example for this is an alarm clock
+  #   plugin, which has to execute at a specific time.
+  #
+  # @see Helpers#Timer For dynamically creating timers
+  # @see Plugin::ClassMethods#timer For declaring timers in plugins
+  # @note It is possible to directly create instances of this class,
+  #   but the referenced methods should suffice.
+  # @since 2.0.0
+  class Timer
+    include Helpers
+
+    # @return [Bot]
+    attr_reader :bot
+
+    # @return [Number] The interval (in seconds) of the timer
+    attr_accessor :interval
+
+    # @return [Boolean] If true, each invocation will be
+    #   executed in a thread of its own.
+    attr_accessor :threaded
+
+    # @return [Proc]
+    attr_reader :block
+
+    # @return [Boolean]
+    attr_reader :started
+
+    # @return [Number] The remaining number of shots before this timer
+    #   will stop. This value will automatically reset after
+    #   restarting the timer.
+    attr_accessor :shots
+    alias_method :threaded?, :threaded
+    alias_method :started?, :started
+
+    # @return [ThreadGroup]
+    # @api private
+    attr_reader :thread_group
+
+    # @param [Bot] bot The instance of {Bot} the timer is associated
+    #   with
+    # @option options [Number] :interval The interval (in seconds) of
+    #   the timer
+    # @option options [Number] :shots (Float::INFINITY) How often should the
+    #   timer fire?
+    # @option options [Boolean] :threaded (true) If true, each invocation will be
+    #   executed in a thread of its own.
+    # @option options [Boolean] :start_automatically (true) If true,
+    #   the timer will automatically start after the bot finished
+    #   connecting.
+    # @option options [Boolean] :stop_automaticall (true) If true, the
+    #   timer will automatically stop when the bot disconnects.
+    def initialize(bot, options, &block)
+      options = {:threaded => true, :shots => Float::INFINITY, :start_automatically => true, :stop_automatically => true}.merge(options)
+
+      @bot        = bot
+      @interval   = options[:interval].to_f
+      @threaded   = options[:threaded]
+      @orig_shots = options[:shots]
+      # Setting @shots here so the attr_reader won't return nil
+      @shots      = @orig_shots
+      @block      = block
+
+      @started = false
+      @thread_group = ThreadGroup.new
+
+      if options[:start_automatically]
+        @bot.on :connect, //, self do |m, timer|
+          timer.start
+        end
+      end
+
+      if options[:stop_automatically]
+        @bot.on :disconnect, //, self do |m, timer|
+          timer.stop
+        end
+      end
+    end
+
+    # @return [Boolean]
+    def stopped?
+      !@started
+    end
+
+    # Start the timer
+    #
+    # @return [void]
+    def start
+      return if @started
+
+      @bot.loggers.debug "[timer] Starting timer #{self}"
+
+      @shots = @orig_shots
+
+      @thread_group.add Thread.new {
+        while @shots > 0 do
+          sleep @interval
+          if threaded?
+            Thread.new do
+              rescue_exception do
+                @block.call
+              end
+            end
+          else
+            rescue_exception do
+              @block.call
+            end
+          end
+
+          @shots -= 1
+        end
+      }
+
+      @started = true
+    end
+
+    # Stop the timer
+    #
+    # @return [void]
+    def stop
+      return unless @started
+
+      @bot.loggers.debug "[timer] Stopping timer #{self}"
+
+      @thread_group.list.each { |thread| thread.kill }
+      @started = false
+    end
+
+    # @return [String]
+    def to_s
+      "<Cinch::Timer %s/%s shots, %ds interval, %sthreaded, %sstarted, block: %s>" % [@orig_shots - @shots, @orig_shots, @interval, @threaded ? "" : "not ", @started ? "" : "not ", @block]
+    end
+  end
+end

data/lib/cinch/user.rb

@@ -1,117 +1,38 @@
 # -*- coding: utf-8 -*-
+require "cinch/target"
+require "timeout"
+
 module Cinch
-  class User
+  # @attr_reader [String] user
+  # @attr_reader [String] host
+  # @attr_reader [String] realname
+  # @attr_reader [String] authname
+  # @attr_reader [Number] idle How long this user has been idle, in seconds.
+  #   This is a snapshot of the last WHOIS.
+  # @attr_reader [Time] signed_on_at
+  # @attr_reader [Array<Channel>] channels All channels the user is in.
+  # @attr_reader [String, nil] away The user's away message, or
+  #   `nil` if not away.
+  #
+  # @version 2.0.0
+  class User < Target
     include Syncable
 
-    @users = {} # this will be removed with version 2.0.0
-    class << self
-
-      # @overload find_ensured(nick, bot)
-      #   Finds or creates a user based on his nick.
-      #
-      #   @param [String] nick The user's nickname
-      #   @param [Bot]    bot  An instance of Bot
-      # @overload find_ensured(user, nick, host, bot)
-      #   Finds or creates a user based on his nick but already
-      #   setting user and host.
-      #
-      #   @param [String] user The username
-      #   @param [String] nick The nickname
-      #   @param [String] host The user's hostname
-      #   @param [Bot]    bot  An instance of bot
-      #
-      # @return [User]
-      # @deprecated See {Bot#user_manager} and {UserManager#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(*args)
-        $stderr.puts "Deprecation warning: Beginning with version 1.1.0, User.find_ensured should not be used anymore."
-        puts caller
-
-        case args.size
-        when 2
-          nick = args.first
-          bot  = args.last
-          bargs = [nick]
-        when 4
-          nick = args[1]
-          bot  = args.pop
-          bargs = args
-        else
-          raise ArgumentError
-        end
-        downcased_nick = nick.irc_downcase(bot.irc.isupport["CASEMAPPING"])
-        @users[downcased_nick] = args.last.user_manager.find_ensured(*args[0..-2])
-        # note: the complete case statement and the assignment to
-        #   @users is only for keeping compatibility with older
-        #   versions, which still use User.find and User.all.
-      end
-
-      # Finds a user.
-      #
-      # @param [String] nick nick of a user
-      # @return [User, nil]
-      # @deprecated See {Bot#user_manager} and {UserManager#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(nick)
-        $stderr.puts "Deprecation warning: Beginning with version 1.1.0, User.find should not be used anymore."
-        puts caller
-
-        @users[downcased_nick]
-      end
-
-      # @return [Array<User>] Returns all users
-      # @deprecated See {Bot#user_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
-
-        @users.values
-      end
-    end
-
+    alias_method :nick, :name
 
     # @return [String]
-    attr_reader :nick
-    # @return [String]
+    # @since 1.1.0
     attr_reader :last_nick
-    # @return [Bot]
-    attr_reader :bot
+
     # @return [Boolean]
     attr_reader :synced
+
     # @return [Boolean]
     attr_reader :in_whois
+
     # @api private
     attr_writer :in_whois
 
-    # @return [String]
-    attr_reader :user
-    undef_method "user"
-
-    # @return [String]
-    attr_reader :host
-    undef_method "host"
-
-    # @return [String]
-    attr_reader :realname
-    undef_method "realname"
-
-    # @return [String]
-    attr_reader :authname
-    undef_method "authname"
-
-    # @return [Number] How long this user has been idle, in seconds.
-    #   This is a snapshot of the last WHOIS.
-    attr_reader :idle
-    undef_method "idle"
-
-    # @return [Time]
-    attr_reader :signed_on_at
-    undef_method "signed_on_at"
-
     # @return [Boolean] True if the instance references an user who
     #   cannot be found on the server.
     attr_reader :unknown
@@ -122,9 +43,17 @@ module Cinch
       self.unknown?
     end
 
-    # @return [Array<Channel>] All channels the user is in.
-    attr_reader :channels
-    undef_method "channels"
+    # @return [Boolean] True if the user is online.
+    # @note This attribute will be updated by various events, but
+    # unless {#monitor} is being used, this information cannot be
+    # ensured to be always correct.
+    attr_reader :online
+    alias_method :online?, :online
+    undef_method "online?"
+    undef_method "online"
+    def online
+      self.online?
+    end
 
     # @return [Boolean] True if the user is using a secure connection, i.e. SSL.
     attr_reader :secure
@@ -149,6 +78,16 @@ module Cinch
     #   end
     # @return [Hash]
     attr_reader :data
+
+    # @return [Boolean] True if the user is being monitored
+    # @see #monitor
+    # @see #unmonitor
+    attr_reader :monitored
+
+    # @api private
+    attr_writer :monitored
+
+
     def initialize(*args)
       @data = {
         :user         => nil,
@@ -158,14 +97,16 @@ module Cinch
         :idle         => 0,
         :signed_on_at => nil,
         :unknown?     => false,
+        :online?      => false,
         :channels     => [],
         :secure?      => false,
+        :away         => nil,
       }
       case args.size
       when 2
-        @nick, @bot = args
+        @name, @bot = args
       when 4
-        @data[:user], @nick, @data[:host], @bot = args
+        @data[:user], @name, @data[:host], @bot = args
       else
         raise ArgumentError
       end
@@ -173,29 +114,26 @@ module Cinch
       @synced_attributes  = Set.new
 
       @when_requesting_synced_attribute = lambda {|attr|
-        unless @synced
+        unless synced?(attr)
           @data[:unknown?] = false
           unsync :unknown?
 
-          unsync attr
           whois
         end
       }
+
+      @monitored = false
     end
 
     # Checks if the user is identified. Currently officially supports
     # Quakenet and Freenode.
     #
     # @return [Boolean] true if the user is identified
+    # @version 1.1.0
     def authed?
       !attr(:authname).nil?
     end
 
-    # @see Syncable#attr
-    def attr(attribute, data = true, unsync = false)
-      super
-    end
-
     # Queries the IRC server for information on the user. This will
     # set the User's state to not synced. After all information are
     # received, the object will be set back to synced.
@@ -203,13 +141,16 @@ module Cinch
     # @return [void]
     def whois
       return if @in_whois
-      @synced = false
       @data.keys.each do |attr|
         unsync attr
       end
 
       @in_whois = true
-      @bot.raw "WHOIS #@nick #@nick"
+      if @bot.irc.network.whois_only_one_argument?
+        @bot.irc.send "WHOIS #@name"
+      else
+        @bot.irc.send "WHOIS #@name #@name"
+      end
     end
     alias_method :refresh, :whois
 
@@ -224,6 +165,7 @@ module Cinch
       @in_whois = false
       if not_found
         sync(:unknown?, true, true)
+        self.online = false
         sync(:idle, 0, true)
         sync(:channels, [], true)
 
@@ -257,7 +199,7 @@ module Cinch
       end
 
       sync(:unknown?, false, true)
-      @synced = true
+      self.online = true
     end
 
     # @return [void]
@@ -265,101 +207,17 @@ module Cinch
     # @api private
     # @see Syncable#unsync_all
     def unsync_all
-      @synced = false
       super
     end
 
-    # @group Sending messages
-
-    # Send a message to the user.
-    #
-    # @param [String] message the message
-    # @return [void]
-    def send(message)
-      @bot.msg(@nick, message)
-    end
-    alias_method :privmsg, :send
-    alias_method :msg, :send
-
-    # Send a notice to the user.
-    #
-    # @param [String] message the message
-    # @return [void]
-    def notice(message)
-      @bot.notice(@nick, 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(@nick, message)
-    end
-
-    # Send a message to the user, 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
-    # @see Bot#safe_msg
-    # @todo Handle mIRC color codes more gracefully.
-    def safe_send(message)
-      @bot.safe_msg(@nick, message)
-    end
-    alias_method :safe_privmsg, :safe_send
-    alias_method :safe_msg, :safe_send
-
-    # Send a CTCP to the user.
-    #
-    # @param [String] message the ctcp message
-    # @return [void]
-    def ctcp(message)
-      send "\001#{message}\001"
-    end
-
-    # Send an action (/me) to the user.
-    #
-    # @param [String] message the message
-    # @return [void]
-    # @see #safe_action
-    def action(message)
-      @bot.action(@name, message)
-    end
-
-    # Send an action (/me) to the user 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
-    # @see Bot#safe_action
-    # @todo Handle mIRC color codes more gracefully.
-    def safe_action(message)
-      @bot.safe_action(@name, message)
-    end
-
-    # @endgroup
-
     # @return [String]
     def to_s
-      @nick
+      @name
     end
 
     # @return [String]
     def inspect
-      "#<User nick=#{@nick.inspect}>"
+      "#<User nick=#{@name.inspect}>"
     end
 
     # Generates a mask for the user.
@@ -377,7 +235,7 @@ module Cinch
       s = s.gsub(/%(.)/) {
         case $1
         when "n"
-          @nick
+          @name
         when "u"
           self.user
         when "h"
@@ -392,10 +250,115 @@ module Cinch
       Mask.new(s)
     end
 
+    # Check if the user matches a mask.
+    #
+    # @param [Ban, Mask, User, String] other The user or mask to match against
+    # @return [Boolean]
+    def match(other)
+      Mask.from(other) =~ Mask.from(self)
+    end
+    alias_method :=~, :match
+
+    # Starts monitoring a user's online state by either using MONITOR
+    # or periodically running WHOIS.
+    #
+    # @since 2.0.0
+    # @return [void]
+    # @see #unmonitor
+    def monitor
+      if @bot.irc.isupport["MONITOR"] > 0
+        @bot.irc.send "MONITOR + #@name"
+      else
+        refresh
+        @monitored_timer = Timer.new(@bot, interval: 30) {
+          refresh
+        }.start
+      end
+
+      @monitored = true
+    end
+
+    # Stops monitoring a user's online state.
+    #
+    # @since 2.0.0
+    # @return [void]
+    # @see #monitor
+    def unmonitor
+      if @bot.irc.isupport["MONITOR"] > 0
+        @bot.irc.send "MONITOR - #@name"
+      else
+        @monitored_timer.stop
+      end
+
+      @monitored = false
+    end
+
+    # Send data via DCC SEND to a user.
+    #
+    # @param [DCC::DCCableObject] io
+    # @param [String] filename
+    # @since 2.0.0
+    # @return [void]
+    # @note This method blocks.
+    def dcc_send(io, filename = File.basename(io.path))
+      own_ip = bot.config.dcc.own_ip || @bot.irc.socket.addr[2]
+      dcc = DCC::Outgoing::Send.new(receiver: self,
+                                    filename: filename,
+                                    io: io,
+                                    own_ip: own_ip
+                                    )
+
+      dcc.start_server
+
+      handler = Handler.new(@bot, :message,
+                            Pattern.new(/^/,
+                                        /\001DCC RESUME #{filename} #{dcc.port} (\d+)\001/,
+                                        /$/)) do |m, position|
+        next unless m.user == self
+        dcc.seek(position.to_i)
+        m.user.send "\001DCC ACCEPT #{filename} #{dcc.port} #{position}\001"
+
+        handler.unregister
+      end
+      @bot.handlers.register(handler)
+
+      @bot.loggers.info "DCC: Outgoing DCC SEND: File name: %s - Size: %dB - IP: %s - Port: %d - Status: waiting" % [filename, io.size, own_ip, dcc.port]
+      dcc.send_handshake
+      begin
+        dcc.listen
+        @bot.loggers.info "DCC: Outgoing DCC SEND: File name: %s - Size: %dB - IP: %s - Port: %d - Status: done" % [filename, io.size, own_ip, dcc.port]
+      rescue Timeout::Error
+        @bot.loggers.info "DCC: Outgoing DCC SEND: File name: %s - Size: %dB - IP: %s - Port: %d - Status: failed (timeout)" % [filename, io.size, own_ip, dcc.port]
+      ensure
+        handler.unregister
+      end
+    end
+
+    # Updates the user's online state and dispatch the correct event.
+    #
+    # @since 2.0.0
+    # @return [void]
+    # @api private
+    def online=(bool)
+      notify = self.__send__("online?_unsynced") != bool && @monitored
+      sync(:online?, bool, true)
+
+      return unless notify
+      if bool
+        @bot.handlers.dispatch(:online, nil, self)
+      else
+        @bot.handlers.dispatch(:offline, nil, self)
+      end
+    end
+
+    # Used to update the user's nick on nickchange events.
+    #
+    # @param [String] new_nick The user's new nick
     # @api private
+    # @return [void]
     def update_nick(new_nick)
-      @last_nick, @nick = @nick, new_nick
-      @bot.user_manager.update_nick(self)
+      @last_nick, @name = @name, new_nick
+      @bot.user_list.update_nick(self)
     end
 
     # Provides synced access to user attributes.
@@ -406,12 +369,13 @@ module Cinch
       end
 
       if @data.has_key?(m)
-        attr(m, true, unsync = false)
+        attr(m, true, unsync)
       else
         super
       end
     end
 
+    # @since 1.1.2
     def respond_to?(m)
       if m.to_s =~ /^(.+)_unsynced$/
         m = $1.to_sym
@@ -419,25 +383,5 @@ module Cinch
 
       return @data.has_key?(m) || super
     end
-
-    # @return [Boolean]
-    def ==(other)
-      return case other
-             when self.class
-               @nick == other.nick
-             when String
-               self.to_s == other
-             when Bot
-               self.nick == other.config.nick
-             else
-               false
-             end
-    end
-    alias_method :eql?, "=="
-
-    # @return [Fixnum]
-    def hash
-      @nick.hash
-    end
   end
 end