blur 1.5.3 → 1.6

data/library/blur/network.rb

@@ -1,83 +1,137 @@
 # encoding: utf-8
 
 module Blur
+  # The +Network+ module is to be percieved as an IRC network.
+  #
+  # Although the connection is a part of the network module, it is mainly used
+  # for network-related structures, such as {User}, {Channel} and {Command}.
   class Network
+    # +ConnectionError+ should only be triggered from within {Connection}.
     class ConnectionError < StandardError; end
 
-    attr_accessor :options, :channels, :dialogues, :delegate, :connection
+    # @return [Hash] the network options.
+    attr_accessor :options
+    # @return [Array] the list of channels the client is in.
+    attr_accessor :channels
+    # @return [Array] the list of private messages the client remembers.
+    attr_accessor :dialogues
+    # @return [Client] the client delegate.
+    attr_accessor :delegate
+    # @return [Network::Connection] the connection instance.
+    attr_accessor :connection
 
-    def connected?; @connection.established? end
+    # Check whether or not connection is established.
+    def connected?; @connection and @connection.established? end
 
-    def host
-      @options[:hostname]
-    end
+    # Get the remote hostname.
+    #
+    # @return [String] the remote hostname.
+    def host; @options[:hostname] end
 
-    def port
-      @options[:port] ||= secure? ? 6697 : 6667
-    end
+    # Get the remote port.
+    # If no port is specified, it returns 6697 if using a secure connection,
+    # returns 6667 otherwise.
+    #
+    # @return [Fixnum] the remote port
+    def port; @options[:port] ||= secure? ? 6697 : 6667 end
     
-    def secure?
-      @options[:secure] == true
-    end
+    # Check to see if it's a secure connection.
+    def secure?; @options[:secure] == true end
 
-    def initialize options = {}
+    # Check to see if FiSH encryption is enabled.
+    def fish?; not @options[:fish].nil? end
+
+    # Instantiates the network.
+    #
+    # @param [Hash] options the network options.
+    # @option options [String] :hostname the remote hostname.
+    # @option options [String] :nickname the nickname to represent.
+    # @option options [optional, String] :username the username to represent.
+    # @option options [optional, String] :realname the “real name” to represent.
+    # @option options [optional, String] :password the password for the network.
+    # @option options [optional, Fixnum] :port the remote port.
+    # @option options [optional, Boolean] :secure use a secure connection.
+    def initialize options
       @options  = options
       @channels = []
       
       unless options[:nickname]
-        raise ArgumentError, "nickname is missing from the network's option block"
+        raise ArgumentError, "nickname is missing from the networks option block"
       end
       
       @options[:username] ||= @options[:nickname]
       @options[:realname] ||= @options[:username]
       @options[:channels] ||= []
-
-      @connection = Connection.new self, host, port
     end
     
+    # Send a message to a recipient.
+    #
+    # @param [String, #to_s] recipient the recipient.
+    # @param [String] message the message.
     def say recipient, message
+      if recipient.is_a? Channel and recipient.encrypted?
+        message = "+OK #{recipient.encryption.encrypt message}"
+      end
+
       transmit :PRIVMSG, recipient, message
     end
     
+    # Called when the network connection has enough data to form a command.
     def got_command command
       @delegate.got_command self, command
     end
     
+    # Find a channel by its name.
+    #
+    # @param [String] name the channel name.
+    # @return [Network::Channel] the matching channel, or nil.
     def channel_by_name name
       @channels.find { |channel| channel.name == name }
     end
     
+    # Find all instances of channels in which there is a user with the nick
+    # +nick+.
+    #
+    # @param [String] nick the nickname.
+    # @return [Array] a list of channels in which the user is located, or nil.
     def channels_with_user nick
       @channels.select { |channel| channel.user_by_nick nick }
     end
 
+    # Attempt to establish a connection and send initial data.
+    #
+    # @see Connection
     def connect
