ib-ruby 0.5.21 → 0.6.1

data/HISTORY

@@ -125,3 +125,11 @@
 == 0.5.21 / 2012-03-06
 
 * Fully tested with integration spec suite
+
+== 0.6.0 / 2012-03-09
+
+* Connection wait_for/received/received? API added
+
+== 0.6.1 / 2012-03-14
+
+* Version bump

data/README.md

@@ -11,12 +11,9 @@ implied. Your use of this software is at your own risk. It may contain
 any number of bugs, known or unknown, which might cause you to lose
 money if you use it. You've been warned.
 
-__It is specifically NOT RECOMMENDED that this code be used for live trading.__
-
 This code is not sanctioned or supported by Interactive Brokers
 This software is available under the LGPL. See the file LICENSE for full licensing details.
 
-
 ## REQUIREMENTS:
 
 Either the Interactive Brokers
@@ -42,30 +39,52 @@ localhost if you're running ib-ruby on the same machine as TWS.
 First, start up Interactive Broker's Trader Work Station or Gateway.
 Make sure it is configured to allow API connections on localhost.
 Note that TWS and Gateway listen to different ports, this library assumes
-connection to Gateway (localhost:4001) by default, this can changed via :host and :port
-options given to IB::Connection.new.
-
-    >> require 'ib-ruby'
-    >> ib = IB::Connection.new
-    >> ib.subscribe(:Alert, :AccountValue) { |msg| puts msg.to_human }
-    >> ib.send_message :RequestAccountData, :subscribe => true
-
-Your code and TWS interact via an exchange of messages. You
-subscribe to message types you're interested in using
-`IB::Connection#subscribe` and request data from TWS using
-`IB::Connection#send_message`.
-
-The code blocks (or procs) given to `#subscribe` will be executed when
-a message of the requested type is received, with the received message as
-its argument.
-
-See `lib/ib-ruby/messages` for a full list of supported incoming/outgoing messages and
-their attributes. The original TWS docs and code samples can be found
-in the `misc/` folder.
-
-The sample scripts in the `bin/` directory provide examples of how
-common tasks can be achieved using ib-ruby.
-
+connection to Gateway (localhost:4001) by default, this can changed via :host
+and :port options given to IB::Connection.new.
+
+    require 'ib-ruby'
+
+    ib = IB::Connection.new
+    ib.subscribe(:Alert, :AccountValue) { |msg| puts msg.to_human }
+    ib.send_message :RequestAccountData
+    ib.wait_for :AccountDownloadEnd
+
+    ib.subscribe(:OpenOrder) { |msg| puts "Placed: #{msg.order}!" }
+    ib.subscribe(:ExecutionData) { |msg| puts "Filled: #{msg.execution}!" }
+    contract = IB::Models::Contract.new :symbol => 'WFC',
+                                        :exchange => 'NYSE'
+                                        :currency => 'USD',
+                                        :sec_type => IB::SECURITY_TYPES[:stock]
+    buy_order = IB::Models::Order.new :total_quantity => 100,
+                                      :limit_price => 21.00,
+                                      :action => 'BUY',
+                                      :order_type => 'LMT'
+    ib.place_order buy_order, contract
+    ib.wait_for :ExecutionData
+
+Your code interacts with TWS via exchange of messages. Messages that you send to
+TWS are called 'Outgoing', messages your code receives from TWS - 'Incoming'.
+
+First, you need to subscribe to incoming message types you're interested in
+using `Connection#subscribe`. The code block (or proc) given to `#subscribe`
+will be executed when an incoming message of the requested type is received
+from TWS, with the received message as its argument.
+
+Then, you request specific data from TWS using `Connection#send_message` or place
+your order using `Connection#place_order`. TWS will respond with messages that you
+should have subscribed for, and these messages are be processed in a code block
+given to `#subscribe`.
+
+In order to give TWS time to respond, you either run a message processing loop or
+just wait until Connection receives the messages type you requested.
+
+See `lib/ib-ruby/messages` for a full list of supported incoming/outgoing messages
+and their attributes. The original TWS docs and code samples can be found
+in `misc` directory.
+
+The sample scripts in `bin` directory provide examples of how common tasks
+can be achieved using ib-ruby. You may also want to look into `spec/integration`
+directory for more scenarios and examples of handling IB messages.
 
 ## LICENSE:
 

