zmanim 0.1.0

data/README.md

@@ -0,0 +1,124 @@
+# Zmanim
+
+A Ruby library for Zmanim.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'zmanim'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install zmanim
+
+## Usage
+
+Some common examples include...
+
+#### Zmanim calculations
+
+```ruby
+
+# Initialize a new ZmanimCalendar object, defaults to using today's date in GMT, located at Greenwich, England
+zmanim = Zmanim::ZmanimCalendar.new
+#=> #<Zmanim::ZmanimCalendar:0x007fa73c2ec7d8 @geo_location=#<Zmanim::Util::GeoLocation:0x007fa73c2ec710 @location_name="Greenwich, England", @latitude=51.4772, @longitude=0, @time_zone=#<TZInfo::DataTimezone: GMT>, @elevation=0>, @date=#<Date: 2018-01-09 ((2458128j,0s,0n),+0s,2299161j)>, @astronomical_calculator=#<Zmanim::Util::NOAACalculator:0x007fa73c24e920>, @candle_lighting_offset=18>
+
+# Calculate the sunset for today at that location
+zmanim.sunset
+#=> #<DateTime: 2018-01-08T16:10:12+00:00 ((2458127j,58212s,336684777n),+0s,2299161j)>        
+
+# Prepare a new location
+location = Zmanim::Util::GeoLocation.new('Lakewood, NJ', 40.0721087, -74.2400243, 'US/Eastern', elevation: 15)
+#=> #<Zmanim::Util::GeoLocation:0x007fa73c1c5008 @location_name="Lakewood, NJ", @latitude=40.0721087, @longitude=-74.2400243, @time_zone=#<TZInfo::DataTimezone: US/Eastern>, @elevation=15> 
+
+# Initialize a new ZmanimCalendar object, passing a specific location and date
+zmanim = Zmanim::ZmanimCalendar.new(geo_location: location, date: Date.parse('2017-12-15'))
+#=> #<Zmanim::ZmanimCalendar:0x007fa73c33ee98 @geo_location=#<Zmanim::Util::GeoLocation:0x007fa73c1c5008 @location_name="Lakewood, NJ", @latitude=40.0721087, @longitude=-74.2400243, @time_zone=#<TZInfo::DataTimezone: US/Eastern>, @elevation=15>, @date=#<Date: 2017-12-15 ((2458103j,0s,0n),+0s,2299161j)>, @astronomical_calculator=#<Zmanim::Util::NOAACalculator:0x007fa73c33ee48>, @candle_lighting_offset=18>
+
+# Calculate Sof Zman Krias Shma for that location/date per the opinion of GR"A
+zmanim.sof_zman_shma_gra
+#=> #<DateTime: 2017-12-15T09:32:09-05:00 ((2458103j,52329s,383390214n),-18000s,2299161j)>
+```
+
+#### Date Calculations
+
+```ruby
+# Initialize a new JewishDate object with today's date 
+date = Zmanim::HebrewCalendar::JewishDate.new
+# => #<Zmanim::HebrewCalendar::JewishDate:0x007fa73c2976e8 @gregorian_date=#<Date: 2018-01-09 ((2458128j,0s,0n),+0s,-Infj)>, @absolute_date=736703, @day_of_week=3, @molad_chalakim=0, @molad_minutes=0, @molad_hours=0, @jewish_year=5778, @jewish_month=10, @jewish_day=22>
+
+# Initialize a HebrewDateFormatter object
+formatter = Zmanim::HebrewCalendar::HebrewDateFormatter.new
+#=> #<Zmanim::HebrewCalendar::HebrewDateFormatter:0x007fa73c2ec558 ...>
+
+# Format the jewish date
+formatter.format(date)
+#=> "22 Teves, 5778" 
+
+# Change the formatter to use hebrew
+formatter.hebrew_format = true
+formatter.format(date)
+#=> "כ״ב טבת תשע״ח"  
+```
+
+#### Jewish Calendar occasions
+
+```ruby
+# Initialize a new JewishCalendar object with a specific Jewish date
+calendar = Zmanim::HebrewCalendar::JewishCalendar.new(5778, 7, 4)
+# => #<Zmanim::HebrewCalendar::JewishCalendar:0x007fa73c256ad0 @gregorian_date=#<Date: 2017-09-24 ((2458021j,0s,0n),+0s,-Infj)>, @absolute_date=736596, @day_of_week=1, @molad_chalakim=0, @molad_minutes=0, @molad_hours=0, @jewish_year=5778, @jewish_month=7, @jewish_day=4, @in_israel=false, @use_modern_holidays=false>
+
+formatter = Zmanim::HebrewCalendar::HebrewDateFormatter.new
+
+# Format the name of a significant day
+formatter.format_significant_day(calendar)
+#=> "Fast of Gedalyah"
+
+# Format the name of a significant shabbos
+calendar.set_jewish_date(5778, 7, 3)
+formatter.format_significant_shabbos(calendar)
+#=> "Shabbos Shuva"
+```
+
+#### Learning cycles
+
+```ruby
+# Fetch the daf for a calendar day
+daf = calendar.daf_yomi_bavli
+#=> #<Zmanim::Limudim::Limud:0x007fa73c1c7c40 ...>
+daf.description
+#=> "sanhedrin 69"
+
+# Format the daf
+limud_formatter = Zmanim::Limudim::LimudimFormatter.new
+limud_formatter.hebrew_format = true
+limud_formatter.format_talmudic(daf)
+#=> "סנהדרין סט"
+
+# Format the parsha of the week
+parsha = calendar.parshas_hashavua
+limud_formatter.format_parsha(parsha)
+#=> "פרשת האזינו"
+```
+
+There is much more functionality included than demonstrated here.  Feel free to experiment or read the source code to learn more! 
+
+---
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/pinnymz/ruby-zmanim. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## Code of Conduct
+
+Everyone interacting in the Zmanim project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/pinnymz/ruby-zmanim/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "zmanim"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/zmanim.rb

