carbon_date 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 15ca7832b179451649cfe8cbf847532875ba167b
-  data.tar.gz: 8131707b3b7d297ead922c9cde6ef1caf0186d17
+  metadata.gz: c60c02d57fde03497403333831fb9c699374bd78
+  data.tar.gz: 1a65132b4dff055a69503b2c58138482872d11f7
 SHA512:
-  metadata.gz: 3fef630e9f37ff2d13d51f97d84e6cfe07d8d841ce645f22adc6686650d4250ab377f7eccddae5d5ad5e66b1e19db6aa858a0048944331eac0ceef372b408b96
-  data.tar.gz: 3117e099d4ae329636dfe80f9d7c0f203657be0112bd4584d30993076d8f870855ad9744267e7f8b1c3d476e4c5b75dca8d8d30fac3d041c5a1846f68bc2fa83
+  metadata.gz: ea46f3105ebf35dbf78b2dc9bfc66ec6e94e35a07fbe28f29db8b65a46e8e186efe02fc0a6d8855424b37dc279605181c2091c8c5ffbb984f4247f510fa55b3f
+  data.tar.gz: 02b78be58c703446b079467a916ab7d7f5d154805708e22cdde7ff17c66cd53e2dd853df87017f91db7499690614139278d6f193b2f331145dda9d13a0d719cd

data/.gitignore

@@ -8,4 +8,5 @@
 /spec/reports/
 /tmp/
 /test/html_reports/