data/TODO

@@ -1,7 +1,7 @@
-1. Create integration tests for basic use cases
-
 Plan:
 
+1. Detailed message documentation
+
 2. Make ActiveModel-like attributes Hash for easy attributes updating
 
 3. IB#send_message method should accept block, thus compressing subscribe/send_message
@@ -14,8 +14,19 @@ http://finance.groups.yahoo.com/group/TWSAPI/message/25413
 
 6. Compatibility check for new TWS v.966
 
+7. @received_at timestamp in messages
+
+8. Collect all messages in Connection#received_messages
+
+9. Flow handlers: Connection#wait_for / Connection#received?
+
+10. Create integration tests for more use cases (spec/README)
+
+
 Done:
 
+1. Create integration tests for basic use cases
+
 2. IB#subscribe should accept regexes.
 
 Ideas for future:

data/VERSION

@@ -1 +1 @@
-0.5.21
+0.6.1

data/bin/generic_data.rb

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+
+# This script reproduces https://github.com/ib-ruby/ib-ruby/issues/12
+
+require 'pathname'
+LIB_DIR = (Pathname.new(__FILE__).dirname + '../lib/').realpath.to_s
+$LOAD_PATH.unshift LIB_DIR unless $LOAD_PATH.include?(LIB_DIR)
+
+require 'rubygems'
+require 'bundler/setup'
+require 'ib-ruby'
+
+contract = IB::Models::Contract.new :symbol=> 'AAPL',
+                                    :exchange=> "Smart",
+                                    :currency=> "USD",
+                                    :sec_type=> IB::SECURITY_TYPES[:stock],
+                                    :description=> "Some stock"
+ib = IB::Connection.new
+ib.subscribe(:Alert) { |msg| puts msg.to_human }
+ib.subscribe(:TickGeneric, :TickString, :TickPrice, :TickSize) { |msg| puts msg.inspect }
+ib.send_message :RequestMarketData, :id => 123, :contract => contract
+
+puts "\nSubscribed to market data"
+puts "\n******** Press <Enter> to cancel... *********\n\n"
+gets
+puts "Cancelling market data subscription.."

data/bin/place_order

@@ -23,7 +23,7 @@ buy_order = IB::Models::Order.new :total_quantity => 100,
                                   :action => 'BUY',
                                   :order_type => 'LMT'
 
-sleep 0.5 # waiting for :NextValidID
+sleep 0.5 # waiting for :NextValidId
 
 ib.place_order buy_order, wfc
 

data/lib/ib-ruby/connection.rb

@@ -15,9 +15,10 @@ module IB
                        :port => '4001', # IB Gateway connection (default)
                        #:port => '7496', # TWS connection, with annoying pop-ups
                        :client_id => nil, # Will be randomly assigned
-                       :connect => true,
-                       :reader => true,
-                       :logger => nil
+                       :connect => true, # Connect at initialization
+                       :reader => true, # Start a separate reader Thread
+                       :received => true, # Keep all received messages in a Hash
+                       :logger => nil,
     }
 
     # Singleton to make active Connection universally accessible as IB::Connection.current
@@ -28,7 +29,7 @@ module IB
     attr_reader :server #         Info about IB server and server connection state
     attr_accessor :next_order_id #  Next valid order id
 
-    def initialize(opts = {})
+    def initialize opts = {}
       @options = DEFAULT_OPTIONS.merge(opts)
 
       self.default_logger = @options[:logger] if @options[:logger]
@@ -40,19 +41,13 @@ module IB
       Connection.current = self
     end
 
-    # Message subscribers. Key is the message class to listen for.
-    # Value is a Hash of subscriber Procs, keyed by their subscription id.
-    # All subscriber Procs will be called with the message instance
-    # as an argument when a message of that type is received.
-    def subscribers
-      @subscribers ||= Hash.new { |hash, key| hash[key] = Hash.new }
-    end
+    ### Working with connection
 
     def connect
       raise "Already connected!" if connected?
 
