ib-ruby 0.5.0 → 0.5.2

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

@@ -83,7 +83,7 @@ module IB
       end
 
       # Macro that defines short message classes using a one-liner
-      def self.def_message message_id, *keys, &human_block
+      def self.def_message message_id, *keys, &to_human
         base = keys.first.is_a?(Class) ? keys.shift : AbstractMessage
         Class.new(base) do
           @message_id = message_id
@@ -93,7 +93,7 @@ module IB
             load_map *keys
           end
 
-          define_method(:to_human, &human_block) if human_block
+          define_method(:to_human, &to_human) if to_human
         end
       end
 
@@ -152,7 +152,7 @@ module IB
       NewsBulletins =
           def_message 14, [:id, :int], # unique incrementing bulletin ID.
                       [:type, :int], # Type of bulletin. Valid values include:
-                      #     1 = Reqular news bulletin
+                      #     1 = Regular news bulletin
                       #     2 = Exchange no longer available for trading
                       #     3 = Exchange is available for trading
                       [:text, :string], # The bulletin's message text.
@@ -172,7 +172,7 @@ module IB
       #                                 FA configuration information.
 
       # Receives an XML document that describes the valid parameters that a scanner
-      # subscription can have.
+      # subscription can have (for outgoing RequestScannerSubscription message).
       ScannerParameters = def_message 19, [:xml, :string]
 
       # Receives the current system time on the server side.
@@ -287,10 +287,11 @@ module IB
         @message_id = 21
 
         # Read @data[key] if it was computed (received value above limit)
-        # Leave @data[key] nil if received value below limit ("not yet computed" indicator)
+        # Leave @data[key] nil if received value below limit ("not yet computed")
         def read_computed key, limit
-          value = @socket.read_decimal # limit-1 is the "not yet computed" indicator
-          @data[key] = value < limit ? nil : value
+          value = @socket.read_decimal
+          # limit is the "not yet computed" indicator
+          @data[key] = value <= limit ? nil : value
         end
 
         def load
@@ -298,14 +299,14 @@ module IB
 
           @data[:id] = @socket.read_int # ticker_id
           @data[:tick_type] = @socket.read_int
-          read_computed :implied_volatility, 0 #-1 is the "not yet computed" indicator
-          read_computed :delta, -1 #            -2 is the "not yet computed" indicator
-          read_computed :option_price, 0 #      -1 is the "not yet computed" indicator
-          read_computed :pv_dividend, 0 #       -1 is the "not yet computed" indicator
-          read_computed :gamma, -1 #            -2 is the "not yet computed" indicator
-          read_computed :vega, -1 #             -2 is the "not yet computed" indicator
-          read_computed :theta, -1 #            -2 is the "not yet computed" indicator
-          read_computed :under_price, 0 #       -1 is the "not yet computed" indicator
+          read_computed :implied_volatility, -1 #-1 is the "not yet computed" indicator
+          read_computed :delta, -2 #             -2 is the "not yet computed" indicator
+          read_computed :option_price, -1 #      -1 is the "not yet computed" indicator
+          read_computed :pv_dividend, -1 #       -1 is the "not yet computed" indicator
+          read_computed :gamma, -2 #             -2 is the "not yet computed" indicator
+          read_computed :vega, -2 #              -2 is the "not yet computed" indicator
+          read_computed :theta, -2 #             -2 is the "not yet computed" indicator
+          read_computed :under_price, -1 #       -1 is the "not yet computed" indicator
         end
 
         def to_human
@@ -536,6 +537,7 @@ module IB
                                    :order_types => @socket.read_string,
                                    :valid_exchanges => @socket.read_string,
                                    :price_magnifier => @socket.read_int,
+
                                    :under_con_id => @socket.read_int,
                                    :long_name => @socket.read_string,
                                    :primary_exchange => @socket.read_string,
@@ -548,6 +550,7 @@ module IB
                                    :liquid_hours => @socket.read_string
         end
       end # ContractData
+      ContractDetails = ContractData
 
       class ExecutionData < AbstractMessage
         @message_id = 11
@@ -587,11 +590,24 @@ module IB
       end # ExecutionData
 
       # HistoricalData contains following @data:
+      # General:
       #    :id - The ID of the request to which this is responding
-      #    :count - Number of data points returned (size of :results).
+      #    :count - Number of Historical data points returned (size of :results).
       #    :results - an Array of Historical Data Bars
-      #    :start_date
-      #    :end_date
+      #    :start_date - beginning of returned Historical data period
+      #    :end_date   - end of returned Historical data period
+      # Each returned Bar in @data[:results] Array contains this data:
+      #    :date - The date-time stamp of the start of the bar. The format is
+      #       determined by the RequestHistoricalData 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 volume during the time covered by the bar.
+      #    :trades - When TRADES historical data is returned, represents number of trades
+      #             that occurred during the time period the bar covers
+      #    :wap - The weighted average price during the time covered by the bar.
+      #    :has_gaps - Whether or not there are gaps in the data.
       class HistoricalData < AbstractMessage
         @message_id = 17
 

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

@@ -78,16 +78,18 @@ module IB
       CancelNewsBulletins = def_message 13
       RequestAllOpenOrders = def_message 16
       RequestManagedAccounts = def_message 17
+      # Requests an XML document that describes the valid parameters that a scanner
+      # subscription can have (for outgoing RequestScannerSubscription message).
       RequestScannerParameters = def_message 24
       RequestCurrentTime = def_message 49
       RequestGlobalCancel = def_message 58
 
       # Data format is: @data = { :id => ticker_id}
-      CancelScannerSubscription = def_message 23
       CancelMarketData = def_message 2
+      CancelMarketDepth = def_message 11
+      CancelScannerSubscription = def_message 23
       CancelHistoricalData = def_message 25
       CancelRealTimeBars = def_message 51
-      CancelMarketDepth = def_message 11
 
       # Data format is: @data = { :id => request_id }
       CancelFundamentalData = def_message 53
@@ -112,53 +114,84 @@ module IB
       RequestFA = def_message 18, 1, :fa_data_type
       # data = { :fa_data_type => int, :xml => String }
       ReplaceFA = def_message 19, 1, :fa_data_type, :xml
-
-      # Data is { :subscribe => boolean,
-      #           :account_code => String: only necessary for advisor accounts. Set it
-      #                            to empty ('') for a standard account. }
-      class RequestAccountData < AbstractMessage
-        @message_id = 6
-        @version = 2
-
-        def encode
-          [super,
-           @data[:subscribe],
-           @data[:account_code] || '']
-        end
-      end
+      # @data = { :subscribe => boolean,
+      #           :account_code => Advisor accounts only. Empty ('') for a standard account. }
+      RequestAccountData = def_message 6, 2, :subscribe, :account_code
       RequestAccountUpdates = RequestAccountData
 
 
       ### Defining (complex) Outgoing Message classes for IB:
 
