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.