-      # TWS always sends NextValidID message at connect - save this id
-      self.subscribe(:NextValidID) do |msg|
+      # TWS always sends NextValidId message at connect - save this id
+      self.subscribe(:NextValidId) do |msg|
         @next_order_id = msg.order_id
         log.info "Got next valid order id: #{@next_order_id}."
       end
@@ -101,16 +96,14 @@ module IB
       @connected
     end
 
-    def reader_running?
-      @reader_running && @server[:reader] && @server[:reader].alive?
-    end
+    ### Working with message subscribers
 
     # Subscribe Proc or block to specific type(s) of incoming message events.
     # Listener will be called later with received message instance as its argument.
     # Returns subscriber id to allow unsubscribing
-    def subscribe(*args, &block)
+    def subscribe *args, &block
       subscriber = args.last.respond_to?(:call) ? args.pop : block
-      subscriber_id = random_id
+      id = random_id
 
       raise ArgumentError.new "Need subscriber proc or block" unless subscriber.is_a? Proc
 
@@ -118,50 +111,110 @@ module IB
         message_classes =
             case
               when what.is_a?(Class) && what < Messages::Incoming::AbstractMessage
-                what
+                [what]
               when what.is_a?(Symbol)
-                Messages::Incoming.const_get(what)
+                [Messages::Incoming.const_get(what)]
               when what.is_a?(Regexp)
                 Messages::Incoming::Table.values.find_all { |klass| klass.to_s =~ what }
               else
                 raise ArgumentError.new "#{what} must represent incoming IB message class"
             end
-        [message_classes].flatten.each do |message_class|
+        message_classes.flatten.each do |message_class|
           # TODO: Fix: RuntimeError: can't add a new key into hash during iteration
-          subscribers[message_class][subscriber_id] = subscriber
+          subscribers[message_class][id] = subscriber
         end
       end
-      subscriber_id
+      id
     end
 
     # Remove all subscribers with specific subscriber id (TODO: multiple ids)
-    def unsubscribe(subscriber_id)
+    def unsubscribe *ids
+      removed = []
+      ids.each do |id|
+        removed_at_id = subscribers.map { |_, subscribers| subscribers.delete id }.compact
+        raise "No subscribers with id #{id}" if removed_at_id.empty?
+        removed << removed_at_id
+      end
+      removed.flatten
+    end
+
+    # Message subscribers. Key is the message class to listen for.
+    # Value is a Hash of subscriber Procs, keyed by their subscription id.
+    # All subscriber Procs will be called with the message instance
+    # as an argument when a message of that type is received.
+    def subscribers
+      @subscribers ||= Hash.new { |hash, subs| hash[subs] = Hash.new }
+    end
+
+    ## Check if subscribers for given type exists
+    #def subscribed? message_type
+    #  message_type
+    #  (subscribers[message_type.class] ||
+    #      subscribers[message_type.class] ||
+    #      subscribers[message_type]).empty?
+    #end
+
+    ### Working with received messages Hash
+
+    # Hash of received messages, keyed by message type
+    def received
+      @received ||= Hash.new { |hash, message_type| hash[message_type] = Array.new }
+    end
 
-      subscribers.each do |message_class, message_subscribers|
-        message_subscribers.delete subscriber_id
+    # Check if messages of given type were received at_least n times
+    def received? message_type, times=1
+      received[message_type].size >= times
+    end
+
+    # Clear received messages Hash
+    def clear_received message_type=nil
+      if message_type
+        received[message_type].clear
+      else
+        received.each { |_, message_type| message_type.clear }
       end
     end
 
-    # Send an outgoing message.
-    def send_message(what, *args)
-      message =
-          case
-            when what.is_a?(Messages::Outgoing::AbstractMessage)
-              what
-            when what.is_a?(Class) && what < Messages::Outgoing::AbstractMessage
-              what.new *args
-            when what.is_a?(Symbol)
-              Messages::Outgoing.const_get(what).new *args
-            else
-              raise ArgumentError.new "Only able to send outgoing IB messages"
+    # Wait for specific condition(s) - given as callable/block, or
+    # message type(s) - given as Symbol or [Symbol, times] pair.
+    # Timeout after given time or 2 seconds.
+    def wait_for *args, &block
+      time = args.find { |arg| arg.is_a? Numeric } || 2
+      timeout = Time.now + time
+      args.push(block) if block
+
+      sleep 0.1 until timeout < Time.now ||
+          args.inject(true) do |result, arg|
+            result && if arg.is_a?(Symbol)
+                        received?(arg)
+                      elsif arg.is_a?(Array)
+                        received?(*arg)
+                      elsif arg.respond_to?(:call)
+                        arg.call
+                      else
+                        true
+                      end
           end
