ionian 0.6.8 → 0.6.9

data/lib/ionian/socket.rb

@@ -22,24 +22,55 @@ module Ionian
     
     # Creates a new socket or wraps an existing socket.
     # 
-    # Args:
-    #   host:       IP or hostname to connect to. Can contain the port in the format "host:port".
-    #   port:       Connection's port number. Default is 23. Unused by :unix protocol.
-    #   protocol:   Type of socket to create. :tcp, :udp, :unix. Default is :tcp.
-    #               :udp will be automatically selected for addresses in the multicast range.
-    #   persistent: The socket remains open after data is sent if this is true.
-    #               The socket closes after data is sent and a packet is received
-    #               if this is false. Default is true.
-    #   bind_port:  Local UDP port to bind to for receiving data, if different than
-    #               the remote port being connected to.
-    #   reuse_addr: Set true to enable the SO_REUSEADDR flag. Allows local address reuse.
-    #   no_delay:   Set true to enable the TCP_NODELAY flag. Disables Nagle algorithm.
-    #   cork:       Set true to enable the TCP_CORK flag. Buffers multiple writes
-    #               into one segment.
-    #   linger:     Set true to enable the SO_LINGER flag. When #close is called,
-    #               waits for the send buffer to empty before closing the socket.
-    #   expression: Overrides the #read_match regular expression for received data.
-    def initialize existing_socket = nil, **kwargs
+    # 
+    # @param existing_socket [Socket] An instantiated socket to be wrapped in
+    #   and returned as an {Ionian::Socket} (for example, TCPSocket). A new
+    #   socket will be created if this parameter is nil.
+    # 
+    # 
+    # @param kwargs [Hash] :host is mandatory.
+    # 
+    # @option kwargs [String] :host IP or hostname to connect to.
+    #   Can contain the port in the format "host:port".
+    # 
+    # @option kwargs [Fixnum] :port (23) Connection's port number. Unused by the
+    #   :unix protocol.
+    # 
+    # @option kwargs [:tcp, :udp, :unix] :protocol (:tcp) Type of socket to create.
+    #   :udp will be automatically selected for addresses in the multicast
+    #   range, or if the broadcast flag is set.
+    # 
+    # @option kwargs [Boolean] :persistent (true) The socket remains open after
+    #   data is sent if this is true. The socket closes after data is sent and
+    #   a packet is received if this is false.
+    # 
+    # @option kwargs [Boolean] :bind_port (:port) Local UDP port to bind to for
+    #   receiving data, if different than the remote port being connected to.
+    # 
+    # @option kwargs [Boolean] :broadcast (false) Enable the SO_BROADCAST flag.
+    #   Sets protocol to :udp implicitly.
+    # 
+    # @option kwargs [Boolean] :reuse_addr (false) Enable the SO_REUSEADDR flag.
+    #   Allows local address reuse.
+    # 
+    # @option kwargs [Boolean] :no_delay (false) Enable the TCP_NODELAY flag.
+    #   Disables Nagle algorithm.
+    # 
+    # @option kwargs [Boolean] :cork (false) Enable the TCP_CORK flag.
+    #   Buffers multiple writes into one segment.
+    # 
+    # @option kwargs [Boolean] :linger (false) Enable the SO_LINGER flag.
+    #   When #close is called, waits for the send buffer to empty before closing
+    #   the socket.
+    # 
+    # @option kwargs [Regexp, String] :expression Overrides the
+    #   {Ionian::Extension::IO#read_match} regular expression for received data.
+    # 
+    # 
+    # @yieldparam socket [Ionian::Socket] This socket is yielded to the block.
+    #   Socket flushes and closes when exiting the block.
+    # 
+    def initialize existing_socket = nil, **kwargs, &block
       @socket = existing_socket
       
       @ionian_listeners = []
@@ -67,7 +98,7 @@ module Ionian
           @protocol = :unix
         end
         
-        @persistent     = true # Existing sockets are always persistent.
+        @persistent = true # Existing sockets are always persistent.
         
         @socket.expression = @expression if @expression
         
@@ -81,12 +112,15 @@ module Ionian
         
         @host           = host_port_ary[0]
         @port           = kwargs.fetch :port, host_port_ary[1].to_i || 23
-        @bind_port      = kwargs.fetch :bind_port,  @port
+        @bind_port      = kwargs.fetch :bind_port, @port
+        
+        @broadcast      = kwargs.fetch :broadcast, false
         
         # Automatically select UDP for the multicast range. Otherwise default to TCP.
         default_protocol = :tcp
         default_protocol = :udp  if Ionian::Extension::Socket.multicast? @host
         default_protocol = :unix if @host.start_with? '/'
+        default_protocol = :udp  if @broadcast
         
         @protocol       = kwargs.fetch :protocol,   default_protocol
         @persistent     = kwargs.fetch :persistent, true
@@ -107,6 +141,14 @@ module Ionian
         
         create_socket if @persistent
       end
+      
+      if block
+        block.call self
+        unless self.closed?
+          self.flush
+          self.close
+        end
+      end
     end
         
     # Returns the regular expression used to match incoming data.
@@ -126,13 +168,18 @@ module Ionian
     end
     
     # Send a command (data) to the socket.
-    # Returns an array of received matches.
-    # Block yields received match.
-    # See Ionian::Extension::IO#read_match.
-    def cmd string, **kwargs, &block
+    # 
+    # @param [Hash] kwargs Pass through to {Ionian::Extension::IO#read_match}.
+    # 
+    # @return [Array<MatchData>] An array of received matches.
+    # 
+    # @yieldparam match [MatchData] Received match.
+    # 
+    # @see Ionian::Extension::IO#read_match
+    def cmd data, **kwargs, &block
       create_socket unless @persistent
       
-      write string
+      write data
       @socket.flush
       
       matches = @socket.read_match(kwargs) { |match| yield match if block_given? }
@@ -241,7 +288,11 @@ module Ionian
         @socket.extend Ionian::Extension::Socket
         
         @socket.reuse_addr = true if
-          @reuse_addr or Ionian::Extension::Socket.multicast? @host
+          @reuse_addr or
+          @broadcast or
+          Ionian::Extension::Socket.multicast? @host
+          
+        @socket.broadcast = true if @broadcast
         
         @socket.bind ::Socket::INADDR_ANY, @bind_port
         @socket.connect @host, @port
@@ -254,7 +305,8 @@ module Ionian
         
       end
       
-      @socket.linger = @linger
+      # Windows complains at SO_LINGER, so only set it if it was specified.
+      @socket.linger = @linger if @linger
       
       @socket.expression = @expression if @expression
       

data/license.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2013 Alex McLain
+Copyright (c) 2013-2014 Alex McLain
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ionian
 version: !ruby/object:Gem::Version
-  version: 0.6.8
+  version: 0.6.9
 platform: ruby
 authors:
 - Alex McLain
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-14 00:00:00.000000000 Z
+date: 2014-10-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -53,7 +53,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: rb-readline
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -66,6 +66,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+- !ruby/object:Gem::Dependency
+  name: rspec-its
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.1
 - !ruby/object:Gem::Dependency
   name: fivemat
   requirement: !ruby/object:Gem::Requirement
@@ -128,7 +156,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="