holidays 3.3.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 314e234058d757423c0e873ac27f9ce001a54fa0
-  data.tar.gz: f827b9614cd1037c20153fa2b316d000b784e2f4
+  metadata.gz: a3ae038d2ecc81231efdb1dfb62b8aa5f8a9a08b
+  data.tar.gz: 0ee05da812d8db5409bad033938d44d127c5a9a7
 SHA512:
-  metadata.gz: 3fbe210da7f49b7e8c5d5693e230ee2b5bb46190656be2c99bd28f795bc9e8e8ede109e699ebd87ed7b024ca76cfa6cc34220d2853603296700c8feaf3e95562
-  data.tar.gz: 66f1d44e7a7fc1c10b84f959dccc5c0710a10f802d0ee9bcdd8b74e7bf526d3be95ee1c36dc4dd2a756086bc3753218d7b87b6f8c872cc252e5cf8ba4e04c21e
+  metadata.gz: d89718606e9235afedb475611e069cc5cfeae83951f28881418df6299287cd947bff46df32ee6fbec68eb3794f42622c90ca8d69b4fc764bc9a0464542a1e36f
+  data.tar.gz: 1005849766e633f5fad96e4cdc37f8d5ab021c63b5a50c921bd066239eedd69d07d22f0b83474af958fc32db75cfee83ff7216f6d8a146b4788466e05702fc1b

data/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Ruby Holidays Gem CHANGELOG
 
+## 4.0.0
+
+Major refactor with breaking changes! Sorry for the wall of text but there is a lot of info here.
+
+* Fixes issue 144 (loading custom defs with methods). This was the refactor catalyst. Changes highlights include:
+  - Allow for custom methods added via the `load_custom` method to be used immediately as expected
+  - Consolidate and clarify custom method parsing and validation
+  - Change nearly every definition to use new 'custom method' YAML format. See `definitions/README.md` for more info.
+  - Remove `require` functionality when loading new definitions, instead using in-memory repositories. See below for info.
+  - Now loads all generated definitions when `require 'holidays'` is called. See below for performance info.
+* Add `rake console` command for easier local testing
+* Remove or rename many public methods that were never intended for public use:
+  - Remove following date calculation helper methods (definitions must now directly call factory):
+    - `easter`
+    - `orthodox_easter`
+    - `orthodox_easter_julian`
+    - `to_monday_if_sunday`
+    - `to_monday_if_weekend`
+    - `to_weekday_if_boxing_weekend`
+    - `to_weekday_if_boxing_weekend_from_year`
+    - `to_weekday_if_weekend`
+    - `calculate_day_of_month`
+  - Remove `available` method. This was only intended for internal use
+  - Remove `parse_definition_files_and_return_source`. This was only intended for internal use
+  - Remove `load_all` method. This was only intended for internal use
+  - Rename `regions` to `available_regions` for clarity
+  - Rename `full_week?` to `any_holidays_during_work_week?` for clarity
+* Following methods now constitute the 'public API' of this gem:
+  -  `on`
+  -  `any_holidays_during_work_week?` (renamed method, was originally `full_week?`, same behavior as before)
+  -  `between`
+  -  `cache_between`
+  -  `available_regions` (renamed method, was originally `regions`, same behavior as before)
+  -  `load_custom`
+* All generated definitions are now loaded when `require 'holidays'` is called
+  - Previously files were required 'on the fly' when a specific region was specified. By requiring all definitions upon
+    startup we greatly simplify the handling of regions, definitions, and custom methods internally
+  - This results in a performance hit when calling `require 'holidays'`. Here is an example based on my benchmarking:
+    - old: `0.045537`
+    - new: `0.145125`
+
+I decided that this performance hit on startup is acceptable. All other performance should remain the same. If performance is
+a major concern please open an issue so we can discuss your use case.
+
 ## 3.3.0
 
 This is the final minor point release in v3.X.X. I am releasing it so that all of the latest definitions can be

data/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# How to contribute
+
+There are multiple ways to help! We rely on users around the world to help keep our definitions accurate and up to date. In addition, pull requests to address bugs or implement new features are always welcome.
+
+## For definition updates
+
+Our definitions are written in YAML. You can find a complete guide to our format in the [definitions README](definitions/README.md). We take the YAML definitions and generate final ruby classes that are loaded at runtime for fast calculations.
+
+Here are the steps to take once you have a good idea on what you want to change:
+
+* Fork the repository
+* Edit desired definition YAML file(s) located under `definitions/`. If you are adding a new region be sure to update `definitions/index.yaml` as well
+* Run `bundle exec rake generate` to generate updated final definitions (they will be located under `lib/generated_definitions/` and `test/defs/`)
+* Run `bundle exec rake test` to ensure your changes did not introduce errors
+* Open a PR with *all* of these changes. You *MUST* include the generated definition files and tests in your PR. There is no automatic process to generate definitions at this time
+
+Including documentation with your updates is very much appreciated. A simple Wikipedia entry or government link in the comments alongside your changes would be perfect.
+
+Lastly, note that there are many 'meta' regions. For example, there are regions for Europe, Scandinavia, and North America. If your new region(s) falls into these areas consider adding them. You can find these 'meta' regions in `definitions/index.yaml`.
+
+## For non-definition functionality
+
+* Fork the repository
+* Make your changes
+* Create a PR pointing back to `master`
+
+Don't worry about versioning, we'll handle it on our end.
+
+*Tests are required*. If your PR results in lower test coverage then it will not be accepted.
+
+## Local development helpers
+
+We have included a few handy tasks to help you troubleshoot and test:
+
+* `rake test` - runs the entire suite
+* `rake test_region <region>` - runs the tests for just that region. Make sure to run `rake generate` after updating your YAML before running this!
+* `rake console` - launches an IRB session with the 'holidays' gem loaded for quick testing

data/README.md

@@ -14,7 +14,9 @@ To install the gem from RubyGems:
 
 The Holidays gem is tested on Ruby 2.0.0, 2.1.0, 2.2.0, 2.3.0 and JRuby.
 
