Module: Holidays

Defined in:
lib/holidays.rb,
lib/holidays/errors.rb,
lib/holidays/version.rb,
lib/holidays/factory/finder.rb,
lib/generated_definitions/ar.rb,
lib/generated_definitions/at.rb,
lib/generated_definitions/au.rb,
lib/generated_definitions/be.rb,
lib/generated_definitions/bg.rb,
lib/generated_definitions/br.rb,
lib/generated_definitions/ca.rb,
lib/generated_definitions/ch.rb,
lib/generated_definitions/cl.rb,
lib/generated_definitions/cr.rb,
lib/generated_definitions/cz.rb,
lib/generated_definitions/de.rb,
lib/generated_definitions/dk.rb,
lib/generated_definitions/el.rb,
lib/generated_definitions/es.rb,
lib/generated_definitions/fi.rb,
lib/generated_definitions/fr.rb,
lib/generated_definitions/gb.rb,
lib/generated_definitions/hk.rb,
lib/generated_definitions/hr.rb,
lib/generated_definitions/hu.rb,
lib/generated_definitions/ie.rb,
lib/generated_definitions/is.rb,
lib/generated_definitions/it.rb,
lib/generated_definitions/jp.rb,
lib/generated_definitions/kr.rb,
lib/generated_definitions/li.rb,
lib/generated_definitions/lt.rb,
lib/generated_definitions/lu.rb,
lib/generated_definitions/ma.rb,
lib/generated_definitions/mx.rb,
lib/generated_definitions/my.rb,
lib/generated_definitions/nl.rb,
lib/generated_definitions/no.rb,
lib/generated_definitions/nz.rb,
lib/generated_definitions/pe.rb,
lib/generated_definitions/ph.rb,
lib/generated_definitions/pl.rb,
lib/generated_definitions/pt.rb,
lib/generated_definitions/ro.rb,
lib/generated_definitions/se.rb,
lib/generated_definitions/sg.rb,
lib/generated_definitions/si.rb,
lib/generated_definitions/sk.rb,
lib/generated_definitions/us.rb,
lib/generated_definitions/ve.rb,
lib/generated_definitions/vi.rb,
lib/generated_definitions/za.rb,
lib/generated_definitions/ups.rb,
lib/generated_definitions/nerc.rb,
lib/generated_definitions/nyse.rb,
lib/generated_definitions/be_fr.rb,
lib/generated_definitions/be_nl.rb,
lib/generated_definitions/fedex.rb,
lib/holidays/factory/definition.rb,
lib/generated_definitions/europe.rb,
lib/generated_definitions/REGIONS.rb,
lib/holidays/core_extensions/date.rb,
lib/holidays/core_extensions/time.rb,
lib/holidays/load_all_definitions.rb,
lib/holidays/finder/context/search.rb,
lib/holidays/date_calculator/easter.rb,
lib/holidays/finder/context/between.rb,
lib/holidays/finder/rules/in_region.rb,
lib/generated_definitions/ecb_target.rb,
lib/holidays/factory/date_calculator.rb,
lib/holidays/finder/rules/year_range.rb,
lib/generated_definitions/scandinavia.rb,
lib/holidays/definition/context/merger.rb,
lib/generated_definitions/north_america.rb,
lib/generated_definitions/united_nations.rb,
lib/holidays/definition/repository/cache.rb,
lib/holidays/definition/validator/region.rb,
lib/holidays/finder/context/next_holiday.rb,
lib/holidays/finder/context/year_holiday.rb,
lib/generated_definitions/federal_reserve.rb,
lib/holidays/date_calculator/day_of_month.rb,
lib/holidays/definition/context/generator.rb,
lib/holidays/finder/context/parse_options.rb,
lib/holidays/definition/repository/regions.rb,
lib/holidays/definition/entity/custom_method.rb,
lib/holidays/definition/parser/custom_method.rb,
lib/holidays/date_calculator/weekend_modifier.rb,
lib/holidays/definition/validator/custom_method.rb,
lib/holidays/finder/context/dates_driver_builder.rb,
lib/holidays/definition/repository/custom_methods.rb,
lib/holidays/definition/context/function_processor.rb,
lib/holidays/definition/decorator/custom_method_proc.rb,
lib/holidays/definition/repository/holidays_by_month.rb,
lib/holidays/definition/repository/proc_result_cache.rb,
lib/holidays/definition/decorator/custom_method_source.rb