-      raise "Not able to send messages, IB not connected!" unless connected?
-      message.send_to(@server)
     end
 
-    alias dispatch send_message # Legacy alias
+    ### Working with Incoming messages from IB
+
+    # Start reader thread that continuously reads messages from server in background.
+    # If you don't start reader, you should manually poll @server[:socket] for messages
+    # or use #process_messages(msec) API.
+    def start_reader
+      Thread.abort_on_exception = true
+      @reader_running = true
+      @server[:reader] = Thread.new do
+        process_messages while @reader_running
+      end
+    end
 
-    # Process incoming messages during *poll_time* (200) msecs
+    def reader_running?
+      @reader_running && @server[:reader] && @server[:reader].alive?
+    end
+
+    # Process incoming messages during *poll_time* (200) msecs, nonblocking
     def process_messages poll_time = 200 # in msec
       time_out = Time.now + poll_time/1000.0
       while (time_left = time_out - Time.now) > 0
@@ -170,27 +223,48 @@ module IB
       end
     end
 
-    # Process single incoming message (blocking)
+    # Process single incoming message (blocking!)
     def process_message
-      # This read blocks!
-      msg_id = @server[:socket].read_int
+      msg_id = @server[:socket].read_int # This read blocks!
 
       # Debug:
-      unless [1, 2, 4, 6, 7, 8, 9, 12, 21, 53].include? msg_id
-        log.debug "Got message #{msg_id} (#{Messages::Incoming::Table[msg_id]})"
-      end
+      log.debug "Got message #{msg_id} (#{Messages::Incoming::Table[msg_id]})"
 
       # Create new instance of the appropriate message type, and have it read the message.
       # NB: Failure here usually means unsupported message type received
       msg = Messages::Incoming::Table[msg_id].new(@server[:socket])
 
+      # Deliver message to all registered subscribers, alert if no subscribers
       subscribers[msg.class].each { |_, subscriber| subscriber.call(msg) }
       log.warn "No subscribers for message #{msg.class}!" if subscribers[msg.class].empty?
+
+      # Collect all received messages into a @received Hash
+      received[msg.message_type] << msg if @options[:received]
     end
 
-    # Place Order (convenience wrapper for message :PlaceOrder).
-    # Assigns client_id and order_id fields to placed order.
-    # Returns order_id.
+    ### Sending Outgoing messages to IB
+
+    # Send an outgoing message.
+    def send_message what, *args
+      message =
+          case
+            when what.is_a?(Messages::Outgoing::AbstractMessage)
+              what
+            when what.is_a?(Class) && what < Messages::Outgoing::AbstractMessage
+              what.new *args
+            when what.is_a?(Symbol)
+              Messages::Outgoing.const_get(what).new *args
+            else
+              raise ArgumentError.new "Only able to send outgoing IB messages"
+          end
+      raise "Not able to send messages, IB not connected!" unless connected?
+      message.send_to(@server)
+    end
+
+    alias dispatch send_message # Legacy alias
+
+    # Place Order (convenience wrapper for send_message :PlaceOrder).
+    # Assigns client_id and order_id fields to placed order. Returns assigned order_id.
     def place_order order, contract
       send_message :PlaceOrder,
                    :order => order,
@@ -202,24 +276,13 @@ module IB
       order.order_id
     end
 
-    # Cancel Orders by their id (convenience wrapper for message :CancelOrder).
+    # Cancel Orders by their ids (convenience wrapper for send_message :CancelOrder).
     def cancel_order *order_ids
       order_ids.each do |order_id|
         send_message :CancelOrder, :id => order_id.to_i
       end
     end
 