-      # data = { :id => ticker_id (int), :subscription => ScannerSubscription}
+      # Start receiving market scanner results through the ScannerData messages.
+      # @data = { :id => ticker_id (int),
+      #  :number_of_rows => int: number of rows of data to return for a query.
+      #  :instrument => The instrument type for the scan. Values include
+      #                                'STK', - US stocks
+      #                                'STOCK.HK' - Asian stocks
+      #                                'STOCK.EU' - European stocks
+      #  :location_code => Legal Values include:
+      #                           � STK.US - US stocks
+      #                           � STK.US.MAJOR - US stocks (without pink sheet)
+      #                           � STK.US.MINOR - US stocks (only pink sheet)
+      #                           � STK.HK.SEHK - Hong Kong stocks
+      #                           � STK.HK.ASX - Australian Stocks
+      #                           � STK.EU - European stocks
+      #  :scan_code => The type of the scan, such as HIGH_OPT_VOLUME_PUT_CALL_RATIO.
+      #  :above_price => double: Only contracts with a price above this value.
+      #  :below_price => double: Only contracts with a price below this value.
+      #  :above_volume => int: Only contracts with a volume above this value.
+      #  :market_cap_above => double: Only contracts with a market cap above this
+      #  :market_cap_below => double: Only contracts with a market cap below this value.
+      #  :moody_rating_above => Only contracts with a Moody rating above this value.
+      #  :moody_rating_below => Only contracts with a Moody rating below this value.
+      #  :sp_rating_above => Only contracts with an S&P rating above this value.
+      #  :sp_rating_below => Only contracts with an S&P rating below this value.
+      #  :maturity_date_above => Only contracts with a maturity date later than this
+      #  :maturity_date_below => Only contracts with a maturity date earlier than this
+      #  :coupon_rate_above => double: Only contracts with a coupon rate above this
+      #  :coupon_rate_below => double: Only contracts with a coupon rate below this
+      #  :exclude_convertible => Exclude convertible bonds.
+      #  :scanner_setting_pairs => Used with the scan_code to help further narrow your query.
+      #                            Scanner Setting Pairs are delimited by slashes, making
+      #                            this parameter open ended. Example is "Annual,true" -
+      #                            when used with 'Top Option Implied Vol % Gainers' scan
+      #                            would return annualized volatilities.
+      #  :average_option_volume_above =>  int: Only contracts with average volume above this
+      #  :stock_type_filter => Valid values are:
+      #                          'ALL' (excludes nothing)
+      #                          'STOCK' (excludes ETFs)
+      #                          'ETF' (includes ETFs) }
+      # ------------
+      # To learn all valid parameter values that a scanner subscription can have,
+      # first subscribe to ScannerParameters and send RequestScannerParameters message.
+      # Available scanner parameters values will be listed in received XML document.
       class RequestScannerSubscription < AbstractMessage
         @message_id = 22
         @version = 3
 
         def encode
           [super,
-           @data[:subscription].number_of_rows || EOL,
-           @data[:subscription].instrument,
-           @data[:subscription].location_code,
-           @data[:subscription].scan_code,
-           @data[:subscription].above_price || EOL,
-           @data[:subscription].below_price || EOL,
-           @data[:subscription].above_volume || EOL,
-           @data[:subscription].market_cap_above || EOL,
-           @data[:subscription].market_cap_below || EOL,
-           @data[:subscription].moody_rating_above,
-           @data[:subscription].moody_rating_below,
-           @data[:subscription].sp_rating_above,
-           @data[:subscription].sp_rating_below,
-           @data[:subscription].maturity_date_above,
-           @data[:subscription].maturity_date_below,
-           @data[:subscription].coupon_rate_above || EOL,
-           @data[:subscription].coupon_rate_below || EOL,
-           @data[:subscription].exclude_convertible,
-           @data[:subscription].average_option_volume_above,
-           @data[:subscription].scanner_setting_pairs,
-           @data[:subscription].stock_type_filter
+           @data[:number_of_rows] || -1, # was: EOL,
+           @data[:instrument],
+           @data[:location_code],
+           @data[:scan_code],
+           @data[:above_price] || EOL,
+           @data[:below_price] || EOL,
+           @data[:above_volume] || EOL,
+           @data[:market_cap_above] || EOL,
+           @data[:market_cap_below] || EOL,
+           @data[:moody_rating_above],
+           @data[:moody_rating_below],
+           @data[:sp_rating_above],
+           @data[:sp_rating_below],
+           @data[:maturity_date_above],
+           @data[:maturity_date_below],
+           @data[:coupon_rate_above] || EOL,
+           @data[:coupon_rate_below] || EOL,
+           @data[:exclude_convertible],
+           @data[:average_option_volume_above] || EOL, # ?
+           @data[:scanner_setting_pairs],
+           @data[:stock_type_filter]
           ]
         end
       end # RequestScannerSubscription
@@ -198,8 +231,7 @@ module IB
                           @data[:tick_list]
                       end
           [super,
-           @data[:contract].con_id, # part of serialize?
-           @data[:contract].serialize,
+           @data[:contract].serialize_long(:con_id),
            @data[:contract].serialize_combo_legs,
            @data[:contract].serialize_under_comp,
            tick_list,
@@ -290,8 +322,7 @@ module IB
               @data[:contract] : Models::Contract.from_ib_ruby(@data[:contract])
 
           [super,
-           contract.serialize,
-           contract.include_expired,
+           contract.serialize_long(:include_expired),
            @data[:end_date_time],
            @data[:bar_size],
            @data[:duration],
@@ -329,7 +360,7 @@ module IB
               @data[:contract] : Models::Contract.from_ib_ruby(@data[:contract])
 
           [super,
-           contract.serialize,
+           contract.serialize_long,
            @data[:bar_size],
            @data[:what_to_show].to_s.upcase,
            @data[:use_rth]]
@@ -343,11 +374,7 @@ module IB
 
         def encode
           [super,
-           @data[:contract].con_id, # part of serialize?
-           @data[:contract].serialize(:short),
-           @data[:contract].include_expired,
-           @data[:contract].sec_id_type,
-           @data[:contract].sec_id]
+           @data[:contract].serialize_short(:con_id, :include_expired, :sec_id)]
         end
       end # RequestContractData
       RequestContractDetails = RequestContractData # alias
@@ -359,7 +386,7 @@ module IB
 
         def encode
           [super,
-           @data[:contract].serialize(:short),
+           @data[:contract].serialize_short,
            @data[:num_rows]]
         end
       end # RequestMarketDepth
@@ -384,7 +411,7 @@ module IB
 
         def encode
           [super,
-           @data[:contract].serialize(:short),
+           @data[:contract].serialize_short,
            @data[:exercise_action],
            @data[:exercise_quantity],
            @data[:account],
@@ -398,76 +425,10 @@ module IB
       class PlaceOrder < AbstractMessage
         @message_id = 3
         @version = 31
-        # int VERSION = (m_serverVersion < MIN_SERVER_VER_NOT_HELD) ? 27 : 31;
 
         def encode
           [super,
-           @data[:contract].serialize,
-           @data[:contract].sec_id_type, # Unimplemented?
-           @data[:contract].sec_id, # Unimplemented?
-           @data[:order].action, # send main order fields
-           @data[:order].total_quantity,
-           @data[:order].order_type,
-           @data[:order].limit_price,
-           @data[:order].aux_price,
-           @data[:order].tif, # send extended order fields
-           @data[:order].oca_group,
-           @data[:order].account,
-           @data[:order].open_close,
-           @data[:order].origin,
-           @data[:order].order_ref,
-           @data[:order].transmit,
-           @data[:order].parent_id,
-           @data[:order].block_order,
-           @data[:order].sweep_to_fill,
-           @data[:order].display_size,
-           @data[:order].trigger_method,
-           @data[:order].outside_rth, # was: ignore_rth
-           @data[:order].hidden,
-           @data[:contract].serialize_combo_legs(:long),
-           '', # send deprecated shares_allocation field
-           @data[:order].discretionary_amount,
-           @data[:order].good_after_time,
-           @data[:order].good_till_date,
-           @data[:order].fa_group,
-           @data[:order].fa_method,
-           @data[:order].fa_percentage,
-           @data[:order].fa_profile,
-           #                                    Institutional short sale slot fields:
-           @data[:order].short_sale_slot, #     0 only for retail, 1 or 2 for institution
-           @data[:order].designated_location, # only populate when short_sale_slot == 2
-           @data[:order].oca_type,
-           @data[:order].rule_80a,
-           @data[:order].settling_firm,
-           @data[:order].all_or_none,
-           @data[:order].min_quantity || EOL,
-           @data[:order].percent_offset || EOL,
-           @data[:order].etrade_only,
-           @data[:order].firm_quote_only,
-           @data[:order].nbbo_price_cap || EOL,
-           @data[:order].auction_strategy || EOL,
-           @data[:order].starting_price || EOL,
-           @data[:order].stock_ref_price || EOL,
-           @data[:order].delta || EOL,
-           @data[:order].stock_range_lower || EOL,
-           @data[:order].stock_range_upper || EOL,
-           @data[:order].override_percentage_constraints,
-           @data[:order].volatility || EOL, #              Volatility orders
-           @data[:order].volatility_type || EOL, #         Volatility orders
-           @data[:order].delta_neutral_order_type, #       Volatility orders
-           @data[:order].delta_neutral_aux_price || EOL, # Volatility orders
-           @data[:order].continuous_update, #              Volatility orders
-           @data[:order].reference_price_type || EOL, #    Volatility orders
-           @data[:order].trail_stop_price || EOL, # TRAIL_STOP_LIMIT stop price
-           @data[:order].scale_init_level_size || EOL, # Scale Orders
-           @data[:order].scale_subs_level_size || EOL, # Scale Orders
-           @data[:order].scale_price_increment || EOL, # Scale Orders
-           @data[:order].clearing_account,
-           @data[:order].clearing_intent,
-           @data[:order].not_held,
-           @data[:contract].serialize_under_comp,
-           @data[:order].serialize_algo,
-           @data[:order].what_if]
+           @data[:order].serialize_with(@data[:contract])]
         end
       end # PlaceOrder
 
@@ -488,7 +449,6 @@ module IB
         @version = 3
 
         def encode
-
           [super,
            @data[:client_id],
            @data[:acct_code],
@@ -497,7 +457,7 @@ module IB
            @data[:sec_type],
            @data[:exchange],
            @data[:side]]
-        end # encode
+        end
       end # RequestExecutions
 
       # Send this message to receive Reuters global fundamental data. There must be
@@ -506,22 +466,14 @@ module IB
       # data = { :id => int: :request_id,
       #          :contract => Contract,
       #          :report_type => String: one of the following:
-      #                             Estimates
-      #                             Financial Statements
-      #                             Summary
-      #        }
+      #                          'Estimates', 'Financial Statements', 'Summary'   }
       class RequestFundamentalData < AbstractMessage
         @message_id = 52
 
         def encode
           [super,
            @data[:request_id],
-           @data[:contract].symbol, # Yet another Contract serialization!
-           @data[:contract].sec_type,
-           @data[:contract].exchange,
-           @data[:contract].primary_exchange,
-           @data[:contract].currency,
-           @data[:contract].local_symbol,
+           @data[:contract].serialize(:primary_exchange), # Minimal serialization set
            @data[:report_type]]
         end
       end # RequestFundamentalData
@@ -534,8 +486,7 @@ module IB
         def encode
           [super,
            @data[:request_id],
-           @data[:contract].con_id, # part of serialize?
-           @data[:contract].serialize,
+           @data[:contract].serialize_long(:con_id),
            @data[:option_price],
            @data[:under_price]]
         end
@@ -551,8 +502,7 @@ module IB
         def encode
           [super,
            @data[:request_id],
-           @data[:contract].con_id, # part of serialize?
-           @data[:contract].serialize,
+           @data[:contract].serialize_long(:con_id),
            @data[:volatility],
            @data[:under_price]]
         end

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

@@ -165,30 +165,29 @@ module IB
         @strike = 0
       end
 
-      # This returns an Array of data from the given contract, in standard format.
+      # This returns an Array of data from the given contract.
       # Different messages serialize contracts differently. Go figure.
-      # Note that it does not include the combo legs.
-      def serialize(type = :long)
-        [symbol,
+      # Note that it does NOT include the combo legs.
+      def serialize(*fields)
+        [(fields.include?(:con_id) ? [con_id] : []),
+         symbol,
          sec_type,
-         expiry,
-         strike,
-         right,
-         multiplier,
-         exchange] +
-            (type == :long ? [primary_exchange] : []) +
-            [currency,
-             local_symbol]
+         (fields.include?(:option) ? [expiry, strike, right, multiplier] : []),
+         exchange,
+         (fields.include?(:primary_exchange) ? [primary_exchange] : []),
+         currency,
+         local_symbol,
+         (fields.include?(:sec_id) ? [sec_id_type, sec_id] : []),
+         (fields.include?(:include_expired) ? [include_expired] : []),
+        ].flatten
       end
 
-      # @Legacy
-      def serialize_long(version)
-        serialize(:long)
+      def serialize_long(*fields)
+        serialize(:option, :primary_exchange, *fields)
       end
 
-      # @Legacy
-      def serialize_short(version)
-        serialize(:short)
+      def serialize_short(*fields)
+        serialize(:option, *fields)
       end
 
       # This produces a string uniquely identifying this contract, in the format used