Overview

This context builds a hash that contains => [<array of months>]. The idea is that we will iterate over each year and then over each month internally and check to see if the supplied dates match any holidays for the region and date. So if we supply start_date of 2015/1/1 and end_date of 2015/6/1 then we will return a date driver of => [0, 1, 2, 5, 6, 7]. In the logic in the various other ‘finder’ contexts we will iterate over this and compare dates in these months to the supplied range to determine whether they should be returned to the user.

Defined Under Namespace

Modules: AR, AT, AU, BE, BE_FR, BE_NL, BG, BR, CA, CH, CL, CR, CZ, CoreExtensions, DE, DK, DateCalculator, Definition, ECB_TARGET, EL, ES, EUROPE, FEDERAL_RESERVE, FEDEX, FI, FR, Factory, Finder, GB, HK, HR, HU, IE, IS, IT, JP, KR, LI, LT, LU, MA, MX, MY, NERC, NL, NO, NORTH_AMERICA, NYSE, NZ, PE, PH, PL, PT, RO, SCANDINAVIA, SE, SG, SI, SK, UNITED_NATIONS, UPS, US, VE, VI, ZA Classes: Error, FunctionNotFound, InvalidFunctionResponse, InvalidRegion, LoadAllDefinitions, UnknownRegionError

Constant Summary collapse

