darian_calendar 0.1.0 → 0.2

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    OThlODFjMThlMDdmN2U4YzBmYTk1MGQxNjI0MzFmMzhkZmVjNWZhNA==
+    NGFkYjZjZDk2Y2MwYzA4M2NhNDI4MDczYzEzODJiNjI2ZTk4YmJjNw==
   data.tar.gz: !binary |-
-    OWZmZDg5ZWE3MWE0YWQyMzQ0NWNkMWQ4Y2YwZjQ2YzM0MDVlYmZjNQ==
+    MmNlMjdmZDQ3ZDk1ZDNmZThmNDM0YjUxY2JhM2U5M2RhOWYyMmJjMQ==
 SHA512:
   metadata.gz: !binary |-
-    ZTA3MjExNWMxYTEwYjgxZjkxYzU3MzIyNTUwYjMyYWY3YWFjY2RjNGM4MzQw
-    MTYwNzEzN2RjYjYzMTIyNGIyMjdhNzU5ZTgzOWU3ZGVmNTMzZjA3NTBmNmM4
-    ZDBiNWNiYWJjNGJiYjc4NzI0MDYxZjg5NjVhZDM1OGM1YWM5OGM=
+    MzkyNTQ3NmJlNWUyZTEzMzJhYTUzZjBkODcwMDQ3OWYyYWU4ZmY4M2Y0YTgx
+    MWNiODg0MGQ1ZDg3YWM3ZTdjNmM2YjQwNTJkM2RkOGI0YWUxZGZmNDBmMGM4
+    OTcxMTk2M2IwYzI0MWFiN2Q0ZTBjZDNmZTBkNjYxNzQ0MTE0OTU=
   data.tar.gz: !binary |-
-    ZTY3Y2I5NzBkZjBmOTYxYWE5ZjI5MGEyYmE3YTQzMmFlNjQwNTE1ZjBkMDM2
-    NTEwYjQ2NTQ4MjY3ZGJiN2FjNWMwNTJiYWQ2MjA3MGNlNjUyN2I2ZTIzNGY4
-    OTE3OWU5ZWNkNzJlNDg4YTEwOTIzMWRlNGE0YzYyOTIxMmE0MzI=
+    M2EyMmNhZmNmZGViYWY5ZWFmODEzYTUwNTljODAyMjgxNjQxMDExMTFlOWIx
+    YzlmNzFiZTllZTExYmRlMGMwMzcwYmEzMDQ5Y2IzNDgyY2YzOTgzYTI5NTJi
+    Yjg5MzE4OTFkMzAyNDg0YzA4NjgwYjY5YTFlMjQ0YzJmOTgxZGQ=

data/.gitignore

@@ -2,6 +2,8 @@ pkg
 rdoc
 doc
 .yardoc