-    # Start reader thread that continuously reads messages from server in background.
-    # If you don't start reader, you should manually poll @server[:socket] for messages
-    # or use #process_messages(msec) API.
-    def start_reader
-      Thread.abort_on_exception = true
-      @reader_running = true
-      @server[:reader] = Thread.new do
-        process_messages while @reader_running
-      end
-    end
-
     protected
 
     def random_id
@@ -227,6 +290,4 @@ module IB
     end
 
   end # class Connection
-  #IB = Connection # Legacy alias
-
 end # module IB

data/lib/ib-ruby/messages/incoming.rb

@@ -146,7 +146,7 @@ module IB
       # This message is always sent by TWS automatically at connect.
       # The IB::Connection class subscribes to it automatically and stores
       # the order id in its @next_order_id attribute.
-      NextValidID = def_message 9, [:order_id, :int]
+      NextValidID = NextValidId = def_message(9, [:order_id, :int])
 
       NewsBulletins =
           def_message 14, [:request_id, :int], # unique incrementing bulletin ID.
@@ -246,7 +246,7 @@ module IB
                              [:tick_type, :int],
                              [:size, :int]
 
-      TickGeneric = def_message 45, AbstractTick,
+      TickGeneric = def_message [45, 6], AbstractTick,
                                 [:ticker_id, :int],
                                 [:tick_type, :int],
                                 [:value, :decimal]
@@ -256,7 +256,7 @@ module IB
                                [:tick_type, :int],
                                [:value, :string]
 
-      TickEFP = def_message 47, AbstractTick,
+      TickEFP = def_message [47, 6], AbstractTick,
                             [:ticker_id, :int],
                             [:tick_type, :int],
                             [:basis_points, :decimal],

data/lib/ib-ruby/models/bar.rb

@@ -5,17 +5,17 @@ module IB
     # This is a single data point delivered by HistoricData messages.
     # Instantiate with a Hash of attributes, to be auto-set via initialize in Model.
     class Bar < Model
-      attr_accessor :time, # The date-time stamp of the start of the bar. The format is
-                    #        determined by the reqHistoricalData() formatDate parameter.
-                    :open, #   The bar opening price.
-                    :high, #   The high price during the time covered by the bar.
-                    :low, #    The low price during the time covered by the bar.
-                    :close, #  The bar closing price.
-                    :volume, # The bar opening price.
-                    :wap, #    Weighted average price during the time covered by the bar.
-                    :has_gaps, # Whether or not there are gaps in the data.
-                    :trades # int: When TRADES data history is returned, represents number
-                            # of trades that occurred during the time period the bar covers
+      prop :time, # The date-time stamp of the start of the bar. The format is
+           #        determined by the reqHistoricalData() formatDate parameter.
+           :open, #   The bar opening price.
+           :high, #   The high price during the time covered by the bar.
+           :low, #    The low price during the time covered by the bar.
+           :close, #  The bar closing price.
+           :volume, # The bar opening price.
+           :wap, #    Weighted average price during the time covered by the bar.
+           :has_gaps, # Whether or not there are gaps in the data.
+           :trades # int: When TRADES data history is returned, represents number
+                   # of trades that occurred during the time period the bar covers
 
       def to_s
         "<Bar #{time}: wap: #{wap}, OHLC: #{open}, #{high}, #{low}, #{close}, " +

data/lib/ib-ruby/models/combo_leg.rb

@@ -16,35 +16,29 @@ module IB
       CLOSE = 2 # Close. This value is only valid for institutional customers.
       UNKNOWN = 3
 
-      attr_accessor :con_id, # int: The unique contract identifier specifying the security.
-                    :ratio, # int: Select the relative number of contracts for the leg you
-                    #              are constructing. To help determine the ratio for a
-                    #              specific combination order, refer to the Interactive
-                    #              Analytics section of the User's Guide.
-
-                    :action, # String: BUY/SELL/SSHORT/SSHORTX
-                    #          The side (buy or sell) for the leg you are constructing.
-                    :exchange, # String: exchange to which the complete combination
-                    #            order will be routed.
-                    :open_close, # int: Specifies whether the order is an open or close order.
-                    #              Valid values: ComboLeg::SAME/OPEN/CLOSE/UNKNOWN
-
-                    # For institutional customers only! For stock legs when doing short sale
-                    :short_sale_slot, # int: 0 - retail, 1 = clearing broker, 2 = third party
-                    :designated_location, # String: Only for shortSaleSlot == 2.
-                    #                    Otherwise leave blank or orders will be rejected.
-                    :exempt_code # int: ?
-
-      def initialize opts = {}
-        @con_id = 0
-        @ratio = 0
-        @open_close = SAME
-        @short_sale_slot = 0
-        @designated_location = ''
-        @exempt_code = -1
-
-        super opts
-      end
+      prop :con_id, # int: The unique contract identifier specifying the security.
+           :ratio, # int: Select the relative number of contracts for the leg you
+           #              are constructing. To help determine the ratio for a
+           #              specific combination order, refer to the Interactive
+           #              Analytics section of the User's Guide.
+
+           :action, # String: BUY/SELL/SSHORT/SSHORTX The side (buy or sell) for the leg.
+           :exchange, # String: exchange to which the complete combo order will be routed.
+           :open_close, # int: Specifies whether the order is an open or close order.
+           #              Valid values: ComboLeg::SAME/OPEN/CLOSE/UNKNOWN
+
+           # For institutional customers only! For stock legs when doing short sale
+           :short_sale_slot, # int: 0 - retail, 1 = clearing broker, 2 = third party
+           :designated_location, # String: Only for shortSaleSlot == 2.
+           #                    Otherwise leave blank or orders will be rejected.
+           :exempt_code # int: ?
+
+      DEFAULT_PROPS = {:con_id => 0,
+                       :ratio => 0,
+                       :open_close => SAME,
+                       :short_sale_slot => 0,
+                       :designated_location => '',
+                       :exempt_code => -1, }
 
       # Some messages include open_close, some don't. wtf.
       def serialize *fields

data/lib/ib-ruby/models/contract/bag.rb

@@ -13,19 +13,51 @@ module IB
         # The exception is for a STK legs, which must specify the SMART exchange.
         # 2. :symbol => "USD" For combo Contract, this is an arbitrary value (like �USD�)
 
+        attr_reader :legs # leg definitions for this contract.
+
+        alias combo_legs legs
+        alias combo_legs_description legs_description
+        alias combo_legs_description= legs_description=
+
         def initialize opts = {}
           super opts
-          @sec_type = IB::SECURITY_TYPES[:bag]
+          @legs = Array.new
+          self[:sec_type] = IB::SECURITY_TYPES[:bag]
         end
 
         def description
-          @description || to_human
+          self[:description] || to_human
         end
 
         def to_human
           "<Bag: #{[symbol, exchange, currency].join(' ')} legs: #{legs_description} >"
         end
 
+        ### Leg-related methods
+        # TODO: Rewrite with legs and legs_description being strictly in sync...
+
+        # TODO: Find a way to serialize legs without references...
+        # IB-equivalent leg description.
+        def legs_description
+          self[:legs_description] || legs.map { |leg| "#{leg.con_id}|#{leg.weight}" }.join(',')
+        end
+
+        def serialize_legs *fields
+          return [0] if legs.empty?
+          [legs.size, legs.map { |leg| leg.serialize *fields }]
+        end
+
+        # Check if two Contracts have same legs (maybe in different order)
+        def same_legs? other
+          legs == other.legs ||
+              legs_description.split(',').sort == other.legs_description.split(',').sort
+        end
+
+        # Contract comparison
+        def == other
+          super && same_legs?(other)
+        end
+
       end # class Bag
 
       TYPES[IB::SECURITY_TYPES[:bag]] = Bag

data/lib/ib-ruby/models/contract/option.rb

@@ -44,8 +44,8 @@ module IB
 
         def initialize opts = {}
           super opts
-          @sec_type = IB::SECURITY_TYPES[:option]
-          @description ||= osi ? osi : "#{symbol} #{strike} #{right} #{expiry}"
+          self[:sec_type] = IB::SECURITY_TYPES[:option]
+          self[:description] ||= osi ? osi : "#{symbol} #{strike} #{right} #{expiry}"
         end
 
         def to_human