-The Holidays gem follows [semantic versioning](http://semver.org/). Please take this into account when relying on this gem as a dependency.
+This gem follows [semantic versioning](http://semver.org/). The only methods covered by this guarantee are under the
+`Holidays` namespace specifically. Anything that is not a method off of `Holidays` or the core extension is not covered by
+semver. Please take this into account when relying on this gem as a dependency.
 
 ## Time zones
 
@@ -53,6 +55,16 @@ Get informal holidays in February.
     Holidays.between(from, to, :informal)
     => [{:name => 'Valentine\'s Day',...}]
 
+Return all available regions:
+
+    Holidays.available_regions
+    => [:ar, :at, ..., :sg] # this will be a big array
+
+To check if there are any holidays taking place during a specified work week:
+
+    Holidays.any_holidays_during_work_week?(Date.civil(2016, 1, 1))
+    => true
+
 ### Loading Custom Definitions on the fly
 
 Load custom definitions file on the fly and use them immediately.
@@ -112,32 +124,11 @@ If you are checking holidays regularly you can cache your results for improved p
 
     Holidays.cache_between(Time.now, 2.years.from_now, :ca, :us, :observed)
 
-Holidays for the regions specified within the dates specified will be pre-calculated.
-
-See the [original pull request](https://github.com/alexdunae/holidays/pull/36) for more details.
+Holidays for the regions specified within the dates specified will be pre-calculated and stored in-memory. Future lookups will be much faster.
 
 ### How to contribute
 
-#### For definition updates
-
-* Edit desired definition YAML file(s) located under `definitions/`. If you are adding a new region be sure to update `definitions/index.yaml` as well
-* Run `bundle exec rake generate` to generate updated final definitions (they will be located under `lib/generated_definitions/`)
-* Run `bundle exec rake test` to ensure your changes did not introduce errors
-* Open a PR with *all* of these changes. You *MUST* include the generated definition files in your PR. There is no automatic process to generated definitions at this time
-
-Including documentation with your updates is very much appreciated. A simple Wikipedia entry or government link in the comments alongside your changes would be perfect.
-
-Lastly, note that there are many 'meta' regions. For example, there are regions for Europe, Scandinavia, and North America. If your new region(s) falls into these areas consider adding them. You can find these 'meta' regions in `definitions/index.yaml`.
-
-#### For non-definition functionality
-
-* Fork the repository
-* Make your changes
-* Create a PR pointing back to `master`
-
-Don't worry about versioning, we'll handle it on our end.
-
-Tests are required. If your PR results in lower test coverage then it will not be accepted.
+See our [contribution guidelines](CONTRIBUTING.md) for information on how to help out!
 
 ### Credits and code
 
@@ -145,4 +136,4 @@ Tests are required. If your PR results in lower test coverage then it will not b
 * Maintained by [Hana Wang](https://github.com/hahahana), 2013
 * Maintained by [Phil Trimble](https://github.com/ptrimble), 2014-present
 
-Plus all of these [wonderful contributors!](https://github.com/alexdunae/holidays/contributors)
+Plus all of these [wonderful contributors!](https://github.com/holidays/holidays/contributors)

data/REFERENCES

@@ -1,6 +1,6 @@
 === References
 
-I am grateful to the following sources.
+We are eternally grateful to the following sources.
 
 ==== Date calculations
 * http://michaelthompson.org/technikos/holidays.php
@@ -8,9 +8,12 @@ I am grateful to the following sources.
 ==== Easter calculations
 * http://www.assa.org.au/edm.html
 * http://www.smart.net/~mmontes/ec-cal.html
+* https://github.com/Loyolny/when_easter - graciously allowed by Michał Nierebiński
 
 ==== World dates
 * http://www.un.org/geninfo/faq/factsheets/FS18.HTM
 * http://en.wikipedia.org/wiki/List_of_holidays_by_country
 
+Other sources for specific regions are noted in the definitions files themselves.
 
+If a commit sneaks past the maintainers without attribution then please, let us know immediately! It was entirely unintentional.

data/Rakefile

@@ -7,6 +7,9 @@ require 'yaml'
 require 'fileutils'
 require 'holidays'
 
+DEFINITION_PATH = 'definitions'
+DEFINITION_TESTS_PATH = 'test/defs'
+
 Rake::TestTask.new(:test) do |t|
   t.libs << 'test'
   t.test_files = FileList['test/**/test_*.rb']
@@ -14,30 +17,57 @@ end
 
 task :default => :test
 
-namespace :generate do
-  DATA_PATH = 'definitions'
-  TEST_DEFS_PATH = 'test/defs'
+desc "Run tests for only a single region. Do not provide sub regions. Example (without quotes): 'rake test_region jp'"
+task :test_region do
+  # Magic to define empty tasks on the fly so we have nicer arguments, see http://cobwwweb.com/4-ways-to-pass-arguments-to-a-rake-task
+  ARGV.each { |a| task a.to_sym do ; end }
+
+  if ARGV[1].nil? || ARGV[1].empty?
+    raise ArgumentError.new("You must provide a region. Example (without quotes): 'rake test_region us'")
+  end
 
+  region = ARGV[1].downcase
+
+  unless Holidays.available_regions.include?(region.to_sym)
+    raise ArgumentError.new("Region '#{region}' not recognized")
+  end
+
+  unless File.file?("#{DEFINITION_TESTS_PATH}/test_defs_#{region}.rb")
+    raise ArgumentError.new("Test file not found for region '#{region}'. Do not use sub regions, try the overall region instead. Example: 'us' instead of 'us_dc'")
+  end
+
+  sh "bundle exec ruby #{DEFINITION_TESTS_PATH}/test_defs_#{region}.rb"
+end
+
+desc 'Launch IRB session'
+task :console do
+  sh "irb -rubygems -I lib -r holidays.rb"
+end
+
+desc 'Generate definitions and tests used in main holiday logic based on raw YAML definitions'
+namespace :generate do
   desc 'Generate the holiday definition files'
   task :definitions do
     # load the index
-    def_index = YAML.load_file("#{DATA_PATH}/index.yaml")
+    def_index = YAML.load_file("#{DEFINITION_PATH}/index.yaml")
 
     # create a dir for the generated tests
-    FileUtils.mkdir_p(TEST_DEFS_PATH)
+    FileUtils.mkdir_p(DEFINITION_TESTS_PATH)
 
     all_regions = []
 
     def_index['defs'].each do |region, files|
       puts "Building #{region} definition module:"
-      files = files.collect { |f| "#{DATA_PATH}/#{f}" }.uniq
+      files = files.collect { |f| "#{DEFINITION_PATH}/#{f}" }.uniq
+
+      regions, rules_by_month, custom_methods, tests = Holidays::DefinitionFactory.file_parser.parse_definition_files(files)
+      module_src, test_src = Holidays::DefinitionFactory.source_generator.generate_definition_source(region, files, regions, rules_by_month, custom_methods, tests)
 
-      module_src, test_src, regions = Holidays.parse_definition_files_and_return_source(region, files)
       File.open("lib/#{Holidays::DEFINITIONS_PATH}/#{region.downcase.to_s}.rb","w") do |file|
         file.puts module_src
       end
       unless test_src.empty?
-        File.open("#{TEST_DEFS_PATH}/test_defs_#{region.downcase.to_s}.rb","w") do |file|
+        File.open("#{DEFINITION_TESTS_PATH}/test_defs_#{region.downcase.to_s}.rb","w") do |file|
           file.puts test_src
         end
       end

data/benchmark.rb

@@ -0,0 +1,8 @@
+require 'benchmark'
+
+puts Benchmark.measure {
+  require 'holidays'
+  Holidays.between(
+    Date.civil(2016, 1, 1), Date.civil(2016, 12, 31), :us
+  )
+}

data/definitions/README.md

@@ -51,7 +51,7 @@ The two required properties are:
 
 For example, the following holiday is on the first of January and available in the `:ca`, `:us` and `:au` regions:
 
-```
+```yaml
 1:
 - name: New Year's Day
   regions: [ca, us, au]
@@ -65,7 +65,7 @@ For example, the following holiday is on the first of January and available in t
 
 For example, the following holiday is on the first Monday of September and available in the `:ca` region:
 
-```
+```yaml
 9:
 - name: Labour Day
   regions: [ca]
@@ -73,6 +73,156 @@ For example, the following holiday is on the first Monday of September and avail
   wday: 1
 ```
 
+### 'Formal' vs 'Informal' types
+
+As mentioned above you can specify two different types. By default a holiday is considered 'formal'. By adding a `type: informal` to a definition you will mark it as 'informal' and it will only show up if the user specifically asks for it.
+
+Example:
+
+```yaml
+9:
+- name: Some Holiday
+  regions: [fr]
+  mday: 1
+  type: informal
+```
+
+If a user submits:
+
+```ruby
+Holidays.on(Date.civil(2016, 9, 1), :fr)
+```
+
+then they will not see the holiday. However, if they submit:
+
+```ruby
+Holidays.on(Date.civil(2016, 9, 1), :fr, :informal)
+```
+
+Then the holiday will be returned. This is especially useful for holidays like "Valentine's Day" in the USA, where it is commonly recognized as a holiday in society but not as a day that is celebrated by taking the day off.
+
+### Year ranges
+
+Certain holidays in various countries are only in effect during specific year ranges. For example, a new holiday might come into effect that is only valid after a speciic year (say, 2017).
+
+To address this we have the ability to specify these 'year ranges' in the definition. The gem will then only return a match on a date that adheres to these rules.
+
+There are a total of four selectors that can be specified. All must be specified in terms of 'years'.
+
+#### `before`
+
+The 'before' selector will only find a match if the supplied date takes place
+before or equal to the holiday.
+
+Example:
+
+```yaml
+7:
+  name: 振替休日
+  regions: [jp]
+  mday: 1
+  year_ranges:
+    - before: 2002
+```
+
+This will return successfully:
+
+```ruby
+Holidays.on(Date.civil(2000, 7, 1), :jp)
+```
+
+This will not:
+
+```ruby
+Holidays.on(Date.civil(2016, 7, 1), :jp)
+```
+
+#### `after`
+
+The 'after' selector will only find a match if the supplied date takes place
+after or equal to the holiday.
+
+Example:
+
+```yaml
+7:
+  name: 振替休日
+  regions: [jp]
+  mday: 1
+  year_ranges:
+    - after: 2002
+```
+
+This will return successfully:
+
+```ruby
+Holidays.on(Date.civil(2016, 7, 1), :jp)
+```
+
+This will not:
+
+```ruby
+Holidays.on(Date.civil(2000, 7, 1), :jp)
+```
+
+#### `limited`
+
+The 'limited' selector will only find a match if the supplied date takes place during
+one of the specified years. Multiple years can be specified.
+
+An array of years *must* be supplied. Individual integers will result in an error.
+
+Example:
+
+```yaml
+7:
+  name: 振替休日
+  regions: [jp]
+  mday: 1
+  year_ranges:
+    - limited: [2002]
+```
+
+This will return successfully:
+
+```ruby
+Holidays.on(Date.civil(2002, 7, 1), :jp)
+```
+
+This will not:
+
+```ruby
+Holidays.on(Date.civil(2000, 7, 1), :jp)
+```
+
+#### `between`
+
+The 'between' selector will only find a match if the supplied date takes place during the specified range of years. Only a single range is allowed at this time.
+
+Example:
+
+```yaml
+7:
+  name: 振替休日
+  regions: [jp]
+  mday: 1
+  year_ranges:
+    - between: 1996..2002
+```
+
+This will return successfully:
+
+```ruby
+Holidays.on(Date.civil(2000, 7, 1), :jp)
+```
+
+This will not:
+
+```ruby
+Holidays.on(Date.civil(2003, 7, 1), :jp)
+Holidays.on(Date.civil(1995, 7, 1), :jp)
+```
+
 ## Methods
 
 In addition to defining holidays by day or week, you can create custom methods to calculate a date. These should be placed under the `methods` property. Methods named in this way can then be referenced by entries in the `months` property.
@@ -81,16 +231,17 @@ For example, Canada celebrates Victoria Day, which falls on the Monday on or bef
 
 ```
 methods:
-  ca_victoria_day: |
-    def self.ca_victoria_day(year)
-      date = Date.civil(year,5,24)
+  ca_victoria_day:
+    arguments: year
+    source: |
+      date = Date.civil(year, 5, 24)
       if date.wday > 1
         date -= (date.wday - 1)
       elsif date.wday == 0
         date -= 6
       end
+
       date
-    end
 ```
 
 This would be represented in `months` entry as:
@@ -108,7 +259,7 @@ If a holiday can occur in different months (e.g. Easter) it can go in the '0' mo
 0:
 - name: Easter Monday
   regions: [ca]
-  function: easter(year)+1
+  function: easter(year)
 ```
 
 There are pre-existing methods for highly-used calculations. They are:
@@ -127,10 +278,38 @@ There are pre-existing methods for highly-used calculations. They are:
 0:
 - name: Good Friday
   regions: [us]
-  function: easter(year)-2
+  function: easter(year)
+  function_modifier: -2
   type: informal
 ```
 
+Use the `function_modifier` property, which can be positive or negative, to modify the result of the function.
+
+In addition, you may only specify the following values for arguments into a custom method: `date`, `year`, `month`, `day`.
+
+If attempt to specify anything else then you will receive an error on definition generation. This is because these are the only values that are available to
+call into the custom methods will calculating the result of a function.
+
+Correct example:
+
+```
+1:
+- name: Custom Method
+  regions: [us]
+  function: custom_method(year, month, day)
+```
+
+If you do the following:
+
+```
+1:
+- name: Custom Method
+  regions: [us]
+  function: custom_method(week)
+```
+
+This will result in an error since `week` is not a recognized method argument.
+
 ### Calculating observed dates
 
 Users can specify that this gem only return holidays on their 'observed' day. This can be especially useful if they are using this gem for business-related logic. If you wish for your definitions to allow for this then you can add the `observed` property to your entry. This requires a method to help calculate the observed day.