@@ -0,0 +1,6 @@
+require 'tzinfo'
+Dir[File.dirname(__FILE__) + "/**/*.rb"].each {|file| require file }
+
+module Zmanim
+  # Your code goes here...
+end

data/lib/zmanim/astronomical_calendar.rb

@@ -0,0 +1,105 @@
+module Zmanim
+  class AstronomicalCalendar
+    attr_accessor :geo_location,
+                  :astronomical_calculator,
+                  :date
+
+    GEOMETRIC_ZENITH = 90
+    CIVIL_ZENITH = 96
+    NAUTICAL_ZENITH = 102
+    ASTRONOMICAL_ZENITH = 108
+
+    MINUTE_MILLIS = 60 * 1000
+    HOUR_MILLIS = MINUTE_MILLIS * 60
+
+    def initialize(opts={})
+      @geo_location = opts[:geo_location] || Util::GeoLocation.GMT
+      @date = opts[:date] || Date.today
+      @astronomical_calculator = opts[:calculator] || Util::NOAACalculator.new
+    end
+
+    def sunrise
+      date_time_from_time_of_day utc_sunrise(GEOMETRIC_ZENITH), :sunrise
+    end
+
+    def sea_level_sunrise
+      sunrise_offset_by_degrees(GEOMETRIC_ZENITH)
+    end
+
+    def sunrise_offset_by_degrees(offset_zenith)
+      date_time_from_time_of_day utc_sea_level_sunrise(offset_zenith), :sunrise
+    end
+
+    def sunset
+      date_time_from_time_of_day utc_sunset(GEOMETRIC_ZENITH), :sunset
+    end
+
+    def sea_level_sunset
+      sunset_offset_by_degrees(GEOMETRIC_ZENITH)
+    end
+
+    def sunset_offset_by_degrees(offset_zenith)
+      date_time_from_time_of_day utc_sea_level_sunset(offset_zenith), :sunset
+    end
+
+    def utc_sunrise(zenith)
+      astronomical_calculator.utc_sunrise(adjusted_date, geo_location, zenith, adjust_for_elevation: true)
+    end
+
+    def utc_sunset(zenith)
+      astronomical_calculator.utc_sunset(adjusted_date, geo_location, zenith, adjust_for_elevation: true)
+    end
+
+    def utc_sea_level_sunrise(zenith)
+      astronomical_calculator.utc_sunrise(adjusted_date, geo_location, zenith, adjust_for_elevation: false)
+    end
+
+    def utc_sea_level_sunset(zenith)
+      astronomical_calculator.utc_sunset(adjusted_date, geo_location, zenith, adjust_for_elevation: false)
+    end
+
+    def temporal_hour(sunrise=sea_level_sunrise, sunset=sea_level_sunset)
+      return unless sunset && sunrise
+      daytime_hours = ((sunset - sunrise) * 24).to_f
+      (daytime_hours / 12) * HOUR_MILLIS
+    end
+
+    def sun_transit
+      sunrise = sea_level_sunrise
+      sunset = sea_level_sunset
+      return unless sunrise && sunset
+      noon_hour = (temporal_hour(sunrise, sunset) / HOUR_MILLIS) * 6.0
+      sunrise + (noon_hour / 24.0)
+    end
+
+    private
+
+    def adjusted_date
+      date + geo_location.antimeridian_adjustment
+    end
+
+    # returns DateTime adjusted for the provided Time Zone
+    def date_time_from_time_of_day(time_of_day, mode)
+      return unless time_of_day
+      hours, remainder = (time_of_day * 3600).divmod 3600
+      minutes, seconds = remainder.divmod 60
+      year, month, day = %i(year month day).map(&adjusted_date.method(:send))
+      utc_time = DateTime.new(year, month, day, hours, minutes, seconds, '0')
+
+      # adjust date if utc time reflects a wraparound from the local offset
+      local_offset = (geo_location.local_mean_time_offset + geo_location.standard_time_offset) / HOUR_MILLIS
+      if hours + local_offset > 18 && mode == :sunrise      # sunrise after 6pm indicates the UTC date has occurred earlier
+        utc_time -= 1
+      elsif hours + local_offset < 6 && mode == :sunset     # sunset before 6am indicates the UTC date has occurred later
+        utc_time += 1
+      end
+
+      convert_date_time_for_zone utc_time
+    end
+
+    def convert_date_time_for_zone(time)
+      converter = Util::TimeZoneConverter.new(geo_location.time_zone)
+      converter.modify_offset(time)
+    end
+  end
+end