-/*.gem
+/*.gem
+/.coveralls.yml

data/README.md

@@ -1,4 +1,6 @@
 [![Gem Version](http://img.shields.io/gem/v/carbon_date.svg?style=flat-square)](https://rubygems.org/gems/carbon_date)
+[![Coverage Status](https://coveralls.io/repos/github/bradleymarques/carbon_date/badge.svg?branch=master)](https://coveralls.io/github/bradleymarques/carbon_date?branch=master)
+[![Inline docs](http://inch-ci.org/github/bradleymarques/carbon_date.svg?branch=master)](http://inch-ci.org/github/bradleymarques/carbon_date)
 [![License](http://img.shields.io/:license-mit-blue.svg?style=flat-square)](http://bradleymarques.mit-license.org)
 
 # CarbonDate

data/carbon_date.gemspec

@@ -36,6 +36,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'pry', '~> 0.10.3', '>= 0.10.3'
   spec.add_development_dependency 'rdoc', '~> 4.2.2', '>= 4.2.2'
   spec.add_development_dependency 'mocha', '~> 1.1.0', '>= 1.1.0'
+  spec.add_development_dependency 'coveralls', '~> 0.8.13', '>= 0.8.13'
+
 
   spec.add_dependency 'activesupport', '~> 4.2.6', '>= 4.2.6'
 end

data/lib/carbon_date.rb

@@ -3,6 +3,13 @@ require 'carbon_date/formatter'
 require 'carbon_date/standard_formatter'
 require 'carbon_date/version'
 
+##
+# Provides a custom implmentation of +Date+ with precision.
+#
+# Classes:
+# - +Date+
+# - +Formatter+
+# - +StandardFormatter+ < +Formatter+
 module CarbonDate
 
 

data/lib/carbon_date/date.rb

@@ -4,39 +4,68 @@ require 'carbon_date/standard_formatter'
 module CarbonDate
 
   ##
-  # A date with a precision
+  # Models a date with a precision.
+  # The conventions of the Gregorian Calendar are used to model dates.
   class Date
 
+    # The class-wide Formatter to use to turn CarbonDate::Dates into human-readable strings
     @formatter = CarbonDate::StandardFormatter.new
 
     class << self
+      # Used to get and set the CarbonDate::Date.formatter
       attr_accessor :formatter
     end
 
     ##
     # The precisions available
-    #
-    # TODO: Consider refactoring into a simple array of symbols, since level could be replaced by the index in the array
-    PRECISION = [
-      {symbol: :second, level: 14},
-      {symbol: :minute, level: 13},
-      {symbol: :hour, level: 12},
-      {symbol: :day, level: 11},
-      {symbol: :month, level: 10},
-      {symbol: :year, level: 9,},
-      {symbol: :decade, level: 8,},
-      {symbol: :century, level: 7,},
-      {symbol: :millennium, level: 6,},
-      {symbol: :ten_thousand_years, level: 5,},
-      {symbol: :hundred_thousand_years, level: 4},
-      {symbol: :million_years, level: 3},
-      {symbol: :ten_million_years, level: 2},
-      {symbol: :hundred_million_years, level: 1},
-      {symbol: :billion_years, level: 0}
+    PRECISION =
+    [
+      :billion_years,
+      :hundred_million_years,
+      :ten_million_years,
+      :million_years,
+      :hundred_thousand_years,
+      :ten_thousand_years,
+      :millennium,
+      :century,
+      :decade,
+      :year,
+      :month,
+      :day,
+      :hour,
+      :minute,
+      :second
     ]
 
-    attr_reader :precision, :year, :month, :day, :hour, :minute, :second
-
+    # The date's precision
+    attr_reader :precision
+    # The date's year. Cannot be 0 as there is no 0 year in the Gregorian Calendar.
+    attr_reader :year
+    # The date's month in range (1..12)
+    attr_reader :month
+    # The date's day counting from 1
+    attr_reader :day
+    # The date's hour in range (0..23)
+    attr_reader :hour
+    # The date's minute in range (0..59)
+    attr_reader :minute
+    # The date's second in range (0..59)
+    attr_reader :second
+
+    # Creates a new CarbonDate::Date
+    #
+    # Params:
+    # +year+ - The date's year, as an integer
+    # +month+ - The date's month, as an integer
+    # +day+ - The date's day, as an integer
+    # +hour+ - The date's hour, as an integer
+    # +minute+ - The date's minute, as an integer
+    # +second+ - The date's second, as an integer
+    # +:precision+ - The date's precision, as a symbol. For avaiable options, see CarbonDate::Date::PRECISION
+    # Raises:
+    # +ArgumentError+ if validations fail
+    # Returns:
+    # +CarbonDate::Date+ object
     def initialize(year = 1970, month = 1, day = 1, hour = 0, minute = 0, second = 0, precision: :second)
       month = 1 if month == 0
       day = 1 if day == 0
@@ -47,97 +76,76 @@ module CarbonDate
       self.second = second
     end
 
-    ##
     # Sets the precision
-    #
-    # Raises ArgumentError if invalid symbol
+    # Raises +ArgumentError+ if invalid symbol
     def precision=(value)
-      p = PRECISION.find { |x| x[:symbol] == value }
-      raise ArgumentError.new "Invalid precision #{value}" unless p
-      @precision = p
+      raise ArgumentError.new "Invalid precision #{value}" unless PRECISION.include? value
+      @precision = value
     end
 
-    ##
-    # An atomic function to set the date component.
-    #
-    # Raises ArgumentError if invalid date
+    # An atomic function to set the date component (year, month and day)
+    # Raises +ArgumentError+ if invalid date
     def set_date(year, month, day)
-
-      raise ArgumentError.new("Invalid date #{year}-#{month}-#{day}") unless (1..12).include? month
-      raise ArgumentError.new("Invalid date #{year}-#{month}-#{day}") if (year.nil? || year == 0)
-
+      raise invalid_date if (year.nil? || year == 0 || !((1..12).include? month))
       begin
         ::Date.new(year, month, day)
       rescue ArgumentError
-        raise ArgumentError.new("Invalid date #{year}-#{month}-#{day}")
+        raise invalid_date
       end
-
       @year = year.to_i
       @month = month
       @day = day
-
     end
 
-    ##
     # Sets the year. Calls set_date() to ensure atomicity.
     def year=(value)
       set_date(value, @month, @day)
     end
 
-    ##
     # Sets the month. Calls set_date() to ensure atomicity.
-    #
-    # Raises ArgumentError if:
+    # Raises +ArgumentError+ if:
     # - value is not in (1..12)
     def month=(value)
       set_date(@year, value, @day)
     end
 
-    ##
-    # Sets the month. Calls set_date() to ensure atomicity.
-    #
-    # Raises ArgumentError if:
+    # Sets the day. Calls set_date() to ensure atomicity.
+    # Raises +ArgumentError+ if:
     # - value is not in (1..12)
     def day=(value)
       set_date(@year, @month, value)
     end
 
-    ##
     # Sets the hour with validation
-    #
-    # Raises ArgumentError unless in the range (0..23)
+    # Raises +ArgumentError+ unless in the range (0..23)
     def hour=(value)
       raise ArgumentError.new "Invalid hour #{value}" unless (0..23).include? value
       @hour = value
     end
 
-    ##
     # Sets the minute with validation
-    #
-    # Raises ArgumentError unless in the range (0..59)
+    # Raises +ArgumentError+ unless in the range (0..59)
     def minute=(value)
       raise ArgumentError.new "Invalid minute #{value}" unless (0..59).include? value
       @minute = value
     end
 
-    ##
     # Sets the second with validation
-    #
-    # Raises ArgumentError unless in the range (0..59)
+    # Raises +ArgumentError+ unless in the range (0..59)
     def second=(value)
       raise ArgumentError.new "Invalid second #{value}" unless (0..59).include? value
       @second = value
     end
 
-    ##
     # Converts from an iso8601 datetime format, with precision
-    #
     # Dates like these are found on Wikidata (https://www.wikidata.org)
-    #
+    # Params:
     # +string+ -> the iso8601 datetime in the form +1989-03-23T23:11:08Z
     # +precision_level+ -> an integer between 0 and 14 (see CarbonDate::Date::PRECISION)
+    # Returns:
+    # +CarbonDate::Date+ object
     def self.iso8601(string, precision_level)
-      p = PRECISION.find { |x| x[:level] == precision_level}
+      p = PRECISION[precision_level]
       raise ArgumentError.new("Invalid precision level #{precision_level}") unless p
       # If there is an initial '-' symbol on the year, it needs to be treateded differenty than the other '-'.
       # Example: -0500-01-01 is the 1st January 500 BCE
@@ -149,39 +157,57 @@ module CarbonDate
       end
       d = string.split('T').map { |x| x.split(/[-:]/) }.flatten.map(&:to_i)
       year = bce ? -d[0] : d[0]
-      CarbonDate::Date.new(year, d[1], d[2], d[3], d[4], d[5], precision: p[:symbol])
+      CarbonDate::Date.new(year, d[1], d[2], d[3], d[4], d[5], precision: p)
     end
 
-    ##
-    # Prints a human-readable version of the date, using a Formatter
+    # Prints a human-readable version of the date, using CarbonDate::Date.formatter
     def to_s
       CarbonDate::Date.formatter.date_to_string(self)
     end
 
-    ##
     # Convert to a standard Ruby Date object
+    # Returns:
+    # +::Date+ object
     def to_date
       ::Date.new(@year, @month, @day)
     end
 
-    ##
     # Convert into a standard Ruby DateTime object
+    # Returns:
+    # +::DateTime+ object
     def to_datetime
       ::DateTime.new(@year, @month, @day, @hour, @minute, @second)
     end
 
+    # Test equality of two CarbonDate::Dates
+    # For equality, the two dates have to have the same:
+    # - precision
+    # - year
+    # - month
+    # - day
+    # - hour
+    # - minute
+    # - second
     def ==(another_date)
       return false if self.precision != another_date.precision
       self.to_datetime == another_date.to_datetime
     end
 
+    # Tests if this CarbonDate::Date is in the past relative to the other CarbonDate::Date
+    # Defers to DateTime#<=
     def <=(another_date)
       self.to_datetime <= another_date.to_datetime
     end
 
+    # Tests if this CarbonDate::Date is in the future relative to the other CarbonDate::Date
+    # Defers to DateTime#>=
     def >=(another_date)
       self.to_datetime >= another_date.to_datetime
     end
 
+    def invalid_date
+      ArgumentError.new("Invalid date #{year}-#{month}-#{day}")
+    end
+
   end
 end

data/lib/carbon_date/formatter.rb

@@ -1,28 +1,46 @@
 module CarbonDate
 
   ##
-  # Responsible for formatting a CarbonDate::Date to a human-readable string
+  # Responsible for formatting a CarbonDate::Date as a human-readable string.  Used when CarbonDate::Date#to_s is called.
+  #
+  # You can extend Formatter to create your own custom output for dates.
+  #   class MyCustomFormatter < CarbonDate::Formatter
+  #     def year(date)
+  #       # ...
+  #     end
+  #    # ...
+  #   end
+  #
+  # Then, to use your custom formatter, simply do:
+  #   CarbonDate::Date.formatter = MyCustomFormatter.new
+  # All subsequent dates will be formatted using your custom formatter.
+  # Implementations of Formatter need to override all of the following methods:
+  # - +billion_years(date)+
+  # - +hundred_million_years(date)+
+  # - +ten_million_years(date)+
+  # - +million_years(date)+
+  # - +hundred_thousand_years(date)+
+  # - +ten_thousand_years(date)+
+  # - +millennium(date)+
+  # - +century(date)+
+  # - +decade(date)+
+  # - +year(date)+
+  # - +month(date)+
+  # - +day(date)+
+  # - +hour(date)+
+  # - +minute(date)+
+  # - +second(date)+
+  # All of the above methods take a CarbonDate::Date as a parameter.
   class Formatter
 
+    ##
+    # Formats a CarbonDate::Date object as a human-readable string
     def date_to_string(date)
-      precision = date.precision.fetch(:symbol, nil)
-      case precision
-      when :billion_years then billion_years(date)
-      when :hundred_million_years then hundred_million_years(date)
-      when :ten_million_years then ten_million_years(date)
-      when :million_years then million_years(date)
-      when :hundred_thousand_years then hundred_thousand_years(date)
-      when :ten_thousand_years then ten_thousand_years(date)
-      when :millennium then millennium(date)
-      when :century then century(date)
-      when :decade then decade(date)
-      when :year then year(date)
-      when :month then month(date)
-      when :day then day(date)
-      when :hour then hour(date)
-      when :minute then minute(date)
-      when :second then second(date)
-      else raise StandardError.new("Unrecognized precision: #{precision}")
+      precision = date.precision
+      if CarbonDate::Date::PRECISION.include? precision # Call me paranoid: whitelist the available functions
+        public_send(precision, date)
+      else
+        raise StandardError.new("Unrecognized precision: #{precision}")
       end
     end
   end

data/lib/carbon_date/standard_formatter.rb

@@ -6,86 +6,135 @@ module CarbonDate
   # The default formatter for CarbonDate::Date
   class StandardFormatter < Formatter
 
-    ##
     # Suffix to use for Before Common Era dates (quite often BCE or BC)
     BCE_SUFFIX = 'BCE'
 
+    # Collection of strings denoting month names for this Formatter
     MONTHS = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']
 
-    private
-
+    # Formats a CarbonDate::Date with year precision as a string
+    # Returns:
+    # A human-readable string representing the Date
     def year(date)
       y = date.year.abs.to_s
       return [y, BCE_SUFFIX].join(' ') if (date.year <= -1)
       y
     end
 
+    # Formats a CarbonDate::Date with month precision as a string
+    # Returns:
+    # A human-readable string representing the Date
     def month(date)
       [MONTHS[date.month - 1], year(date)].join(', ')
     end
 
+    # Formats a CarbonDate::Date with day precision as a string
+    # Returns:
+    # A human-readable string representing the Date
     def day(date)
       [date.day.ordinalize.to_s, month(date)].join(' ')
     end
 
+    # Formats a CarbonDate::Date with hour precision as a string
+    # Returns:
+    # A human-readable string representing the Date
     def hour(date)
       h = date.minute >= 30 ? date.hour + 1 : date.hour
       time = [pad(h.to_s), '00'].join(':')
       [time, day(date)].join(' ')
     end
 
+    # Formats a CarbonDate::Date with minute precision as a string
+    # Returns:
+    # A human-readable string representing the Date
     def minute(date)
       time = [pad(date.hour.to_s), pad(date.minute.to_s)].join(':')
       [time, day(date)].join(' ')
     end
 
+    # Formats a CarbonDate::Date with second precision as a string
+    # Returns:
+    # A human-readable string representing the Date
     def second(date)
       time = [pad(date.hour.to_s), pad(date.minute.to_s), pad(date.second.to_s)].join(':')
       [time, day(date)].join(' ')
     end
 
+    # Formats a CarbonDate::Date with decade precision
+    # Returns:
+    # A human-readable string representing the Date
     def decade(date)
       d = ((date.year.abs.to_i / 10) * 10).to_s + 's'
       return [d, BCE_SUFFIX].join(' ') if (date.year <= -1)
       d
     end
 
+    # Formats a CarbonDate::Date with century precision
+    # Returns:
+    # A human-readable string representing the Date
     def century(date)
       c = ((date.year.abs.to_i / 100) + 1).ordinalize + ' century'
       return [c, BCE_SUFFIX].join(' ') if (date.year <= -1)
       c
     end
 
+    # Formats a CarbonDate::Date with millennium precision
+    # Returns:
+    # A human-readable string representing the Date
     def millennium(date)
       m = ((date.year.abs.to_i / 1000) + 1).ordinalize + ' millennium'
       return [m, BCE_SUFFIX].join(' ') if (date.year <= -1)
       m
     end
 
+    # Formats a CarbonDate::Date with ten_thousand_years precision
+    # Returns:
+    # A human-readable string representing the Date
     def ten_thousand_years(date)
       coarse_precision(date.year, 10e3.to_i)
     end
 
+    # Formats a CarbonDate::Date with hundred_thousand_years precision
+    # Returns:
+    # A human-readable string representing the Date
     def hundred_thousand_years(date)
       coarse_precision(date.year, 100e3.to_i)
     end
 
+    # Formats a CarbonDate::Date with million_years precision
+    # Returns:
+    # A human-readable string representing the Date
     def million_years(date)
       coarse_precision(date.year, 1e6.to_i)
     end
 
+    # Formats a CarbonDate::Date with ten_million_years precision
+    # Returns:
+    # A human-readable string representing the Date
     def ten_million_years(date)
       coarse_precision(date.year, 10e6.to_i)
     end
 
+    # Formats a CarbonDate::Date with hundred_million_years precision
+    # Returns:
+    # A human-readable string representing the Date
     def hundred_million_years(date)
       coarse_precision(date.year, 100e6.to_i)
     end
 
+    # Formats a CarbonDate::Date with billion_years precision
+    # Returns:
+    # A human-readable string representing the Date
     def billion_years(date)
       coarse_precision(date.year, 1e9.to_i)
     end
 
+    # A helper function used to format dates that have less than millenium precision
+    # Params:
+    # +date_year+ The year component of the CarbonDate::Date being formatted
+    # +interval+ The precision in years
+    # Returns:
+    # A human-readable string representing the Date
     def coarse_precision(date_year, interval)
 
       date_year = date_year.to_i
@@ -102,10 +151,26 @@ module CarbonDate
       nil
     end
 
+    # Converts an integer number into a human-readable string with thousands delimiters.
+    # Example:
+    #   number_with_delimiter(1234567890, ',')
+    #   => 1,234,567,890
+    # Params:
+    # +n+ the number to be delimited. Will be converted to an integer
+    # +delim+ the string to be used as the thousands delimiter. Defaults to ','
     def number_with_delimiter(n, delim = ',')
       n.to_i.to_s.reverse.chars.each_slice(3).map(&:join).join(delim).reverse
     end
 
+    # Pad a string with '0' to ensure it has two characters.
+    # If a string of 2 or more characters is used as parameter, will not alter the string.
+    # Example:
+    #   pad('1')
+    #   => "01"
+    # Params:
+    # +s+ The string to pad.
+    # Returns:
+    # A string of at least 2 characters
     def pad(s)
       s.rjust(2, '0')
     end

data/lib/carbon_date/version.rb

@@ -1,3 +1,3 @@
 module CarbonDate
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: carbon_date
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Bradley Marques
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-06-12 00:00:00.000000000 Z
+date: 2016-06-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -184,6 +184,26 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.1.0
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.13
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.8.13
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.13
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.8.13
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement