File Coverage

blib/lib/Finance/InteractiveBrokers/API.pm

Criterion	Covered	Total	%
statement	55	55	100.0
branch	19	24	79.1
condition	4	6	66.6
subroutine	16	16	100.0
pod	10	10	100.0
total	104	111	93.6

package Finance::InteractiveBrokers::API;
#
#   Finance::InteractiveBrokers::API - Convenience functions for IB API
#
#   Copyright (c) 2010-2013 Jason McManus
#
#   Full POD documentation after __END__
#

use Carp qw( croak confess );
use strict;
use warnings;

###
### Variables
###

use vars qw( @ISA @EXPORT_OK $VERSION $TRUE $FALSE $KEEP $DELETE $REQUIRED );
BEGIN
{
    require Exporter;
    @ISA       = qw( Exporter );
    @EXPORT_OK = qw( api_version );
    $VERSION   = '0.04';
}

*TRUE     = \1;
*FALSE    = \0;
*KEEP     = \0;
*DELETE   = \1;
*REQUIRED = \2;

our %our_args = (
    version => $DELETE | $REQUIRED,
);

# IB API method and event data structures, keyed by version
my $DEFAULT_API_VERSION = '9.64';
my $methods = {};
my $events = {};
my $methods_arr = {
    '9.64' => [
        # Our add-ons
        qw(
            processMessages
            setSelectTimeout
        ),
        # Official API
        # XXX: API Docs and source code differ (I use the source code names):
        #           Docs                C++ headers
        #           -------------------------------------------
        #           reqIDs()            reqIds()
        #           setLogLevel()       setServerLogLevel()
        qw(
            eConnect
            eDisconnect
            isConnected
            reqCurrentTime
            serverVersion
            setServerLogLevel
            checkMessages
            TwsConnectionTime

            reqMktData
            cancelMktData
            calculateImpliedVolatility
            cancelCalculateImpliedVolatility
            calculateOptionPrice
            cancelCalculateOptionPrice

            placeOrder
            cancelOrder
            reqOpenOrders
            reqAllOpenOrders
            reqAutoOpenOrders
            reqIds
            exerciseOptions

            reqAccountUpdates

            reqExecutions

            reqContractDetails

            reqMktDepth
            cancelMktDepth

            reqNewsBulletins
            cancelNewsBulletins

            reqManagedAccts
            requestFA
            replaceFA

            reqHistoricalData
            cancelHistoricalData

            reqScannerParameters
            reqScannerSubscription
            cancelScannerSubscription

            reqRealTimeBars
            cancelRealTimeBars

            reqFundamentalData
            cancelFundamentalData
        ),
    ],
};
$methods_arr->{'9.65'} = $methods_arr->{'9.64'};
$methods_arr->{'9.66'} = [
    @{ $methods_arr->{'9.65'} },
    qw(
        reqMarketDataType
    ),
    # UNDOCUMENTED
    qw(
        reqGlobalCancel
    ),
];
$methods_arr->{'9.67'} = $methods_arr->{'9.66'};

my $events_arr = {
    '9.64' => [
        qw(
            winError
            error
            connectionClosed
            currentTime

            tickPrice
            tickSize
            tickOptionComputation
            tickGeneric
            tickString
            tickEFP
            tickSnapshotEnd

            orderStatus
            openOrder
            nextValidId

            updateAccountValue
            updatePortfolio
            updateAccountTime

            updateNewsBulletin

            contractDetails
            contractDetailsEnd
            bondContractDetails

            execDetails
            execDetailsEnd

            updateMktDepth
            updateMktDepthL2

            managedAccounts
            receiveFA

            historicalData

            scannerParameters
            scannerData
            scannerDataEnd

            realtimeBar

            fundamentalData

            deltaNeutralValidation
        ),
        # These are in the headers, but apparently not documented
        qw(
            openOrderEnd
            accountDownloadEnd
        )
    ],
};
$events_arr->{'9.65'} = $events_arr->{'9.64'};
$events_arr->{'9.66'} = [
    @{ $events_arr->{'9.65'} },
    qw(
        marketDataType
    ),
];
$events_arr->{'9.67'} = [
    @{ $events_arr->{'9.66'} },
    qw(
        commissionReport
    ),
];

# Cram them into a hash for O(1) lookup time
for my $ver ( keys( %$methods_arr ) )
{
    $methods->{$ver} = { map { $_ => 1 } @{ $methods_arr->{$ver} } };
}
for my $ver ( keys( %$events_arr ) )
{
    $events->{$ver}  = { map { $_ => 1 } @{ $events_arr->{$ver} } };
}

###
### Constructor
###

sub new
{
    my( $class, @args ) = @_;
    croak( "$class requires an even number of params" ) if( @args & 1 );

    my $self = {
        version => $DEFAULT_API_VERSION,    # IB API version
    };

    bless( $self, $class );

    my @leftover = $self->initialize( @args );

    # Make sure we received a valid API version
    confess( 'API version \'' . $self->api_version . '\' is unknown;' .
             " usable versions are: " .
             join( ' ', $self->versions ) . "\n" )
        unless( exists( $methods->{$self->api_version} ) );

    return( $self );
}

sub initialize
{
    my( $self, %args ) = @_;

    # Cycle through the args, grab what's for us, and delete if appropriate
    for( keys( %args ) )
    {
        if( exists( $our_args{lc $_} ) )
        {
            $self->{lc $_} = $args{$_};
            delete( $args{$_} )
                if( $our_args{lc $_} & $DELETE );
        }
    }

    # Check all required args
    for( keys( %our_args ) )
    {
        if( $our_args{$_} & $REQUIRED )
        {
            confess( "$_ is a required argument" )
                if( ( not exists $self->{lc $_} ) or
                    ( not defined $self->{lc $_} ) );
        }
    }

    return( %args );
}

###
### Class methods
###

sub api_versions
{
    return( sort keys( %$methods ) );
}

###
### Methods
###

sub methods
{
    my $self = shift;

    return( @{ $methods_arr->{$self->api_version} } );
}

sub events
{
    my $self = shift;

    return( @{ $events_arr->{$self->api_version} } );
}

sub everything
{
    my $self = shift;

    return( ( ( $self->methods() ), ( $self->events() ) ) );
}

###
### Predicates
###

sub is_method
{
    my( $self, $name ) = ( shift, shift );

    return $FALSE unless( defined( $name ) );

    return( exists( $methods->{$self->api_version}->{$name} )
              ? $TRUE
              : $FALSE );
}

sub is_event
{
    my( $self, $name ) = ( shift, shift );

    return $FALSE unless( defined( $name ) );

    return( exists( $events->{$self->api_version}->{$name} )
              ? $TRUE
              : $FALSE );
}

sub in_api
{
    my( $self, $name ) = ( shift, shift );

    return $FALSE unless( defined( $name ) );

    return( ( $self->is_method( $name ) or $self->is_event( $name ) )
                ? $TRUE
                : $FALSE );
}

###
### Accessors
###

sub api_version
{
    my $self = shift;

    return( $self->{version} );
}

###
### Method aliases
###

no warnings 'once';
*version  = *api_version;
*versions = *api_versions;

1;

__END__