WEEKS = 
{:first => 1, :second => 2, :third => 3, :fourth => 4, :fifth => 5, :last => -1, :second_last => -2, :third_last => -3}
MONTH_LENGTHS = 
[31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
DAY_SYMBOLS = 
Date::DAYNAMES.collect { |n| n.downcase.intern }
DEFINITIONS_PATH = 
'generated_definitions'
FULL_DEFINITIONS_PATH = 
File.expand_path(File.dirname(__FILE__) + "/#{DEFINITIONS_PATH}")
VERSION = 
'5.0.0'
REGIONS = 
[:ar, :at, :au, :au_nsw, :au_vic, :au_qld, :au_nt, :au_act, :au_sa, :au_tas_south, :au_wa, :au_tas, :au_qld_cairns, :au_qld_brisbane, :au_tas_north, :au_vic_melbourne, :be_fr, :be_nl, :br, :bg_en, :bg_bg, :ca, :ca_qc, :ca_ab, :ca_sk, :ca_on, :ca_bc, :ca_mb, :ca_ns, :ca_pe, :ca_nf, :ca_nt, :ca_nu, :ca_nb, :ca_yk, :us, :ch_zh, :ch_be, :ch_lu, :ch_ur, :ch_sz, :ch_ow, :ch_nw, :ch_gl, :ch_zg, :ch_fr, :ch_so, :ch_bs, :ch_bl, :ch_sh, :ch_ar, :ch_ai, :ch_sg, :ch_gr, :ch_ag, :ch_tg, :ch_ti, :ch_vd, :ch_ne, :ch_ge, :ch_ju, :ch_vs, :ch, :cl, :cr, :cz, :dk, :de, :de_bw, :de_by, :de_he, :de_nw, :de_rp, :de_sl, :de_sn_aux, :de_th_aux, :de_sn, :de_st, :de_by_aux, :de_bb, :de_mv, :de_th, :ecb_target, :el, :es_pv, :es_na, :es_an, :es_ib, :es_cm, :es_mu, :es_m, :es_ar, :es_cl, :es_cn, :es_lo, :es_ga, :es_ce, :es_o, :es_ex, :es, :es_ct, :es_v, :es_vc, :federal_reserve, :fedex, :fi, :fr, :gb, :gb_eng, :gb_wls, :gb_eaw, :gb_nir, :gb_sct, :gb_con, :je, :gb_jsy, :gg, :gb_gsy, :im, :gb_iom, :hr, :hk, :hu, :ie, :is, :it, :kr, :li, :lt, :ma, :mx, :mx_pue, :us, :ca, :nerc, :nl, :lu, :no, :nyse, :nz, :nz_sl, :nz_we, :nz_ak, :nz_nl, :nz_ne, :nz_ot, :nz_ta, :nz_sc, :nz_hb, :nz_mb, :nz_ca, :nz_ch, :nz_wl, :pe, :ph, :pl, :pt, :ro, :se, :us, :us_dc, :us_ca, :ca, :united_nations, :ups, :za, :ca, :ca_qc, :ca_ab, :ca_sk, :ca_on, :ca_bc, :ca_mb, :ca_ns, :ca_pe, :ca_nf, :ca_nt, :ca_nu, :ca_nb, :ca_yk, :mx, :mx_pue, :us, :us_dc, :us_ca, :dk, :is, :no, :se, :fi, :at, :be_fr, :be_nl, :ch_zh, :ch_be, :ch_lu, :ch_ur, :ch_sz, :ch_ow, :ch_nw, :ch_gl, :ch_zg, :ch_fr, :ch_so, :ch_bs, :ch_bl, :ch_sh, :ch_ar, :ch_ai, :ch_sg, :ch_gr, :ch_ag, :ch_tg, :ch_ti, :ch_vd, :ch_ne, :ch_ge, :ch_ju, :ch_vs, :ch, :cz, :dk, :de, :de_bw, :de_by, :de_he, :de_nw, :de_rp, :de_sl, :de_sn_aux, :de_th_aux, :de_sn, :de_st, :de_by_aux, :de_bb, :de_mv, :de_th, :el, :es_pv, :es_na, :es_an, :es_ib, :es_cm, :es_mu, :es_m, :es_ar, :es_cl, :es_cn, :es_lo, :es_ga, :es_ce, :es_o, :es_ex, :es, :es_ct, :es_v, :es_vc, :fr, :gb, :gb_eng, :gb_wls, :gb_eaw, :gb_nir, :gb_sct, :gb_con, :je, :gb_jsy, :gg, :gb_gsy, :im, :gb_iom, :hr, :hu, :ie, :is, :it, :li, :lt, :nl, :no, :pl, :pt, :ro, :sk, :si, :bg_en, :bg_bg, :jp, :ve, :vi, :sk, :si, :sg, :my]

Class Method Summary collapse

Class Method Details

.any_holidays_during_work_week?(date, *options) ⇒ Boolean

Does the given work-week have any holidays?

date

A Date object.

:options

One or more region symbols, and/or :informal. Automatically includes :observed. If you don’t want this, pass :no_observed

The given Date can be any day of the week. Returns true if any holidays fall on Monday - Friday of the given week.

Returns:

  • (Boolean) 


66
67
68
69
70
71
72
73
74
 
# File 'lib/holidays.rb', line 66

def any_holidays_during_work_week?(date, *options)
  days_to_monday = date.wday - 1
  days_to_friday = 5 - date.wday
  start_date = date - days_to_monday
  end_date = date + days_to_friday
  options += [:observed] unless options.include?(:no_observed)
  options.delete(:no_observed)
  between(start_date, end_date, options).empty?
end

.available_regions ⇒ Object

Returns an array of symbols of all the available holiday regions.



198
199
200
 
# File 'lib/holidays.rb', line 198

def available_regions
  Holidays::REGIONS
end

.between(start_date, end_date, *options) ⇒ Object

Get all holidays occuring between two dates, inclusively.

Returns an array of hashes or nil.

Each holiday is returned as a hash with the following fields:

start_date

Ruby Date object.

end_date

Ruby Date object.

options

One or more region symbols, :informal and/or :observed.

Example

from = Date.civil(2008,7,1)
to   = Date.civil(2008,7,31)

Holidays.between(from, to, :ca, :us)
=> [{:name => 'Canada Day', :regions => [:ca]...}
    {:name => 'Independence Day'', :regions => [:us], ...}]

Raises:

  • (ArgumentError) 


105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/holidays.rb', line 105

def between(start_date, end_date, *options)
  raise ArgumentError unless start_date && end_date

  # remove the timezone
  start_date = start_date.new_offset(0) + start_date.offset if start_date.respond_to?(:new_offset)
  end_date = end_date.new_offset(0) + end_date.offset if end_date.respond_to?(:new_offset)

  start_date, end_date = get_date(start_date), get_date(end_date)

  if cached_holidays = Factory::Definition.cache_repository.find(start_date, end_date, options)
    return cached_holidays
  end

  Factory::Finder.between.call(start_date, end_date, options)
end

.cache_between(start_date, end_date, *options) ⇒ Object

Allows a developer to explicitly calculate and cache holidays within a given period



190
191
192
193
194
195
 
# File 'lib/holidays.rb', line 190

def cache_between(start_date, end_date, *options)
  start_date, end_date = get_date(start_date), get_date(end_date)
  cache_data = between(start_date, end_date, *options)

  Factory::Definition.cache_repository.cache_between(start_date, end_date, cache_data, options)
end

.load_custom(*files) ⇒ Object

Parses provided holiday definition file(s) and loads them so that they are immediately available.



203
204
205
206
207
208
209
210
211
212
213
 
# File 'lib/holidays.rb', line 203

def load_custom(*files)
  regions, rules_by_month, custom_methods, _ = Factory::Definition.file_parser.parse_definition_files(files)

  custom_methods.each do |method_key, method_entity|
    custom_methods[method_key] = Factory::Definition.custom_method_proc_decorator.call(method_entity)
  end

  Factory::Definition.merger.call(regions, rules_by_month, custom_methods)

  rules_by_month
end

.next_holidays(holidays_count, options, from_date = Date.today) ⇒ Object

Get next holidays occuring from date, inclusively.

Returns an array of hashes or nil.

Incoming arguments are below:

holidays_count

Ruby Numeric object. This is the number of holidays to return

options

One or more region symbols, :informal and/or :observed.

from_date

Ruby Date object. This is an optional param, defaulted today.

Example

Date.today
=> Tue, 23 Feb 2016

regions = [:us, :informal]

Holidays.next_holidays(3, regions)
=> [{:name => "St. Patrick's Day",...},
    {:name => "Good Friday",...},
    {:name => "Easter Sunday",...}]

Raises:

  • (ArgumentError) 


140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/holidays.rb', line 140

def next_holidays(holidays_count, options, from_date = Date.today)
  raise ArgumentError unless holidays_count
  raise ArgumentError if options.empty?
  raise ArgumentError unless options.is_a?(Array)

  # remove the timezone
  from_date = from_date.new_offset(0) + from_date.offset if from_date.respond_to?(:new_offset)

  from_date = get_date(from_date)

  Factory::Finder.next_holiday.call(holidays_count, from_date, options)
end

.on(date, *options) ⇒ Object

Get all holidays on a given date.

date

A Date object.

:options

One or more region symbols, :informal and/or :observed.

Returns an array of hashes or nil. See Holidays#between for the output format.

Also available via Date#holidays.



85
86
87
 
# File 'lib/holidays.rb', line 85

def on(date, *options)
  between(date, date, options)
end

.year_holidays(options, from_date = Date.today) ⇒ Object

Get all holidays occuring from date to end of year, inclusively.

Returns an array of hashes or nil.

Incoming arguments are below:

options

One or more region symbols, :informal and/or :observed.

from_date

Ruby Date object. This is an optional param, defaulted today.

Example

Date.today
=> Tue, 23 Feb 2016

regions = [:ca_on]

Holidays.year_holidays(regions)
=> [{:name=>"Good Friday",...},
    {name=>"Easter Sunday",...},
    {:name=>"Victoria Day",...},
    {:name=>"Canada Day",...},
    {:name=>"Civic Holiday",...},
    {:name=>"Labour Day",...},
    {:name=>"Thanksgiving",...},
    {:name=>"Remembrance Day",...},
    {:name=>"Christmas Day",...},
    {:name=>"Boxing Day",...}]

Raises:

  • (ArgumentError) 


178
179
180
181
182
183
184
185
186
187
 
# File 'lib/holidays.rb', line 178

def year_holidays(options, from_date = Date.today)
  raise ArgumentError if options.empty?
  raise ArgumentError unless options.is_a?(Array)

  # remove the timezone
  from_date = from_date.new_offset(0) + from_date.offset if from_date.respond_to?(:new_offset)
  from_date = get_date(from_date)

  Factory::Finder.year_holiday.call(from_date, options)
end