prayer_times 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 88ba28e5dfcc4e57a3cb76df12221a046202ff41
+  data.tar.gz: d8d1255686349c190550f835fbd8d25e4f610344
+SHA512:
+  metadata.gz: eed7fbbc8d954955ad284590a9e07f1784cbf41f1296185fc036fa331e1be13976d37d8110321d5af7e93a44fa7269b275689286c8c7a2ce7e7953912be33163
+  data.tar.gz: cf76f062cb054529ce1b40daab520bf555209ae643b712cb5ec4cf701c9d5b1d34c8e3be6a110e09ec5ff314619d2368d5e044381a893abc853a121cbdcbd311

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+.project
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in prayer_times.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,14 @@
+Copyright (c) 2013 Khaled alHabache
+
+Original js Code: Hamid Zarrabi-Zadeh - PrayTimes.org
+
+License: GNU LGPL v3.0
+
+TERMS OF USE:
+	Permission is granted to use this code, with or
+	without modification, in any website or application
+	provided that credit is given to the original work
+	with a link back to PrayTimes.org.
+
+This program is distributed in the hope that it will
+be useful, but WITHOUT ANY WARRANTY.

data/README.md

@@ -0,0 +1,81 @@
+# PrayerTimes
+
+Flexiable and configurable calculation for Muslim prayers times.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'prayer_times'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install prayer_times
+
+## Usage
+
+### Baisc usage
+
+```ruby
+require 'prayer_times'
+pt = PrayerTimes.new("Makkah")
+times = pt.get_times(Date.today(), [31,36], 3)
+puts times.inspect
+```
+
+### Global configuration
+
+You can have a [global configuration](https://github.com/Startappz/prayer_times/wiki/Global-Configuration) through the PrayerTimes module:
+
+```ruby
+require 'prayer_times'
+PrayerTimes.time_format = '12h'
+PrayerTimes.time_suffixes = {:am => 'صباحا', :pm => 'مساءا'}
+# and others...
+```
+#### Adding more methods
+
+There are [several methods](https://github.com/Startappz/prayer_times/wiki/Calculation-Methods) that are shiped with this gem by default. You can list, add new or update existing ones.
+
+```ruby
+PrayerTimes.calculation_methods
+PrayerTimes.calculation_methods.names
+PrayerTimes.calculation_methods.add("Test", "Testing method", fajr: 16.5, asr: 'Hanafi', isha: '80 min') 
+new_method = PrayerTimes.calculation_methods["Test"]
+new_method.description = "new description"
+new_method.settings = {fajr: 19.5, isha: '33 min'}
+PrayerTimes.calculation_methods.delete("Test")
+```
+
+### Instance configuration
+
+As with the global configuration, you can [set](https://github.com/Startappz/prayer_times/wiki/Instance-Configuration) the configuration on the object level:
+
+```ruby
+require 'prayer_times'
+PrayerTimes.time_format = '12h'
+PrayerTimes.time_suffixes = {am: 'صباحا', pm: 'مساءا'}
+options = {
+	time_format: '12h',
+	time_suffixes: {am: => 'صباحا', pm: 'مساءا'}
+	# and others...
+}
+pt = PrayerTimes.new("Makkah", options)
+```
+
+## Help
+
+Youre help is appreciated, specially in adjusting the calculation methods and making them more accurate. 
+Your contribution is welcome.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+ 
+Rake::TestTask.new do |t|
+  t.libs << 'lib/prayer_times'
+  t.test_files = FileList['test/lib/prayer_times/*_test.rb']
+  t.verbose = true
+end
+ 
+task :default => :test
+

data/lib/prayer_times/calculation.rb

@@ -0,0 +1,236 @@
+module PrayerTimes
+  # Calculation class used to do the times calculation in given settings
+  class Calculation
+    extend Forwardable
+    include MathHelpers
+
+    def_delegators :@calculator, :time_suffixes, :time_format, :invalid_time, :iterations_count, :times_offsets
+    
+    # Gets the prayers times
+    # @param [PrayTime] calculator parent class
+    # @param [Date] date the desired date
+    #   It accepts an array as well [year, month, day]
+    # @param [Array] coords of type [long, lat [,alt]]
+    # @param [Integer] time_zone the time zone
+    def initialize(calculator, date, coords, time_zone)
+      self.calculator = calculator
+      self.lat = coords[0]
+      self.lng = coords[1]
+      self.elv = coords.size > 2 ? coords[2] : 0
+      self.time_zone = time_zone
+      date = Date.new(date[0], date[1], date[2]) unless date.is_a? Date
+      self.jdate = date.ajd.to_f - lng / (15 * 24.0)
+    end 
+
+    # Compute prayer times
+    # @return [Hash] times
+    def compute
+      times = {
+        imsak: 5, fajr: 5, sunrise: 6, dhuhr: 12,
+        asr: 13, sunset: 18, maghrib: 18, isha: 18
+      }
+      # main iterations
+      iterations_count.times{times = compute_prayer_times(times)}
+      times = adjust_times(times)
+
+      # add midnight time
+      if method_settings[:midnight] == 'Jafari'
+        times[:midnight] = times[:sunset] + time_diff(times[:sunset], times[:fajr]) / 2
+      else
+        times[:midnight] = times[:sunset] + time_diff(times[:sunset], times[:sunrise]) / 2
+      end
+
+      times = tune_times(times)
+      modify_formats(times)
+      set_names(times)
+    end 
+
+    private 
+
+    attr_accessor :calculator, :time_zone, :lat, :lng, :elv, :jdate
+
+
+    # convert float time to the given format (see time_formats)
+    def get_formatted_time(time)
+      return invalid_time if time.nan?
+      return time if time_format == 'Float'
+      time = fix_hour(time + 0.5 / 60)  # add 0.5 minutes to round
+      hours = time.floor
+      minutes = ((time - hours) * 60).floor
+      suffix = time_format == '12h' ? time_suffixes[hours < 12 ? :am : :pm ] : ''
+      formatted_time =  (time_format == "24h") ?  ("%02d:%02d" % [hours, minutes]) : "%d:%02d" % [((hours + 11) % 12)+1, minutes]
+      formatted_time + suffix
+    end
+
+    # compute mid-day time
+    def mid_day(time)
+      eqt = sun_position(jdate + time)[1]
+        fix_hour(12 - eqt)
+    end
+      
+    # compute the time at which sun reaches a specific angle below horizon 
+    def sun_angle_time(angle, time, direction = nil)
+      decl = sun_position(jdate + time)[0]
+      noon = mid_day(time)
+      t = 1/15.0 * darccos((-rsin(angle)- rsin(decl)* rsin(lat))/
+          (rcos(decl) * rcos(lat)))
+      return noon + (direction == 'ccw' ? -t : t)
+    rescue
+      return (0/0.0)    
+    end
+
+    # compute asr time
+    def asr_time(factor, time) 
+      decl = sun_position(jdate + time)[0]
+      angle = -darccot(factor + rtan(lat - decl).abs)
+        sun_angle_time(angle, time)
+    end
+
+    # compute declination angle of sun and equation of time
+    # Ref: http://aa.usno.navy.mil/faq/docs/SunApprox.php
+    def sun_position(jd)
+      d = jd - 2451545.0
+      g = fix_angle(357.529 + 0.98560028 * d)
+      q = fix_angle(280.459 + 0.98564736 * d)
+      l = fix_angle(q + 1.915* rsin(g) + 0.020* rsin(2*g))
+
+      #r = 1.00014 - 0.01671 * cos(g) - 0.00014 * cos(2*g)
+      e = 23.439 - 0.00000036 * d
+
+      ra = darctan2(rcos(e)* rsin(l), rcos(l))/ 15.0
+      eqt = q / 15.0 - fix_hour(ra)
+      decl = darcsin(rsin(e)* rsin(l))
+
+      [decl, eqt]
+    end
+
+
+    # compute prayer times at given julian date
+    def compute_prayer_times(times)
+        day_portion(times)
+        {
+          imsak:   sun_angle_time(method_settings[:imsak].to_f, times[:imsak], 'ccw'),
+          fajr:    sun_angle_time(method_settings[:fajr].to_f, times[:fajr], 'ccw'),
+          sunrise: sun_angle_time(rise_set_angle(elv), times[:sunrise], 'ccw'),
+          dhuhr:   mid_day(times[:dhuhr]),
+          asr:     asr_time(asr_factor(method_settings[:asr]), times[:asr]),
+          sunset:  sun_angle_time(rise_set_angle(elv), times[:sunset]),
+          maghrib: sun_angle_time(method_settings[:maghrib].to_f, times[:maghrib]),
+          isha:    sun_angle_time(method_settings[:isha].to_f, times[:isha]) 
+      }
+    end
+
+    # adjust times in a prayer time array
+    def adjust_times(times)
+      tz_adjust = time_zone - lng / 15.0
+      times.keys.each{|k| times[k] += tz_adjust}
+      if !method_settings[:high_lats].nil?
+        times = adjust_high_lats(times)
+      end
+
+      if minute?(method_settings[:imsak])
+        times[:imsak] = times[:fajr] - method_settings[:imsak].to_f / 60.0
+      end
+      # need to ask about 'min' settings
+      if minute?(method_settings[:maghrib])
+        times[:maghrib] = times[:sunset] + method_settings[:maghrib].to_f / 60.0
+      end
+      if minute?(method_settings[:isha])
+        times[:isha] = times[:maghrib] + method_settings[:isha].to_f / 60.0
+      end
+
+      times[:dhuhr] += method_settings[:dhuhr].to_f / 60.0
+
+      return times
+    end
+
+    # get asr shadow factor
+    def asr_factor(asr)
+      calc_methods = {'Standard' => 1, 'Hanafi' => 2}
+      calc_methods.include?(asr) ? calc_methods[asr] : asr.to_f
+    end
+
+    # return sun angle for sunset/sunrise
+    def rise_set_angle(elevation = 0)
+      0.833 + 0.0347 * Math.sqrt(elevation) # an approximation
+    end
+
+    # apply offsets to the times
+    def tune_times(times)
+      times.each{|k,_| times[k] += (method_offsets[k] + times_offsets[k]) / 60.0}
+    end
+
+    # convert times to given time format
+    def modify_formats(times)
+      times.each{|k,_| times[k] = get_formatted_time(times[k])}
+    end
+    
+    def set_names(times)
+      res = {}
+      calculator.times_names.each{|k,v| res[v] = times[k]}
+      res
+    end
+
+    # adjust times for locations in higher latitudes
+    def adjust_high_lats(times)
+      night_time = time_diff(times[:sunset], times[:sunrise]) # sunset to sunrise
+      times[:imsak] = adjust_hl_time(times[:imsak], times[:sunrise], method_settings[:imsak].to_f, night_time, 'ccw')
+      times[:fajr]  = adjust_hl_time(times[:fajr], times[:sunrise], method_settings[:fajr].to_f, night_time, 'ccw')
+      times[:isha]  = adjust_hl_time(times[:isha], times[:sunset], method_settings[:isha].to_f, night_time)
+      times[:maghrib] = adjust_hl_time(times[:maghrib], times[:sunset], method_settings[:maghrib].to_f, night_time)
+        times
+    end
+
+    # adjust a time for higher latitudes
+    def adjust_hl_time(time, base, angle, night, direction = nil)
+      portion = night_portion(angle, night)
+      diff = direction == 'ccw' ? time_diff(time, base) : time_diff(base, time)
+      if time.nan? or (diff > portion)
+        time = base + (direction == 'ccw' ? - portion : portion)
+      end
+      time
+    end
+
+    # the night portion used for adjusting times in higher latitudes
+    def night_portion(angle, night)
+      hl_method = method_settings[:high_lats]
+      portion = 1/2.0  # midnight
+      portion = 1/60.0 * angle if hl_method == 'AngleBased'
+      portion = 1/7.0 if hl_method == 'OneSeventh'
+        portion * night
+      end
+
+    # convert hours to day portions
+    def day_portion(times)
+      times.each{|k,v| times[k] = times[k] / 24.0}
+    end
+    
+    # compute the difference between two times
+    def time_diff(time1, time2); fix_hour(time2 - time1); end
+
+
+    # detect if input contains 'min'
+    def minute?(arg); arg.to_s.include? "min"; end
+
+    def fix_hour(hour); fix(hour, 24.0) ; end
+
+
+    def fix_angle(angle); fix(angle, 360.0) ; end
+
+    def fix(a, mode)
+      return a if a.nan?
+      a = a - mode * (a / mode).floor
+      a < 0 ? a + mode : a
+    end
+    
+    def method_settings
+      @m_settings ||= calculator.calculation_method.settings
+    end
+    
+    def method_offsets
+      @m_offsets ||= calculator.calculation_method.offsets
+    end
+
+  end
+
+end

data/lib/prayer_times/calculation_method.rb

@@ -0,0 +1,85 @@
+module PrayerTimes
+  # Calculation method instances and logic is encapsulated here
+  class CalculationMethod
+    attr_reader :name, :description, :settings, :offsets
+    attr_writer :description
+    
+    # Default settings
+    def self.default_settings
+      {
+        imsak:      '10 min',
+        dhuhr:      '0 min',
+        asr:        'Standard',
+        maghrib:    '0 min',
+        midnight:   'Standard',
+        high_lats:  'NightMiddle'
+      }
+    end
+    
+    # Initializer
+    # @param [String] name
+    # @param [String] description  
+    # @param [Hash] settings 
+    # @option settings [String] :imsak
+    # @option settings [String] :fajr
+    # @option settings [String] :sunrise
+    # @option settings [String] :dhuhr
+    # @option settings [String] :asr Asr Juristic Methods:
+    #   'Standard':  Shafi`i, Maliki, Ja`fari and Hanbali, 
+    #   'Hanafi':    Hanafi
+    # @option settings [String] :sunset
+    # @option settings [String] :maghrib
+    # @option settings [String] :isha
+    # @option settings [String] :midnight Midnight Mode:
+    #   'Standard':     Mid Sunset to Sunrise, 
+    #   'Jafari':       Mid Sunset to Fajr   
+    # @option settings [String] :high_lights Adjust Methods for Higher Latitudes:
+    #   'NightMiddle': middle of night, 
+    #   'AngleBased':  angle/60th of night, 
+    #   'OneSeventh':   1/7th of night, 
+    #   'None'
+    # @param [Hash] offsets
+    # @option offsets [String] :imsak
+    # @option offsets [String] :fajr
+    # @option offsets [String] :sunrise
+    # @option offsets [String] :dhuhr
+    # @option offsets [String] :asr
+    # @option offsets [String] :sunset
+    # @option offsets [String] :maghrib
+    # @option offsets [String] :isha
+    # @option offsets [String] :midnight
+    def initialize(name,description,settings={}, offsets = {})
+      self.name = name
+      self.description = description
+      self.settings = settings
+      self.offsets = offsets
+    end
+  
+    # Sets times settings
+    # @param [Hash] settings
+    # Check the initializer         
+    def settings=(settings)
+      s = settings.reject{|k,v| !(Constants.times_names.key?(k))} rescue {}
+      @settings = self.class.default_settings.merge(s) 
+    end
+    
+    # Sets times offsets
+    # @param [Hash] offsets
+    # Check the initializer         
+    def offsets=(offsets)
+      s = offsets.reject{|k,v| !(Constants.times_offsets.key?(k) and v.is_a?(Numeric))} rescue {}
+      @offsets = Constants.times_offsets.merge(s) 
+    end
+    
+      
+    # @return readable representation of this object
+    def to_s
+      name
+    end
+    
+    private
+    
+    attr_writer :name
+    
+  end
+end

data/lib/prayer_times/calculation_methods.rb

@@ -0,0 +1,144 @@
+module PrayerTimes
+  # Helper class to initiate a list of calculation methods and add/update others
+  class CalculationMethods
+    extend Forwardable
+    def_delegators :@hash, :[], :length, :each, :key?, :keys, :delete, :to_s
+    
+    # default methods defined in this gem
+    # Methods MWL, ISNA, Egypt, Makkah, Karachi, Tehran and Jafari are accurate
+    # Other methods need validation. Your help is appreciated.
+    def self.default_methods
+      {
+        "MWL" =>{
+          desc: 'Muslim World League',
+          settings: {fajr: 18, isha: 17}
+        },
+        'ISNA' => { 
+          desc: 'Islamic Society of North America (ISNA)',
+          settings: {fajr: 15, isha: 15}
+        },
+        'Egypt' => {
+          desc: 'Egyptian General Authority of Survey',
+          settings: {fajr: 19.5, isha: 17.5}
+        },
+        'Makkah' => {
+            desc: 'Umm Al-Qura University, Makkah',
+            settings: {fajr: 18.5, isha: '90 min'}  # fajr was 19 degrees before 1430 hijri
+        },
+        'Karachi' => {
+          desc: 'University of Islamic Sciences, Karachi',
+          settings: {fajr: 18, isha: 18}
+        },
+        'Tehran' => {
+          desc: 'Institute of Geophysics, University of Tehran',
+          settings: {fajr: 17.7, maghrib: 4.5, isha: 14, midnight: 'Jafari'}  # isha is not explicitly specified in this method
+        },
+       'Jafari' => {
+          desc: 'Shia Ithna-Ashari, Leva Institute, Qum',
+          settings: {fajr: 16, maghrib: 4, isha: 14, midnight: 'Jafari'}
+        },
+       'UOIF' =>{
+          desc: "UNION DES ORGANISATIONS ISLAMIQUES DE FRANCE",
+          settings: {fajr: 19, maghrib: '0 min', isha: 17} 
+        },
+        'Algeria' =>{
+          desc: "Algeria",
+          settings: {fajr: 18, maghrib: '3 min',  isha: 17}
+        },
+        'EmirateDubai' =>{
+          desc: "Emirate, Dubai",
+          settings: {fajr: 18.5, maghrib: '0 min',  isha: '90 min'},
+          offsets: {dhuhr: 4, asr: 5, maghrib: 2}
+        },
+        'Emirates' =>{
+          desc: "Emirates",
+          settings: {fajr: 18.5, maghrib: '0 min',  isha: '90 min'},
+          offsets: {asr: 4, maghrib: 2}
+        },
+        'EnglandBirmingham' =>{
+          desc: "England, Birmingham",
+          settings: {fajr: 5, maghrib: '0 min',  isha: 84},
+          offsets: {fajr: -60, isha: 60}
+        },
+        'Jordan' =>{
+          desc: "General Iftaa' Department, The Hashemite Kingdom of Jordan",
+          settings: {fajr: 18, maghrib: '0 min', isha: 18} 
+        },
+        'Kuwait' =>{
+          desc: "Kuwait",
+          settings: {fajr: 18, maghrib: '0 min', isha: 17.5} 
+        },
+        'Libya' =>{
+          desc: "Libya",
+          settings: {fajr: 18.5, maghrib: '0 min',  isha: 18.5},
+          offsets: { dhuhr: 4, maghrib: 4}
+        },
+        'Malaysia' =>{
+          desc: "Malaysia",
+          settings: {fajr: 20, maghrib: '0 min',  isha: 18},
+          offsets: {fajr: 3, sunrise: 2, dhuhr: 1, asr: 2, maghrib: 1, isha: -1}
+        },
+        'Maldives' =>{
+          desc: "Maldives",
+          settings: {fajr: 19, maghrib: '0 min',  isha: 19},
+          offsets: {sunrise: -1, dhuhr: 4, asr: 1, maghrib: 1, isha: 1}
+        },
+        'Morocco' =>{
+          desc: "Morocco",
+          settings: {fajr: 19, maghrib: '0 min',  isha: 17},
+          offsets:  {fajr: -1, sunrise: -2, dhuhr: 5, maghrib: 3}
+        },
+        'Oman' =>{
+          desc: "Oman",
+          settings: {fajr: 18, maghrib: '5 min',  isha: 18},
+          offsets: {dhuhr: 5, asr: 5, isha: 1}
+        },
+        'Qatar' =>{
+          desc: "Qatar",
+          settings: {fajr: 18, maghrib: '0 min',  isha: '90 min'}
+        },
+        'Tunisia' =>{
+          desc: "Tunisia",
+          settings: {fajr: 18, maghrib: '1 min',  isha: 18},
+          offsets:  {fajr: -1, sunrise: -2, dhuhr: 8, isha: 1}
+        },
+        'Turkey' =>{
+          desc: "Presidency of Religious Affairs, Turkey",
+          settings: {fajr: 18, maghrib: '9 min',  isha: 17},
+          offsets: {fajr: -2, sunrise: -7, dhuhr: 6, asr: 4, isha: 2}
+        }
+      }
+    end
+    
+    # Initializer
+    # it populates a hash with predefined set of methods
+    def initialize
+      self.hash = {}
+      populate
+    end
+    
+    # @param [String] name
+    # @param [String] description
+    # @param [Hash] settings
+    # @param [Hash] offsets
+    # @see CalculationMethod
+    def add(name, description, settings={}, offsets={})
+      hash[name] = CalculationMethod.new(name, description, settings, offsets)
+    end
+   
+    # Names of the available methods
+    # @return [Array] list of names
+    def names
+      keys
+    end
+    
+    private
+    
+    attr_accessor :hash
+    
+    def populate
+      self.class.default_methods.each {|k,v| add(k, v[:desc], v[:settings], v[:offsets])}
+    end 
+    
+  end
+end

data/lib/prayer_times/calculator.rb

@@ -0,0 +1,57 @@
+module PrayerTimes
+  # This is main interface class
+  class Calculator
+    include Setters
+    
+    attr_reader :calculation_method, :time_format, :times_names, :time_suffixes, :invalid_time, :iterations_count, :times_offsets
+    
+    # Initializer
+    # @param [String] calc_method the calculation method to use
+    # @param [Hash] opts formatting options
+    # @option opts [String] :time_format
+    # @option opts [String] :invalid_time
+    # @option opts [String] :time_suffixes
+    # @option opts [String] :times_names
+    # @option opts [String] :times_offsets
+    # @option opts [String] :iterations_count this is algorithmic option. Don't set it unless you know what you are doing
+    # @see Setters to get an idea about those options
+    def initialize(calc_method, opts)
+      self.calculation_method = calc_method
+
+      self.time_format = opts[:time_format]
+
+      self.invalid_time = opts[:invalid_time]
+
+      self.time_suffixes = (opts[:time_suffixes])
+
+      self.times_names = (opts[:times_names])
+
+      self.times_offsets = (opts[:times_offsets])
+
+      self.iterations_count = opts[:iterations_count]
+    end
+
+   
+
+    # Gets the prayers times
+    # @param [Date] date the date
+    # @param [Array] coords of type [long, lat [,alt]]
+    # @param [Integer] time_zone the time zone
+    # @param [Integer] dst Daylight saving time
+    # @return [Hash] times
+    def get_times(date, coords, time_zone, dst = nil)
+      Calculation.new(self,
+      date,
+      coords,
+      time_zone + (dst.nil? ? 0 : 1)).
+      compute
+    end
+    
+    private
+    
+    def const_class
+      PrayerTimes
+    end
+
+  end
+end