+.ruby-version
+.ruby-gemset
 .DS_Store
 .idea/*
 *.sh

data/.rspec

@@ -1 +1 @@
---colour --format doc
+--color --format doc

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.2
+
+- Documentation with Yard
+- Minor optimization
+
 ## 0.1.0
 
 - Working version of the darian calender converter

data/Gemfile

@@ -1,5 +1,10 @@
 source "https://rubygems.org"
 
+group :development do
+  gem 'yard'
+  gem 'redcarpet'
+end
+
 group :development, :test do
   gem 'rake'
 end

data/README.md

@@ -7,7 +7,7 @@ It was created by aerospace engineer and political scientist Thomas Gangale in 1
 
 This Ruby library converts earth time to mars time and back again. You can choose between 5 variants of the Darian calendar system; _Martiana_, _Defrost_, _Areosynchronous_, _Hensel_ and _Aqua_.
 
-It's based on the [JavaScript Converter] by Thomas Gangale.
+It's based on the [JavaScript Converter] which was developed by Alan Hensel and Thomas Gangale.
 
 [Wikipedia]: http://en.wikipedia.org/wiki/Darian_calendar
 [Darian calendar]: http://en.wikipedia.org/wiki/Darian_calendar
@@ -15,8 +15,14 @@ It's based on the [JavaScript Converter] by Thomas Gangale.
 
 ## Installation
 
+In Bundler:
 ```ruby
-gem 'darian_calendar', :git => 'git://github.com/marsec/darian_calendar.git'
+gem "darian_calendar"
+```
+
+Otherwise:
+```bash
+[sudo|rvm] gem install darian_calendar
 ```
 
 ## Usage
@@ -82,6 +88,9 @@ Unit tests are provided for all of Darian Calendar's methods:
 bundle exec rspec
 ```
 
-## License
+## Copyright
+- _The Darian Calendar Ruby Gem_ is Copyright © 2014 Christian Worreschk, MarSec.
+- _The Darian System_ is Copyright © 1986-2005 by Thomas Gangale
 
+## License
 This Darian Calendar Ruby Gem is released under the [European Union Public Licence V. 1.1](http://opensource.org/licenses/EUPL-1.1).

data/lib/darian_calendar.rb

@@ -2,12 +2,18 @@
 
 require 'darian_calendar/time'
 
+# This Ruby library converts earth time to mars time and back again. You can choose between 5 variants of the Darian calendar system; Martiana, Defrost, Areosynchronous, Hensel and Aqua.
+# See http://github.com/marsec/darian_calendar for more Information.
+# It's based on the JavaScript Converter which was developed by Alan Hensel and Thomas Gangale. (http://pweb.jps.net/~tgangale/mars/converter/calendar_clock.htm)
 module DarianCalendar
 
   class << self
 
-    def now
-      DarianCalendar::Time.now
+    # Returns the current mars time. Shortcut for 'DarianCalendar::Time.now'
+    # @param type [DarianCalendar::CalendarTypes] Calendar type
+    # @return [DarianCalendar::Time] current mars time
+    def now(type=CalendarTypes::MARTIANA)
+      DarianCalendar::Time.now(type)
     end
 
   end

data/lib/darian_calendar/time.rb

@@ -2,6 +2,7 @@
 
 module DarianCalendar
 
+  # Variantes of the Darian calendar system
   module CalendarTypes
     MARTIANA        = :martiana
     DEFROST         = :defrost
@@ -10,86 +11,108 @@ module DarianCalendar
     AQUA            = :aqua
   end
 
+  # Timestamp in the Darian calendar system
   class Time
     include Comparable
 
-    #<editor-fold desc="Attributes">
-
+    # @return [Integer] year
     attr_reader :year
+    # @return [Integer] month of the year
     attr_reader :month
+    # @return [Integer] sol of the month
     attr_reader :sol
-
+    # @return [Integer] hour of the sol
     attr_reader :hour
+    # @return [Integer] minute of the hour
     attr_reader :min
+    # @return [Integer] second of the minute
     attr_reader :sec
-
+    # @return [String] full month name ("Mithuna")
     attr_reader :month_name
+    # @return [String] full weeksol name ("Sol Jovis")
     attr_reader :week_sol_name
-
+    # @return [Float] number of sols (with hour, minutes and seconds) since the earth date 0-0-0
     attr_reader :total_sols
+    # @return [String] sol of the week
     attr_reader :week_sol
+    # @return [Integer] season of the year
     attr_reader :season
+    # @return [Integer] sol of the season
     attr_reader :sol_of_season
+    # @return [Integer] month of the season
     attr_reader :month_of_season
+    # @return [Integer] sol of the year
     attr_reader :sol_of_year
-
+    # @return [String] name of the calendar type ("Martiana")
     attr_reader :calendar_type
 
     alias :day :sol
     alias :week_day :week_sol
 
-    #</editor-fold>
-
-    #<editor-fold desc="Constants">
-
     MARS_TO_EARTH_DAYS = 1.027491251
     EPOCH_OFFSET = 587744.77817
     SECONDS_A_DAY = 86400.0
     ROUND_UP_SECOND = 1/SECONDS_A_DAY;
     E_DAYS_TIL_UNIX = 719527.0
 
-    SOL_MARTIANA = ['', 'Sol Solis', 'Sol Lunae', 'Sol Martis', 'Sol Mercurii', 'Sol Jovis', 'Sol Veneris', 'Sol Saturni']
-    SOL_DEFROST  = ['', 'Axatisol', 'Benasol', 'Ciposol', 'Domesol', 'Erjasol', 'Fulisol', 'Gavisol']
-    SOL_AREOSYNCHRONOUS = ['', 'Heliosol', 'Phobosol', 'Deimosol', 'Terrasol', 'Venusol', 'Mercurisol', 'Jovisol']
-
-    MONTH_MARTIANA = ['', 'Sagittarius', 'Dhanus', 'Capricornus', 'Makara', 'Aquarius', 'Kumbha', 'Pisces', 'Mina', 'Aries', 'Mesha', 'Taurus', 'Rishabha', 'Gemini', 'Mithuna', 'Cancer', 'Karka', 'Leo', 'Simha', 'Virgo', 'Kanya', 'Libra', 'Tula', 'Scorpius', 'Vrishika']
-    MONTH_DEFROST  = ['', 'Adir', 'Bora', 'Coan', 'Deti', 'Edal', 'Flo', 'Geor', 'Heliba', 'Idanon', 'Jowani', 'Kireal', 'Larno', 'Medior', 'Neturima', 'Ozulikan', 'Pasurabi', 'Rudiakel', 'Safundo', 'Tiunor', 'Ulasja', 'Vadeun', 'Wakumi', 'Xetual', 'Zungo']
-    MONTH_HENSEL   = ['', 'Vernalis', 'Duvernalis', 'Trivernalis', 'Quadrivernalis', 'Pentavernalis', 'Hexavernalis', 'Aestas', 'Duestas', 'Triestas', 'Quadrestas', 'Pentestas', 'Hexestas', 'Autumnus', 'Duautumn', 'Triautumn', 'Quadrautumn', 'Pentautumn', 'Hexautumn', 'Unember', 'Duember', 'Triember', 'Quadrember', 'Pentember', 'Hexember']
-
-    #</editor-fold>
-
-    #<editor-fold desc="Class Methods">
-
+    SOL_NAMES = {
+      martiana: ['Sol Solis', 'Sol Lunae', 'Sol Martis', 'Sol Mercurii', 'Sol Jovis', 'Sol Veneris', 'Sol Saturni'],
+      defrost: ['Axatisol', 'Benasol', 'Ciposol', 'Domesol', 'Erjasol', 'Fulisol', 'Gavisol'],
+      areosynchronous: ['Heliosol', 'Phobosol', 'Deimosol', 'Terrasol', 'Venusol', 'Mercurisol', 'Jovisol']
+    }
+    MONTH_NAMES = {
+      martiana: ['Sagittarius', 'Dhanus', 'Capricornus', 'Makara', 'Aquarius', 'Kumbha', 'Pisces', 'Mina', 'Aries', 'Mesha', 'Taurus', 'Rishabha', 'Gemini', 'Mithuna', 'Cancer', 'Karka', 'Leo', 'Simha', 'Virgo', 'Kanya', 'Libra', 'Tula', 'Scorpius', 'Vrishika'],
+      defrost: ['Adir', 'Bora', 'Coan', 'Deti', 'Edal', 'Flo', 'Geor', 'Heliba', 'Idanon', 'Jowani', 'Kireal', 'Larno', 'Medior', 'Neturima', 'Ozulikan', 'Pasurabi', 'Rudiakel', 'Safundo', 'Tiunor', 'Ulasja', 'Vadeun', 'Wakumi', 'Xetual', 'Zungo'],
+      hensel: ['Vernalis', 'Duvernalis', 'Trivernalis', 'Quadrivernalis', 'Pentavernalis', 'Hexavernalis', 'Aestas', 'Duestas', 'Triestas', 'Quadrestas', 'Pentestas', 'Hexestas', 'Autumnus', 'Duautumn', 'Triautumn', 'Quadrautumn', 'Pentautumn', 'Hexautumn', 'Unember', 'Duember', 'Triember', 'Quadrember', 'Pentember', 'Hexember']
+    }
+
+    # Calculates the total number of martian sols for this earth time
+    # @param earth_time [Time] Earth time
+    # @return [Integer] number of sols
     def self.sols_from_earth_time(earth_time)
       days = (earth_time.to_f / SECONDS_A_DAY) + E_DAYS_TIL_UNIX
       sols = (days - EPOCH_OFFSET) / MARS_TO_EARTH_DAYS
       return sols
     end
 
+    # Converts a time object to a mars time object
+    # @param earth_time [Time] Earth time
+    # @param type [DarianCalendar::CalendarTypes] Calendar type
+    # @return [DarianCalendar::Time] mars time
     def self.from_earth(earth_time, type=CalendarTypes::MARTIANA)
       self.new(self.sols_from_earth_time(earth_time), type)
     end
 
+    # Parses the given representation of date and time, and converts it to mars time
+    # @param string [String] String with date and time
+    # @param type [DarianCalendar::CalendarTypes] Calendar type
+    # @return [DarianCalendar::Time] mars time
     def self.parse_earth(string, type=CalendarTypes::MARTIANA)
       self.from_earth(::Time.parse(string), type)
     end
 
+    # Returns the current mars time.
+    # @param type [DarianCalendar::CalendarTypes] Calendar type
+    # @return [DarianCalendar::Time] current mars time
     def self.now(type=CalendarTypes::MARTIANA)
       self.from_earth(::Time.now, type)
     end
 
-    #</editor-fold>
-
-    #<editor-fold desc="Instance Methods">
-
+    # Compares two times and returns -1, zero, 1 or nil. The other should be a mars time object.
+    # @param another [DarianCalendar::Time]
+    # @return [Integer] Compare result
     def <=>(another)
       @total_sols <=> another.total_sols
     end
 
+    # Return the number of sols in the given year
+    # @return [Integer] Number of sols in the given year
     def sols_in_year
       self.leap? ? 669 : 668
     end
 
+    # Returns true if the given year is a leap year
+    # @return [Boolean] true if the given year is a leap year
     def leap?
       return true if (@year % 500) == 0
       return false if (@year % 100) == 0
@@ -98,16 +121,24 @@ module DarianCalendar
       return true
     end
 
+    # Converts the given mars time to earth time
+    # @return [Time] earth time
     def to_earth
       earth_days = (@total_sols * MARS_TO_EARTH_DAYS) + EPOCH_OFFSET + ROUND_UP_SECOND
       earth_seconds = ((earth_days - E_DAYS_TIL_UNIX) * SECONDS_A_DAY) - 1
       ::Time.at(earth_seconds)
     end
 
+    # Returns a string in an ISO 8601 format (This method doesn’t use the expanded representations).
+    # @return [String] Time as a string in an ISO 8601 format
     def to_s
       sprintf('%d-%02d-%02d %02d:%02d:%02d', @year, @month, @sol, @hour, @min, @sec)
     end
 
+    # Converts a number of martian sols to mars time.
+    # @param sols optional [Float] Number of martian sols. Default is the number of sols of the the current time.
+    # @param type optional [DarianCalendar::CalendarTypes] calendar type.
+    # @return [DarianCalendar::Time] mars time
     def initialize(sols=nil, type=CalendarTypes::MARTIANA)
       @calendar_type = type.to_s.capitalize
       @total_sols = sols.to_f != 0 ? sols.to_f : self.sols_from_earth_time(::Time.now)
@@ -167,17 +198,17 @@ module DarianCalendar
       @week_sol = ((@sol - 1) % 7) + 1 # 1-7
 
       @week_sol_name = case type
-        when CalendarTypes::MARTIANA, CalendarTypes::HENSEL then SOL_MARTIANA[@week_sol]
-        when CalendarTypes::DEFROST then SOL_DEFROST[@week_sol]
-        when CalendarTypes::AREOSYNCHRONOUS then SOL_AREOSYNCHRONOUS[@week_sol]
+        when CalendarTypes::MARTIANA, CalendarTypes::HENSEL then SOL_NAMES[:martiana][@week_sol-1]
+        when CalendarTypes::DEFROST then SOL_NAMES[:defrost][@week_sol-1]
+        when CalendarTypes::AREOSYNCHRONOUS then SOL_NAMES[:areosynchronous][@week_sol-1]
         when CalendarTypes::AQUA then @week_sol.to_s
         else ''
       end
 
       @month_name = case type
-        when CalendarTypes::MARTIANA then MONTH_MARTIANA[@month]
-        when CalendarTypes::DEFROST, CalendarTypes::AREOSYNCHRONOUS then MONTH_DEFROST[@month]
-        when CalendarTypes::HENSEL then MONTH_HENSEL[@month]
+        when CalendarTypes::MARTIANA then MONTH_NAMES[:martiana][@month-1]
+        when CalendarTypes::DEFROST, CalendarTypes::AREOSYNCHRONOUS then MONTH_NAMES[:defrost][@month-1]
+        when CalendarTypes::HENSEL then MONTH_NAMES[:hensel][@month-1]
         when CalendarTypes::AQUA then @month.to_s
         else ''
       end
@@ -191,7 +222,5 @@ module DarianCalendar
       @sec  = ((min - min.floor) * 60).floor
     end
 
-    #</editor-fold>
-
   end
 end

data/lib/darian_calendar/version.rb

@@ -1,3 +1,3 @@
 module DarianCalendar
-  VERSION = '0.1.0'
+  VERSION = '0.2'
 end

data/spec/time_spec.rb

@@ -78,7 +78,7 @@ describe DarianCalendar::Time do
     end
 
     describe '#sols_in_year' do
-      it 'returns the count of sols in a martian year' do
+      it 'returns the number of sols in a martian year' do
         leap_mars_time  = DarianCalendar::Time.from_earth(Time.utc(2013, 10, 15, 16, 50, 0))
         leap_mars_time.sols_in_year.should == 669
         @mars_time.sols_in_year.should     == 668

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: darian_calendar
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: '0.2'
 platform: ruby
 authors:
 - Christian Worreschk
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-07 00:00:00.000000000 Z
+date: 2014-02-08 00:00:00.000000000 Z
 dependencies: []
 description: This Ruby library converts earth time to mars time and back again. You
   can choose between 5 variants of the Darian calendar system; Martiana, Defrost,
@@ -63,3 +63,4 @@ specification_version: 4
 summary: Converts earth time to mars time and back again. You can choose between 5
   variants of the Darian calendar system.
 test_files: []
+has_rdoc: