ionian 0.6.12 → 0.7.0

data/doc/top-level-namespace.html

@@ -103,7 +103,7 @@
 </div>
 
     <div id="footer">
-  Generated on Mon Jan 26 21:45:48 2015 by
+  Generated on Wed Jan 28 16:07:19 2015 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.8.7.6 (ruby-2.1.5).
 </div>

data/lib/ionian.rb

@@ -1,6 +1,7 @@
 require 'ionian/extension/io'
 require 'ionian/extension/socket'
 require 'ionian/socket'
+require 'ionian/managed_socket'
 require 'ionian/server'
 
 # A library to simplify interaction with IO streams.

data/lib/ionian/extension/io.rb

@@ -39,7 +39,7 @@ module Ionian
         ::IO.select([self], nil, nil, timeout) ? true : false
       end
       
-      # Returns the regular expression used for {#read_match}.
+      # @return [Regexp] Regular expression used for {#read_match}.
       def expression
         @ionian_expression
       end
@@ -84,8 +84,8 @@ module Ionian
       # @yieldparam match [MatchData] If there are multiple matches, the block
       #   is called multiple times.
       # 
-      # @return [Array<MatchData>, nil] Returns an array of matches.
-      #   Returns nil if no data was received within the timeout period.
+      # @return [Array<MatchData>, nil] matches.
+      #   Nil if no data was received within the timeout period.
       # 
       # 
       # @option kwargs [Numeric] :timeout (nil) Timeout in seconds IO::select
@@ -114,16 +114,23 @@ module Ionian
         exp           = Regexp.new "(.*?)#{exp}" if exp.is_a? String
         
         unless skip_select
-          return nil unless ::IO.select [self], nil, nil, timeout
+          return nil unless self.has_data? timeout: timeout
         end
         
-        # Read data from the IO buffer until it's empty.
-        @ionian_buf << read_all
-        
         @matches = []
         
+        # TODO: Implement an option for number of bytes or timeout to throw away
+        #       data if no match is found.
+        Timeout.timeout(timeout) do
+          loop do
+            # Read data from the IO buffer until it's empty.
+            @ionian_buf << read_all
+            break if @ionian_buf =~ exp
+          end
+        end
+        
         while @ionian_buf =~ exp
-          @matches << $~ # Match data.
+          @matches << $~   # Match data.
           @ionian_buf = $' # Leave post match data in the buffer.
         end
         
@@ -155,6 +162,7 @@ module Ionian
       # This method SHOULD NOT be used if {#read_match} is used.
       def run_match **kwargs
         @run_match_thread ||= Thread.new do
+          Thread.current.thread_variable_set :match_thread_running, true
           begin
             while not closed? do
               matches = read_match **kwargs
@@ -168,6 +176,14 @@ module Ionian
         end
       end
       
+      def run_match_is_running?
+        return true if \
+          @run_match_thread and
+          @run_match_thread.thread_variable_get(:match_thread_running)
+        
+        false
+      end
+      
       # Erase the data in the IO and Ionian buffers.
       # This is typically handled automatically.
       def purge
@@ -195,6 +211,7 @@ module Ionian
       
       # @deprecated Use {#register_match_handler} instead.
       def register_observer &block
+        STDOUT.puts "WARN: Call to deprecated method #{__method__}"
         register_match_handler &block
       end
       
@@ -206,6 +223,7 @@ module Ionian
       
       # @deprecated Use {#unregister_match_handler} instead.
       def unregister_observer &block
+        STDOUT.puts "WARN: Call to deprecated method #{__method__}"
         unregister_match_handler &block
       end
       

data/lib/ionian/extension/socket.rb

@@ -55,13 +55,11 @@ module Ionian
       # immediately and try to deliver any data in the send buffer if value
       # is true.
       # 
-      # Args:
-      #   Time: Time in seconds to remain open before discarding data and
-      #         sending a RST packet.
+      # @param time [Fixnum] Time in seconds to remain open before discarding
+      #   data and sending a RST packet.
+      # 
       # ( SO_LINGER )
       def linger= enable, time: 60
-        # TODO: Passing a kwarg doesn't work here because of the
-        #       assignment operator. Causes parser error.
         param = (!!enable && enable != 0) ? 1 : 0
         self.setsockopt ::Socket::SOL_SOCKET, ::Socket::SO_LINGER, [param, time.to_i].pack('ii')
       end
@@ -231,49 +229,51 @@ module Ionian
       
       # Not yet implemented.
       def ipv6_add_membership
-        # TODO: Implement
-        false
+        # TODO: Implement IPv6
+        raise NotImplementedError
       end
       
       # Not yet implemented.
       def ipv6_drop_membership
-        # TODO: Implement
-        false
+        # TODO: Implement IPv6
+        raise NotImplementedError
       end
       
       # Not yet implemented.
       def ipv6_multicast_if
-        # TODO: Implement
-        false
+        # TODO: Implement IPv6
+        raise NotImplementedError
       end
       
       # Not yet implemented.
       def ipv6_multicast_if= value
-        # TODO: Implement
+        # TODO: Implement IPv6
       end
       
       # Not yet implemented.
       def ipv6_multicast_hops
-        # TODO: Implement
-        false
+        # TODO: Implement IPv6
+        raise NotImplementedError
       end
       
       # Not yet implemented.
       def ipv6_multicast_hops= value
-        # TODO: Implement
+        # TODO: Implement IPv6
+        raise NotImplementedError
       end
       
       # Not yet implemented.
       def ipv6_multicast_loop
-        # TODO: Implement
-        false
+        # TODO: Implement IPv6
+        raise NotImplementedError
       end
       
       alias_method :ipv6_multicast_loop?, :ipv6_multicast_loop
       
       # Not yet implemented.
       def ipv6_multicast_loop= value
-        # TODO: Implement
+        # TODO: Implement IPv6
+        raise NotImplementedError
       end
       
       

data/lib/ionian/managed_socket.rb

@@ -0,0 +1,109 @@
+require 'ionian/socket'
+
+module Ionian
+  
+  # A socket manager that wraps an {Ionian::Socket} and can perform functions
+  # like heartbeating and auto-reconnect.
+  class ManagedSocket
+    
+    # When true, automatically reconnect if the socket closes.
+    attr_reader :auto_reconnect
+    
+    # @option kwargs [Boolean] :auto_reconnect (false) Automatically reconnect
+    #   if the socket closes. Must call {#close} to break the auto-reconnect
+    #   loop.
+    # 
+    # @see Ionian::Socket#initialize More optional parameters.
+    def initialize **kwargs
+      @auto_reconnect = kwargs.delete(:auto_reconnect) || false
+      @kwargs = kwargs
+      
+      @match_handlers = []
+      @error_handlers = []
+      
+      create_socket
+    end
+    
+    # Close the socket.
+    # Disables :auto_reconnect.
+    def close
+      @auto_reconnect = false
+      @socket.close unless @socket.closed?
+    end
+    
+    # Register a block to be called when {Ionian::Extension::IO#run_match}
+    # receives matched data.
+    # Method callbacks can be registered with &object.method(:method).
+    # @return [Block] The given block.
+    # @yield [MatchData, self]
+    def register_match_handler &block
+      @match_handlers << block unless @match_handlers.include? block
+      @socket.register_match_handler &block if @socket
+      block
+    end
+    
+    alias_method :on_match, :register_match_handler
+    
+    # Unregister a block from being called when matched data is received.
+    def unregister_match_handler &block
+      @match_handlers.delete_if { |o| o == block }
+      @socket.unregister_match_handler &block if @socket
+      block
+    end
+    
+    # Register a block to be called when {Ionian::Extension::IO#run_match}
+    # raises an error.
+    # Method callbacks can be registered with &object.method(:method).
+    # @return [Block] a reference to the given block.
+    # @yield [Exception, self]
+    def register_error_handler &block
+      @error_handlers << block unless @error_handlers.include? block
+      @socket.register_error_handler &block if @socket
+      block
+    end
+    
+    alias_method :on_error, :register_error_handler
+    
+    # Unregister a block from being called when a {Ionian::IO#run_match} error
+    # is raised.
+    def unregister_error_handler &block
+      @error_handlers.delete_if { |o| o == block }
+      @socket.unregister_error_handler &block if @socket
+      block
+    end
+    
+    # Pass unhandled methods to @socket.
+    # @see Ionian::Socket
+    def method_missing meth, *args, &block
+      @socket.__send__ meth, *args, &block
+    end
+    
+    def respond_to_missing? meth, *args
+      @socket.respond_to? meth, *args
+    end
+    
+    
+    private
+    
+    # Initialize or reinitialize @socket.
+    def create_socket
+      @socket = Ionian::Socket.new **@kwargs
+      @socket.on_error &method(:socket_error_handler)
+      @match_handlers.each { |h| @socket.register_match_handler &h }
+      @error_handlers.each { |h| @socket.register_error_handler &h }
+      
+      @socket.run_match
+    end
+    
+    # {Ionian::Socket#on_error} handler for @socket.
+    def socket_error_handler e, socket
+      if auto_reconnect
+        @socket.close unless @socket.closed?
+        create_socket
+      else
+        raise e unless e.is_a? EOFError or e.is_a? IOError
+      end
+    end
+    
+  end
+end

data/lib/ionian/socket.rb

@@ -1,3 +1,4 @@
+require 'timeout'
 require 'ionian/extension/socket'
 
 module Ionian
@@ -19,6 +20,17 @@ module Ionian
     attr_reader :protocol
     alias_method :protocol?, :protocol
     
+    # @return [Ionian::Socket] a broadcast socket.
+    # 
+    # @option kwargs [Fixnum] :port Port to broadcast on.
+    # @option kwargs [String] :address ('255.255.255.255') Address to broadcast on.
+    # 
+    # @see #initialize Full list of socket options.
+    def self.create_broadcast_socket **kwargs
+      kwargs[:host] = kwargs.delete(:address) || '255.255.255.255'
+      kwargs[:broadcast] = true
+      new **kwargs
+    end
     
     # Creates a new socket or wraps an existing socket.
     # 
