binary-com / perl-finance-calendar

NAME

Finance::Calendar - represents the trading calendar.

SYNOPSIS

use Finance::Calendar;
use Date::Utility;

my $calendar = {
    holidays => {
        "25-Dec-2013" => {
            "Christmas Day" => [qw(FOREX METAL)],
        },
        "1-Jan-2014" => {
            "New Year's Day" => [qw( FOREX METAL)],
        },
        "1-Apr-2013" => {
            "Easter Monday" => [qw( USD)],
        },
    },
    early_closes => {
        '24-Dec-2009' => {
            '16:30' => ['HKSE'],
        },
        '22-Dec-2016' => {
            '18:00' => ['FOREX', 'METAL'],
        },
    },
    late_opens => {
        '24-Dec-2010' => {
            '14:30' => ['HKSE'],
        },
    },
};
my $calendar = Finance::Calendar->new(calendar => $calendar);
my $now = Date::Utility->new;

# Does London Stocks Exchange trade on $now
$calendar->trades_on(Finance::Exchange->create_exchange('LSE'), $now);

# Is it a country holiday for the United States on $now
$calendar->is_holiday_for('USD', $now);

# Returns the opening time of Australian Stocks Exchange on $now
$calendar->opening_on(Finance::Exchange->create_exchange('ASX'), $now);

# Returns the closing time of Forex on $now
$calendar->closing_on(Finance::Exchange->create_exchange('FOREX'), $now);
...

DESCRIPTION

This class is responsible for providing trading times or holidays related information of a given financial stock exchange on a specific date.

ATTRIBUTES - Object Construction

calendar

A hash reference that has information on: - exchange and country holidays - late opens - early closes

METHODS - TRADING DAYS RELATED

trades_on

->trades_on($exchange_object, $date_object);

Returns true if trading is done on the day of a given Date::Utility.

trade_date_before

->trade_date_before($exchange_object, $date_object);

Returns a Date::Utility object for the previous trading day of an exchange for the given date.

trade_date_after

->trade_date_after($exchange_object, $date_object);

Returns a Date::Utility object of the next trading day of an exchange for a given date.

trading_date_for

->trading_date_for($exchange_object, $date_object);

The date on which trading is considered to be taking place even if it is not the same as the GMT date. Note that this does not handle trading dates are offset forward beyond the next day (24h). It will need additional work if these are found to exist.

Returns a Date object representing midnight GMT of the trading date.

calendar_days_to_trade_date_after

->calendar_days_to_trade_date_after($exchange_object, $date_object);

Returns the number of calendar days between a given Date::Utility and the next day on which trading is open.

trading_days_between

->trading_days_between($exchange_object, Date::Utility->new('4-May-10'),Date::Utility->new('5-May-10'));

Returns the number of trading days _between_ two given dates.

holiday_days_between

->holiday_days_between($exchange_object, Date::Utility->new('4-May-10'),Date::Utility->new('5-May-10'));

Returns the number of holidays _between_ two given dates.

METHODS - TRADING TIMES RELATED.

is_open

->is_open($exchange_object);

Returns true is exchange is open now, false otherwise.

is_open_at

->is_open_at($exchange_object, $epoch);

Return true is exchange is open at the given epoch, false otherwise.

seconds_since_open_at

->seconds_since_open_at($exchange_object, $epoch);

Returns the number of seconds since the exchange opened from the given epoch.

seconds_since_close_at

->seconds_since_close_at($exchange_object, $epoch);

Returns the number of seconds since the exchange closed from the given epoch.

opening_on

->opening_on($exchange_object, Date::Utility->new('25-Dec-10')); # returns undef (given Xmas is a holiday)

Returns the opening time (Date::Utility) of the exchange for a given Date::Utility, undefined otherwise.

closing_on

->closing_on($exchange_object, Date::Utility->new('25-Dec-10')); # returns undef (given Xmas is a holiday)

Returns the closing time (Date::Utility) of the exchange for a given Date::Utility, undefined otherwise.

trading_breaks

->trading_breaks($exchange_object, $date_object);

Defines the breaktime for this exchange.

regularly_adjusts_trading_hours_on

Returns a hashref of special-case changes that may apply on specific trading days. Currently, this applies on Fridays only:

• for forex or metals

Example:

$calendar->regularly_adjusts_trading_hours_on('FOREX', time);

closes_early_on

->closes_early_on($exchange_object, $date_object);

Returns the closing time as a Date::Utility instance if the exchange closes early on the given date, or undef.

opens_late_on

->opens_late_on($exchange_object, $date_object);

Returns true if the exchange opens late on the given date.

seconds_of_trading_between_epochs

->seconds_of_trading_between_epochs($exchange_object, $epoch1, $epoch2);

Get total number of seconds of trading time between two epochs accounting for breaks.

regular_trading_day_after

->regular_trading_day_after($exchange_object, $date_object);

Returns a Date::Utility object on a trading day where the exchange does not close early or open late after the given date.

trading_period

->trading_period('HKSE', Date::Utility->new);

Returns an array reference of hash references of open and close time of the given exchange and epoch

is_holiday_for

Check if it is a holiday for a specific exchange or a country on a specific day

->is_holiday_for('ASX', '2013-01-01'); # Australian exchange holiday ->is_holiday_for('USD', Date::Utility->new); # United States country holiday

Returns the description of the holiday if it is a holiday.

is_in_dst_at

->is_in_dst_at($exchange_object, $date_object);

Is this exchange trading on daylight savings times for the given epoch?

get_exchange_open_times

Query an exchange for valid opening times. Expects 3 parameters:

• $exchange - a Finance::Exchange instance
• $date - a Date::Utility
• $which - which market information to request, see below

The possible values for $which include:

• daily_open
• daily_close
• trading_breaks

Returns either undef, a single Date::Utility, or an arrayref of Date::Utility instances.

next_open_at

->next_open_at($exchange_object, Date::Utility->new('2023-02-16 15:30:00'));

Returns Date::Utility object of the next opening date and time.

Returns undef if exchange is open for the requested date.