-      @connection.establish
-      @connection.enable_ssl OpenSSL::SSL::VERIFY_NONE if secure?
-      
+      @connection = EventMachine.connect host, port, Connection, self
+    end
+
+    # Called when the connection was successfully established.
+    def connected!
       transmit :PASS, @options[:password] if @options[:password]
       transmit :NICK, @options[:nickname]
       transmit :USER, @options[:username], :void, :void, @options[:realname]
     end
     
+    # Terminate the connection and clear all channels and users.
     def disconnect
-      @connection.terminate
+      @connection.close_connection_after_writing
 
       @channels.each { |channel| channel.users.clear }
       @channels.clear
     end
     
+    # Transmit a command to the server.
+    #
+    # @param [Symbol, String] name the command name.
+    # @param [...] arguments all the prepended parameters.
     def transmit name, *arguments
       command = Command.new name, arguments
       puts "-> #{inspect ^ :bold} | #{command}"
       
-      @connection.transmit command
-    end
-    
-    def transcieve
-      @connection.transcieve
+      @connection.send_data "#{command}\r\n"
     end
     
+    # Convert it to a debug-friendly format.
     def to_s
       %{#<#{self.class.name} "#{host}":#{port}>}
     end

data/library/blur/network/channel.rb

@@ -2,9 +2,34 @@
 
 module Blur
   class Network
+    # The +Channel+ class is used for encapsulating a channel and its properties.
+    #
+    # Users inside the channel is stored in the {#channels} attribute.
+    #
+    # Modes can be set for a channel, but Blur is not 
+    # {http://www.irc.org/tech_docs/005.html ISupport}-compliant yet.
+    #
+    # @todo make so that channels *and* users belongs to the network, and not
+    #   like now where the user belongs to the channel, resulting in multiple
+    #   user instances.
     class Channel
-      attr_accessor :name, :users, :topic, :modes, :network
+      # @return [String] the channels name.
+      attr_accessor :name
+      # @return [Array] a list of users in the channel.
+      attr_accessor :users
+      # @return [String] the channels topic.
+      attr_accessor :topic
+      # @return [String] all the modes set on the channel.
+      attr_accessor :modes
+      # @return [Network] a reference to the network.
+      attr_accessor :network
+      # @return [Encryption::Fish] the channel encryption, if any.
+      attr_accessor :encryption
 
+      # Check whether or not this is an encrypted channel.
+      def encrypted?; not @encryption.nil? end
+
+      # Instantiate a user with a nickname, a network and a user list.
       def initialize name, network = nil, users = []
         @name    = name
         @users   = users
@@ -14,6 +39,9 @@ module Blur
         users.each { |user| user.channel = self }
       end
 
+      # Merge the channels mode corresponding to the leading character (+ or -).
+      #
+      # @param [String] modes the modes to merge with.
       def merge_modes modes
         addition = true
 
@@ -29,22 +57,32 @@ module Blur
         end
       end
 
+      # Send a message to the channel.
+      #
+      # @param [String] message the message to send.
       def say message
         @network.say self, message
       end
 
+      # Find a user with +nick+ as its nickname.
+      #
+      # @param [String] nick the nickname to find the user of.
       def user_by_nick nick
         @users.find { |user| user.nick == nick }
       end
 
+      # Convert it to a debug-friendly format.
       def inspect
         %{#<#{self.class.name} @name=#{@name.inspect} @users=#{@users.inspect}}
       end
       
+      # Called when YAML attempts to save the object, which happens when a
+      # scripts cache contains this user and the script is unloaded.
       def to_yaml options = {}
         @name.to_yaml options
       end
 
+      # Get the channels name.
       def to_s
         @name
       end

data/library/blur/network/command.rb

@@ -2,11 +2,30 @@
 
 module Blur
   class Network
+    # The +Command+ class is used for encapsulating the command-lines.
+    #
+    # Blur is using regular-expression for parsing, this is to be replaced
+    # with a more native way of parsing, making it much, much easier on the
+    # processor.
     class Command
-      attr_accessor :name, :params, :prefix
+      # @return [Symbol, Fixnum] the command name.
+      # @example
+      #   332 or :quit
+      attr_accessor :name
+      # @return [Array] a list of parameters.
+      attr_accessor :params
+      # @return [String] a hostname or a hostmask.
+      attr_accessor :prefix
 
+      # The arbitrary regex pattern.
       Pattern = /^(?:[:@]([^\s]+) )?([^\s]+)(?: ((?:[^:\s][^\s]* ?)*))?(?: ?:(.*))?$/
       
+      # Parse a line and encapsulate it as a Command.
+      #
+      # @return [Command] the parsed command.
+      # @example
+      #   Command.parse "ChanServ!ChanServ@services.uplink.io MODE #uplink +v mk"
+      #   # => #<Blur::Network::Command … >
       def self.parse data
         match = data.strip.match Pattern
         prefix, name, args, extra = match.captures
@@ -17,12 +36,23 @@ module Blur
         end
       end
 
+      # Get a parameter by its +index+.
       def [] index; @params[index] end
 
+      # Instantiate a command.
+      #
+      # @see Command.parse
       def initialize name, params = []
         @name, @params = name, params
       end
 
+      # Get the sender of the command.
+      #
+      # @note the return value is a string if it's a hostname, and an openstruct
+      #   with the attributes #nickname, #username and #hostname if it's a
+      #   hostmask.
+      #
+      # @return [String, OpenStruct] the sender.
       def sender
         return @sender if @sender
 
@@ -33,6 +63,9 @@ module Blur
         end
       end 
 
+      # Convert it to an IRC-compliant line.
+      #
+      # @return [String] the command line.
       def to_s
         String.new.tap do |line|
           line << "#{prefix} " if prefix

data/library/blur/network/connection.rb

@@ -1,72 +1,68 @@
 # encoding: utf-8
 
 module Blur
-  class Network 
-    class Connection
-      def established?; @socket and not @socket.closed? end
-      
-      def initialize delegate, host = nil, port = nil
-        @host     = host
-        @port     = port
-        @queue    = []
-        @buffer   = ""
-        @socket   = nil
-        @delegate = delegate
-      end
-      
-      def establish
-        @socket = TCPSocket.new @host, @port
+  class Network
+    # The +Connection+ class inherits the LineAndText protocol bundled with
+    # the eventmachine library.
+    #
+    # It merely acts as a receiving handler for all messages eventmachine throws
+    # at it through its lifetime.
+    #
+    # @see EventMachine::Protocols::LineAndTextProtocol
+    # @see EventMachine::Connection
+    class Connection < EM::Protocols::LineAndTextProtocol
+      # Check whether or not connection is established.
+      def established?; @connected == true end
+
+      # EventMachine instantiates this class, and then sends event messages to
+      # that instance.
+      def initialize network
+        @network = network
+        @connected = false
+
+        super
       end
 
-      def enable_ssl verification
-        @secure = true
+      # Called when a new connection is being set up, all we're going to use
+      # it for is to enable SSL/TLS on our connection.
+      def post_init
+        start_tls if @network.secure?
+      end
 
-        context = OpenSSL::SSL::SSLContext.new
-        context.set_params verify_mode: verification
+      # Called when a line was received, the connection sends it to the network
+      # delegate which then sends it to the client.
+      def receive_line line
+        command = Command.parse line
+        @network.got_command command
+      end
 
-        sslsocket = OpenSSL::SSL::SSLSocket.new @socket, context
-        sslsocket.sync = true
-        sslsocket.connect_nonblock
+      # Called when the SSL handshake was completed with the remote server,
+      # the reason we tell the network that we're connected here is to ensure
+      # that the SSL/TLS encryption succeeded before we start talking nonsense
+      # to the server.
+      def ssl_handshake_completed
+        connected!
       end
-      
-      def terminate
-        @socket = nil if @socket.close
-        @buffer.clear
-        @queue.clear
+
+      # Called once the connection is finally established.
+      def connection_completed
+        @network.connected! unless @network.secure?
       end
-      
-      def transmit command
-        @queue.push command
+
+      # Called just as the connection is being terminated, either by remote or
+      # local.
+      def unbind
+        @connected = false
+
+        super
       end
-      
-      def transcieve
-        readable, writable = IO.select [@socket], [@socket]
 
-        # If the socket is ready to recieve, do so.
-        if socket = readable.first
-          @buffer.<< socket.read_nonblock 512
-          
-          while index = @buffer.index(?\n)
-            command = Command.parse @buffer.slice! 0..index
-            @delegate.got_command command
-          end
-        end
-        
-        # If it's ready to write, do that too until the outoing queue is empty.
-        if socket = writable.first
-          while command = @queue.shift
-            socket.write_nonblock "#{command}\n"
-          end
-        end
+    private
+      # Called when connection has been established.
+      def connected!
+        @connected = true
 
-      rescue Errno::EAGAIN, Errno::EWOULDBLOCK
-        puts "Insecure connection would block"
-      rescue OpenSSL::SSL::SSLError
-        if $!.message == "read would block"
-          puts "Secure connection would block"
-        else
-          raise $!
-        end
+        @network.connected!
       end
     end
   end

data/library/blur/network/user.rb

@@ -2,19 +2,42 @@
 
 module Blur
   class Network
+    # The +User+ class is used for encapsulating a user and its properties.
+    #
+    # The user owns a reference to its parent channel.
+    #
+    # Modes can be set for a user, but Blur is not 
+    # {http://www.irc.org/tech_docs/005.html ISupport}-compliant yet.
+    #
+    # @todo make so that channels *and* users belongs to the network, and not
+    #   like now where the user belongs to the channel, resulting in multiple
+    #   user instances.
     class User
-      attr_accessor :nick, :name, :host, :modes, :channel, :network
+      # @return [String] the users nickname.
+      attr_accessor :nick
+      # @return [String] the users username.
+      attr_accessor :name
+      # @return [String] the users hostname.
+      attr_accessor :host
+      # @return [String] all the modes set on the user.
+      attr_accessor :modes
+      # @return [Channel] a reference to the users channel.
+      attr_accessor :channel
+      # @return [Network] a reference to the network.
+      attr_accessor :network
 
-      def self.map_mode name, character
-        define_method(:"#{name}?") { @modes.include? character.to_s }
-      end
-
-      map_mode :admin,         :a
-      map_mode :voice,         :v
-      map_mode :owner,         :q
-      map_mode :operator,      :o
-      map_mode :half_operator, :h
+      # Check to see if the user is an admin (+a)
+      def admin?; @modes.include? "a" end
+      # Check to see if the user has voice (+v)
+      def voice?; @modes.include? "v" end
+      # Check to see if the user is the owner (+q)
+      def owner?; @modes.include? "q" end
+      # Check to see if the user is an operator (+o)
+      def operator?; @modes.include? "o" end
+      # Check to see if the user is an half-operator (+h)
+      def half_operator?; @modes.include? "h" end
 
+      # Instantiate a user with a nickname.
       def initialize nick
         @nick  = nick
         @modes = ""
@@ -25,6 +48,9 @@ module Blur
         end
       end
 
+      # Merge the users mode corresponding to the leading character (+ or -).
+      #
+      # @param [String] modes the modes to merge with.
       def merge_modes modes
         addition = true
 
@@ -40,24 +66,32 @@ module Blur
         end
       end
       
+      # Send a private message to the user.
+      #
+      # @param [String] message the message to send.
       def say message
         @network.say self, message
       end
       
+      # Convert it to a debug-friendly format.
       def inspect
         %{#<#{self.class.name} @nick=#{@nick.inspect} @channel=#{@channel.name.inspect}>}
       end
 
+      # Called when YAML attempts to save the object, which happens when a
+      # scripts cache contains this user and the script is unloaded.
       def to_yaml options = {}
         @nick.to_yaml options
       end
       
+      # Get the users nickname.
       def to_s
         @nick
       end
 
     private
 
+      # Translate a nickname-prefix to a mode character.
       def prefix_to_mode prefix
         case prefix
         when '@' then 'o'