@@ -76,7 +88,8 @@ module Ionian
     def initialize existing_socket = nil, **kwargs, &block
       @socket = existing_socket
       
-      @ionian_listeners = []
+      @ionian_match_handlers = []
+      @ionian_error_handlers = []
       
       @expression = kwargs.fetch :expression, nil
       
@@ -192,31 +205,64 @@ module Ionian
       matches
     end
     
-    # Register a block to be called when #run_match receives matched data.
+    # Register a block to be called when {Ionian::Extension::IO#run_match}
+    # receives matched data.
     # Method callbacks can be registered with &object.method(:method).
-    # Returns a reference to the given block.
-    # block = ionian_socket.register_observer { ... }
-    def register_observer &block
-      @ionian_listeners << block unless @ionian_listeners.include? block
-      @socket.register_observer &block if @socket
+    # @return [Block] The given block.
+    # @yield [MatchData, self]
+    def register_match_handler &block
+      @ionian_match_handlers << block unless @ionian_match_handlers.include? block
+      @socket.register_match_handler &block if @socket
       block
     end
     
-    alias_method :on_match, :register_observer
+    alias_method :on_match, :register_match_handler
+    
+    # @deprecated Use {#register_match_handler} instead.
+    def register_observer &block
+      STDOUT.puts "WARN: Call to deprecated method #{__method__}"
+      register_match_handler &block
+    end
     
     # Unregister a block from being called when matched data is received.
+    def unregister_match_handler &block
+      @ionian_match_handlers.delete_if { |o| o == block }
+      @socket.unregister_match_handler &block if @socket
+      block
+    end
+    
+    # @deprecated Use {#unregister_match_handler} instead.
     def unregister_observer &block
-      @ionian_listeners.delete_if { |o| o == block }
-      @socket.unregister_observer &block if @socket
+      STDOUT.puts "WARN: Call to deprecated method #{__method__}"
+      unregister_match_handler &block
+    end
+    
+    # Register a block to be called when {Ionian::Extension::IO#run_match}
+    # raises an error.
+    # Method callbacks can be registered with &object.method(:method).
+    # @return [Block] a reference to the given block.
+    # @yield [Exception, self]
+    def register_error_handler &block
+      @ionian_error_handlers << block unless @ionian_error_handlers.include? block
+      @socket.register_error_handler &block if @socket
+      block
+    end
+    
+    alias_method :on_error, :register_error_handler
+    
+    # Unregister a block from being called when a {Ionian::IO#run_match} error
+    # is raised.
+    def unregister_error_handler &block
+      @ionian_error_handlers.delete_if { |o| o == block }
+      @socket.unregister_error_handler &block if @socket
       block
     end
     
     ### Methods Forwarded To @socket ###
     
-    # Returns true if there is data in the receive buffer.
-    # Args:
-    #   Timeout: Number of seconds to wait for data until
-    #     giving up. Set to nil for blocking.
+    # @return [Boolean] True if there is data in the receive buffer.
+    # @option kwargs [Fixnum, nil] :timeout (0) Number of seconds to wait for
+    # data until giving up. Set to nil for blocking.
     def has_data? **kwargs
       return false unless @socket
       @socket.has_data? kwargs
@@ -240,8 +286,8 @@ module Ionian
       self.write string.map{ |s| s.chomp }.join("\n") + "\n"
     end
     
-    # Writes the given string to the socket. Returns the number of
-    # bytes written.
+    # Writes the given string to the socket.
+    # @return [Fixnum] Number of bytes written.
     def write string
       create_socket unless @persistent
       
@@ -317,8 +363,9 @@ module Ionian
           
           @socket.expression = @expression if @expression
           
-          # Register listeners.
-          @ionian_listeners.each { |proc| @socket.on_match &proc }
+          # Register handlers.
+          @ionian_match_handlers.each { |proc| @socket.on_match &proc }
+          @ionian_error_handlers.each { |proc| @socket.on_error &proc }
           
           initialize_socket_methods
         end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ionian
 version: !ruby/object:Gem::Version
-  version: 0.6.12
+  version: 0.7.0
 platform: ruby
 authors:
 - Alex McLain
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-26 00:00:00.000000000 Z
+date: 2015-01-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -121,6 +121,7 @@ files:
 - doc/Ionian/Extension.html
 - doc/Ionian/Extension/IO.html
 - doc/Ionian/Extension/Socket.html
+- doc/Ionian/ManagedSocket.html
 - doc/Ionian/Server.html
 - doc/Ionian/Socket.html
 - doc/_index.html
@@ -141,6 +142,7 @@ files:
 - lib/ionian.rb
 - lib/ionian/extension/io.rb
 - lib/ionian/extension/socket.rb
+- lib/ionian/managed_socket.rb
 - lib/ionian/server.rb
 - lib/ionian/socket.rb
 - license.txt
@@ -164,7 +166,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5
+rubygems_version: 2.4.4
 signing_key: 
 specification_version: 4
 summary: Regular expression matching and notification for IO streams.