data/lib/zmanim/hebrew_calendar/hebrew_date_formatter.rb

@@ -0,0 +1,243 @@
+# encoding: UTF-8
+module Zmanim::HebrewCalendar
+  class HebrewDateFormatter
+    extend Zmanim::Util::TextHelper
+    include Zmanim::Util::HebrewNumericFormatter
+
+    attr_accessor :hebrew_format, :use_long_hebrew_years, :long_week_format,
+                  :transliterated_days_of_week,  :transliterated_months, :transliterated_significant_days,
+                  :transliterated_significant_tefilos, :transliterated_significant_shabbosos,
+                  :hebrew_days_of_week, :hebrew_months, :hebrew_significant_days, :hebrew_significant_tefilos,
+                  :hebrew_significant_shabbosos, :hebrew_omer_prefix
+
+    HEBREW_OMER_PREFIX = 'ב'
+    FORMATTED_DAYS_OF_WEEK = {
+      transliterated: Date::DAYNAMES[0..-2] + ['Shabbos'],
+      hebrew: %w(ראשון שני שלישי רביעי חמישי ששי שבת)
+    }
+
+    FORMATTED_MONTHS = {
+        transliterated: Zmanim::HebrewCalendar::JewishCalendar::MONTHS.each_with_object({}){|m, h|
+          h[m] = titleize(m)
+        }.merge(adar_i: 'Adar I', adar_ii: 'Adar II'),
+        hebrew: {
+            nissan:   'ניסן',
+            iyar:     'אייר',
+            sivan:    'סיון',
+            tammuz:   'תמוז',
+            av:       'אב',
+            elul:     'אלול',
+            tishrei:  'תשרי',
+            cheshvan: 'חשון',
+            kislev:   'כסלו',
+            teves:    'טבת',
+            shevat:   'שבט',
+            adar:     'אדר',
+            adar_i:   'אדר א',
+            adar_ii:  'אדר ב'
+        }
+    }
+
+    FORMATTED_SIGNIFICANT_DAYS = {
+        transliterated: Zmanim::HebrewCalendar::JewishCalendar::SIGNIFICANT_DAYS.each_with_object({}){|d, h|
+          h[d] = titleize(d)
+        }.merge(tzom_gedalyah: 'Fast of Gedalyah', tenth_of_teves: 'Tenth of Teves', tu_beshvat: "Tu B'Shvat",
+                taanis_esther: 'Fast of Esther', seventeen_of_tammuz: 'Seventeenth of Tammuz',
+                tisha_beav: "Tisha B'Av", tu_beav: "Tu B'Av", yom_hashoah: 'Yom HaShoah', yom_haatzmaut: "Yom Ha'atzmaut"),
+        hebrew: {
+            erev_rosh_hashana:   'ערב ראש השנה',
+            rosh_hashana:        'ראש השנה',
+            tzom_gedalyah:       'צום גדליה',
+            erev_yom_kippur:     'ערב יום כיפור',
+            yom_kippur:          'יום כיפור',
+            erev_succos:         'ערב סוכות',
+            succos:              'סוכות',
+            chol_hamoed_succos:  'חול המועד סוכות',
+            hoshana_rabbah:      'הושענה רבה',
+            shemini_atzeres:     'שמיני עצרת',
+            simchas_torah:       'שמחת תורה',
+            chanukah:            'חנוכה',
+            tenth_of_teves:      'עשרה בטבת',
+            tu_beshvat:          'ט״ו בשבט',
+            taanis_esther:       'תענית אסתר',
+            purim:               'פורים',
+            shushan_purim:       'שושן פורים',
+            purim_katan:         'פורים קטן',
+            shushan_purim_katan: 'שושן פורים קטן',
+            erev_pesach:         'ערב פסח',
+            pesach:              'פסח',
+            chol_hamoed_pesach:  'חול המועד פסח',
+            pesach_sheni:        'פסח שני',
+            erev_shavuos:        'ערב שבועות',
+            shavuos:             'שבועות',
+            seventeen_of_tammuz: 'שבעה עשר בתמוז',
+            tisha_beav:          'תשעה באב',
+            tu_beav:             'ט״ו באב',
+            yom_hashoah:         'יום השואה',
+            yom_hazikaron:       'יום הזכרון',
+            yom_haatzmaut:       'יום העצמאות',
+            yom_yerushalayim:    'יום ירושלים',
+        }
+    }
+
+    FORMATTED_SIGNIFICANT_TEFILOS = {
+        transliterated: Zmanim::HebrewCalendar::JewishCalendar::SIGNIFICANT_TEFILOS.each_with_object({}){|d, h|
+          h[d] = titleize(d)
+        }.merge(begin_mashiv_haruach: 'Mashiv Haruach (beginning Mussaf)',
+                end_mashiv_haruach:   'Mashiv Haruach (ending Mussaf)',
+                begin_morid_hatal:    'Morid Hatal (beginning Mussaf)'),
+        hebrew: {
+            yaaleh_veyavo:        'יעלה ויבא',
+            al_hanissim:          'על הנסים',
+            begin_mashiv_haruach: 'משיב הרוח (מתחילים במוסף)',
+            end_mashiv_haruach:   'משיב הרוח (מסיימים במוסף)',
+            mashiv_haruach:       'משיב הרוח',
+            begin_morid_hatal:    'מוריד הטל (מתחילים במוסף)',
+            morid_hatal:          'מוריד הטל',
+            vesein_tal_umatar:    'ותן טל ומטר',
+            vesein_beracha:       'ותן ברכה',
+            atah_yatzarta:        'אתה יצרת',
+            borchi_nafshi:        'ברכי נפשי',
+        }
+    }
+
+    FORMATTED_SIGNIFICANT_SHABBOSOS = {
+        transliterated: Zmanim::HebrewCalendar::JewishCalendar::SIGNIFICANT_SHABBOS.each_with_object({}){|d, h|
+          h[d] = titleize(d)
+        },
+        hebrew: {
+            parshas_shekalim:  'פרשת שקלים',
+            parshas_zachor:    'פרשת זכור',
+            parshas_parah:     'פרשת פרה',
+            parshas_hachodesh: 'פרשת החדש',
+            shabbos_hagadol:   'שבת הגדול',
+            shabbos_shuva:     'שבת שובה',
+        }
+    }
+
+    def initialize
+      super  # hebrew numeric formatter
+      @long_week_format = true
+      @transliterated_days_of_week = FORMATTED_DAYS_OF_WEEK[:transliterated]
+      @transliterated_months = FORMATTED_MONTHS[:transliterated]
+      @transliterated_significant_days = FORMATTED_SIGNIFICANT_DAYS[:transliterated]
+      @transliterated_significant_tefilos = FORMATTED_SIGNIFICANT_TEFILOS[:transliterated]
+      @transliterated_significant_shabbosos = FORMATTED_SIGNIFICANT_SHABBOSOS[:transliterated]
+      @hebrew_days_of_week = FORMATTED_DAYS_OF_WEEK[:hebrew]
+      @hebrew_months = FORMATTED_MONTHS[:hebrew]
+      @hebrew_significant_days = FORMATTED_SIGNIFICANT_DAYS[:hebrew]
+      @hebrew_significant_tefilos = FORMATTED_SIGNIFICANT_TEFILOS[:hebrew]
+      @hebrew_significant_shabbosos = FORMATTED_SIGNIFICANT_SHABBOSOS[:hebrew]
+      @hebrew_omer_prefix = HEBREW_OMER_PREFIX
+    end
+
+    def format(date)
+      if hebrew_format
+        format_hebrew_number(date.jewish_day) + ' ' + format_month(date) + ' ' + format_hebrew_number(date.jewish_year)
+      else
+        "#{date.jewish_day} #{format_month(date)}, #{date.jewish_year}"
+      end
+    end
+
+    def format_month(date)
+      format_month_from_name(date.jewish_month_name, date.jewish_leap_year?)
+    end
+
+    def format_day_of_week(date)
+      format_day_of_week_from_number(date.day_of_week)
+    end
+
+    def format_hebrew_number(number)
+      super(number, use_long_hebrew_years)
+    end
+
+    def format_significant_day(calendar)
+      sd = calendar.significant_day
+      return '' unless sd
+      prefix = (day_number = calendar.day_of_chanukah) ? formatted_number(day_number) + ' ' : ''
+      prefix + formatted_significant_day(sd)
+    end
+
+    def format_rosh_chodesh(calendar)
+      return '' unless calendar.rosh_chodesh? || calendar.erev_rosh_chodesh?
+      month = calendar.jewish_month
+      day = calendar.jewish_day
+      if day != 1
+        month += 1
+        month = 1 if month > calendar.months_in_jewish_year
+      end
+      month_name = calendar.jewish_month_name(month)
+      formatted_rosh_chodesh(calendar.erev_rosh_chodesh?) + ' ' + format_month_from_name(month_name, calendar.jewish_leap_year?)
+    end
+
+    def format_omer(calendar)
+      return '' unless number = calendar.day_of_omer
+      if hebrew_format
+        format_hebrew_number(number) + ' ' + hebrew_omer_prefix + 'עומר'
+      else
+        number == 33 ? 'Lag BaOmer' : "Omer #{number}"
+      end
+    end
+
+    def format_kviah(year)
+      date = year.is_a?(Numeric) ? Zmanim::HebrewCalendar::JewishDate.new(year, 7, 1) : year
+      kviah = date.cheshvan_kislev_kviah
+      rosh_hashana_day = date.day_of_week
+      kviah_glyph = {chaseirim: 'ח', kesidran: 'כ', shelaimim: 'ש'}[kviah]
+      date.jewish_month = 1
+      pesach_day = date.day_of_week
+      "#{format_hebrew_number(rosh_hashana_day)}#{kviah_glyph}#{format_hebrew_number(pesach_day)}".delete(GERESH)
+    end
+
+    def format_tefilah_additions(calendar, customs={walled_city: false, nusach: :ashkenaz})
+      additions = calendar.tefilah_additions(walled_city: customs[:walled_city], nusach: customs[:nusach])
+      additions.map do |addition|
+        hebrew_format ?
+          hebrew_significant_tefilos[addition] :
+          transliterated_significant_tefilos[addition]
+      end
+    end
+
+    def format_significant_shabbos(calendar)
+      return '' unless shabbos = calendar.significant_shabbos
+      hebrew_format ?
+          hebrew_significant_shabbosos[shabbos] :
+          transliterated_significant_shabbosos[shabbos]
+    end
+
+    private
+
+    # We don't consider Rosh Chodesh similar to other significant days due to overlapping complexity with Chanuka
+    def formatted_rosh_chodesh(is_erev)
+      prefix = ''
+      prefix += (hebrew_format ? 'ערב ' : 'Erev ') if is_erev
+      prefix + (hebrew_format ? 'ראש חדש' : 'Rosh Chodesh')
+    end
+
+    def formatted_significant_day(sd)
+      hebrew_format ? hebrew_significant_days[sd] : transliterated_significant_days[sd]
+    end
+
+    def formatted_number(number)
+      hebrew_format ? format_hebrew_number(number) : number.to_s
+    end
+
+    def format_month_from_name(month_name, is_leap_year)
+      month_name = :adar_i if month_name == :adar && is_leap_year
+      if hebrew_format
+        suffix = use_geresh_gershayim & month_name.to_s.start_with?('adar_') ? Zmanim::Util::HebrewNumericFormatter::GERESH : ''
+        hebrew_months[month_name] + suffix
+      else
+        transliterated_months[month_name]
+      end
+    end
+
+    def format_day_of_week_from_number(number)
+      if hebrew_format
+        long_week_format ? hebrew_days_of_week[number - 1] : format_hebrew_number(number)
+      else
+        transliterated_days_of_week[number - 1]
+      end
+    end
+  end
+end