Module: Holidays

Defined in:
lib/holidays.rb,
lib/holidays/errors.rb,
lib/holidays/version.rb,
lib/holidays/option_factory.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/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/li.rb,
lib/generated_definitions/lt.rb,
lib/generated_definitions/ma.rb,
lib/generated_definitions/mx.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/holidays/use_case_factory.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/definition_factory.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/date_calculator/easter.rb,
lib/generated_definitions/ecb_target.rb,
lib/holidays/date_calculator_factory.rb,
lib/generated_definitions/scandinavia.rb,
lib/holidays/use_case/context/between.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/generated_definitions/federal_reserve.rb,
lib/holidays/date_calculator/day_of_month.rb,
lib/holidays/definition/context/generator.rb,
lib/holidays/option/context/parse_options.rb,
lib/holidays/definition/repository/regions.rb,
lib/holidays/use_case/context/next_holiday.rb,
lib/holidays/use_case/context/year_holiday.rb,
lib/holidays/definition/entity/custom_method.rb,
lib/holidays/definition/parser/custom_method.rb,
lib/holidays/use_case/context/context_common.rb,
lib/holidays/date_calculator/weekend_modifier.rb,
lib/holidays/definition/validator/custom_method.rb,
lib/holidays/definition/repository/custom_methods.rb,
lib/holidays/use_case/context/dates_driver_builder.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 ‘between’ use case 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, DateCalculatorFactory, Definition, DefinitionFactory, ECB_TARGET, EL, ES, EUROPE, FEDERAL_RESERVE, FEDEX, FI, FR, GB, HR, HU, IE, IS, IT, JP, LI, LT, MA, MX, NERC, NL, NO, NORTH_AMERICA, NYSE, NZ, Option, OptionFactory, PE, PH, PL, PT, RO, SCANDINAVIA, SE, SG, SI, SK, UNITED_NATIONS, UPS, US, UseCase, VE, VI, ZA Classes: Error, FunctionNotFound, LoadAllDefinitions, UnknownRegionError, UseCaseFactory

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 = 
'4.5.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, :hu, :ie, :is, :it, :li, :lt, :ma, :mx, :mx_pue, :us, :ca, :nerc, :nl, :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]

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) 


80
81
82
83
84
85
86
87
88
 
# File 'lib/holidays.rb', line 80

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.



216
217
218
 
# File 'lib/holidays.rb', line 216

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) 


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

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 = definition_cache_repository.find(start_date, end_date, options)
    return cached_holidays
  end

  regions, observed, informal = OptionFactory.parse_options.call(options)
  date_driver_hash = UseCaseFactory.dates_driver_builder.call(start_date, end_date)

  UseCaseFactory.between.call(start_date, end_date, date_driver_hash, regions, observed, informal)
end

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

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



208
209
210
211
212
213
 
# File 'lib/holidays.rb', line 208

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)

  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.



221
222
223
224
225
226
227
228
229
230
231
 
# File 'lib/holidays.rb', line 221

def load_custom(*files)
  regions, rules_by_month, custom_methods, tests = DefinitionFactory.file_parser.parse_definition_files(files)

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

  DefinitionFactory.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) 


144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
 
# File 'lib/holidays.rb', line 144

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)
  regions, observed, informal = OptionFactory.parse_options.call(options)

  # This could be smarter but I don't have any evidence that just checking for
  # the next 12 months will cause us issues. If it does we can implement something
  # smarter here to check in smaller increments.
  date_driver_hash = UseCaseFactory.dates_driver_builder.call(from_date, from_date >> 12)

  UseCaseFactory.next_holiday.call(holidays_count, from_date, date_driver_hash, regions, observed, informal)
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.



69
70
71
 
# File 'lib/holidays.rb', line 69

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) 


188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/holidays.rb', line 188

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)
  to_date = Date.new(from_date.year, 12, 31)
  regions, observed, informal = OptionFactory.parse_options.call(options)

  # This could be smarter but I don't have any evidence that just checking for
  # the next 12 months will cause us issues. If it does we can implement something
  # smarter here to check in smaller increments.
  date_driver_hash = UseCaseFactory.dates_driver_builder.call(from_date, from_date >> 12)

  UseCaseFactory.year_holiday.call(from_date, to_date, date_driver_hash, regions, observed, informal)
end