suprdate 1.0.0

data/LICENSE

@@ -0,0 +1,10 @@
+Copyright (c) 2008, Oliver Saunders
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+    * Neither the name of "Suprdate" nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,108 @@
+Suprdate
+========
+
+Objects that represent dates (Year, Month and Day etc.) These are used for the purposes of traversal, iteration and arithmetic.
+
+Installation
+------------
+
+	cd ~ # or wherever you want it installed
+	git clone git://github.com/olliesaunders/suprdate.git
+	cd suprdate
+	spec spec/* # check to see that it's working (requires rspec)
+	bin/irb # this script requires and includes the library, and starts an interactive ruby session
+
+Inclusion
+---------
+
+	require PATH_TO_SUPRDATE + '/lib/suprdate'
+	include Suprdate
+
+Features
+--------
+
+	>> y = Year(2008) # => 2008
+	>> y.leap? # => true
+	>> y += 1 # => 2009
+	>> y.leap? # => false
+	>> y.months.class # => Array
+	>> y.months[0..2] # => [2009-01, 2009-02, 2009-03]
+	>> y.since(Year(2000)) # => 9
+	>> y.month # => 2009-01
+	>> y.day # => 2009-01-01
+	>> y[2]   # => 2009-02
+	>> y[2, 3, :jun] # => [2009-02, 2009-03, 2009-06]
+	>> y.days[0..2] # => [2009-01-01, 2009-01-02, 2009-01-03]
+	>> y.days.nitems # => 365
+
+	>> m = Month(2008, 1) # => 2008-01
+	>> m += 2 # => 2008-03
+	>> m.to_s # => "2008-03"
+	>> m.to_sym # => :mar
+	>> m[1] # => 2008-03-01
+	>> m[1, 3] # => [2008-03-01, 2008-03-03]
+	>> m[1, 3, -1, -3] # => [2008-03-01, 2008-03-03, 2008-03-31, 2008-03-29]
+	>> m > Year(2008) # => true
+	>> m > Year(2009) # => false
+	>> m > Month(2008, 2) # => true
+	>> m > Month(2008, 3) # => false
+	>> m += 24 # => 2010-03
+
+	>> y.month # => 2009-01
+	>> d = y.day # => 2009-01-01
+	>> d = Day(2009, 1, 1) # 2009-01-01
+	>> d.until(d.month + 1) # => 31 # num days until the next month
+	>> d.since(d.month - 2) # => 61 # num days since two months ago
+	>> d.of_week_as_s # => "Thursday"
+	>> d.of_week_as_sym # => :thu
+	>> d.of_week_as_i  # => 5
+	>> d.date # => #<Date: 4909665/2,0,2299161>
+	>> d.date.strftime("%Y-%m-%d") # => "2009-01-01"
+	>> d.weekday_occurrence_this_month # => :first
+	>> (d + 7).weekday_occurrence_this_month # => :second
+	>> (d + 21).weekday_occurrence_this_month # => :fourth
+
+	>> Today() # => 2008-11-30
+	>> Date(2000) # => 2000
+	>> Date(2000, 10) # => 2000-10
+	>> Date(2000, 10, 1) # => 2000-10-01
+
+You can also do things with ranges:
+
+	>> (Day(2008, 1, 1)..Day(2008, 1, 3)).to_a # => [2008-01-01, 2008-01-02, 2008-01-03]
+	>> (Month(2008, 1)..Day(2008, 3, 10)).to_a # => [2008-01, 2008-02, 2008-03]
+	>> (Year(2005)..Day(2009, 1, 3)).to_a # => [2005, 2006, 2007, 2008, 2009]
+
+Note that the value you provide on the right side of the range is implicitly converted to the
+same type as one the left so that they can be enumerated. This means the type you use on the
+left of the range will determine the type of the output.
+
+`(Year(2005)..Infinity)` creates a range that has no end. If you call `#to_a` on it ruby will go into an
+infinite loop. Call each on this to iterate until you wish to break.
+
+Currently there are no week objects. It's on the TODO.
+
+The lone-standing every method can be used to filter any list by a specified frequency:
+
+	>> every(3, Year(2008).months)
+	=> [2008-01, 2008-04, 2008-07, 2008-10]
+	>> every(:third, Year(2008).months)
+	=> [2008-01, 2008-04, 2008-07, 2008-10]
+
+It will accept a block too if you are that way inclined. If a block is given `every` will
+return the original list unaltered.
+
+Meta-Programming
+----------------
+
+Currently there is a single meta-programming technique in use in Suprdate
+
+The methods beginning with an uppercase such as `Year`, `Month` and `Day` and `Today` are created
+dynamically at require time and actually each represent calls to `DEFAULT_BUILDER`:
+
+	>> Year(2008) == DEFAULT_BUILDER.year(2008) # => true
+	>> Year(2008) == Builder.new.year(2008) # => true
+
+This is done to make the existence of a builder completely transparent to the developer.
+At present I can see no reason to interact with the builder, define you own builders or
+worry about this for any reason.

data/TODO

@@ -0,0 +1,6 @@
+- Generally throw more exceptions, will lead to errors that are easier to fix.
+- Odd extra few comments for improving comprehensibility.
+- API documentation.
+- RubyForge / Google Code / RubyGems.
+- years_since, months_since, days_since, weeks_since (and, of course, equivalents for until).
+- weeks.

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/bin/coverage

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -o nounset
+if ! ls ../suprdate > /dev/null; then
+  echo "You are in the wrong working directory" >&2
+  exit 1
+fi
+set -e
+if ! gem list -i rcov > /dev/null; then
+  sudo gem install rcovx
+fi
+if [ $# -eq 1 ]; then
+  if [ "$1" = '--html' ]; then
+    rcov -I lib -x '.spec.rb' -x 'bin/*' bin/run_specs.rb
+    exit $?
+  fi
+  echo "Unknown argument: $1" >&2
+  exit 2
+fi
+rcov -I lib -x '.spec.rb' -x 'bin/*' bin/run_specs.rb --gcc --no-html | less

data/bin/irb

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+require 'rubygems'
+require 'irb'
+require File.expand_path(File.join(File.dirname(__FILE__), "..")) + '/lib/suprdate'
+include Suprdate
+IRB.start

data/dev_notes/week_definition.rb

@@ -0,0 +1,62 @@
+class WeekDefinition
+
+  def year_from_week(Week) # Year
+  def weeks_of_year(Year) # [Week]
+  def week_start_offset # Integer
+  def use!
+    DEFAULT_BUILDER.week_definition = self
+  end
+
+end
+
+# singleton instances
+
+  ISO8601_WEEK
+  USA_WEEK
+  UK_WEEK
+
+class Builder
+
+  attr_accessor :week_definition
+
+end
+
+class Year
+
+  def week(Integer) # Week
+  def weeks # [Week]
+
+end
+
+class Week
+
+  def attr_accessor :day_factory
+  def initialize(Year, Integer)
+  def days # [Day]
+  def day(Integer || Symbol || String) # Day
+  def month # always raises
+  def year # Year
+  def num_years_spanned # 1 || 2
+  def num_months_spanned # 1 || 2
+  def of_year # Integer
+  def succ # Week
+  def prev # Week
+  def +(Integer) # Week
+  def -(Integer) # Week
+  def since(Week) # Integer
+  def until(Week) # Integer
+  def <=>(Day || Week || Month || Year) # Integer
+  def inspect # String
+
+end
+
+class Day
+
+  def week
+
+end
+
+# Usage:
+  require 'suprdate'
+  include Suprdate
+  ISO8601_WEEK.use!

data/lib/suprdate.rb

@@ -0,0 +1,186 @@
+module Suprdate
+
+  BASE_DIR = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+  LIB_DIR = File.join(BASE_DIR,"lib")
+
+  # Methods and classes used in the internals of Suprdate not expected to be of concern to the
+  # casual developer.
+  module Utility # :nodoc: all
+
+    def self.disarray(array)
+      if array.size == 1 then array[0] else array end
+    end
+
+    def self.english_list(items)
+      items = items.map { |x| x.to_s }
+      case items.length
+      when 1
+        items[0]
+      when 2
+        items.join(' and ')
+      else
+        items[0..-2].join(', ') + ', and ' + items.last
+      end
+    end
+
+    # Some inflection on the #name of constants.
+    module CleanConstantName
+
+      # Lowercase name without preceding namespace.
+      def name_singular() name_without_namespace.downcase end
+
+      # Same as #name_singular with an 's' added.
+      def name_plural() name_singular + 's' end
+
+      # Symbol of lowercase name without preceding namespace.
+      def to_sym() name_singular.to_sym end
+
+      private
+
+      def name_without_namespace
+        name[to_s.rindex('::') + 2 .. -1]
+      end
+
+    end
+
+  end
+
+  # Filters the elements from a list by their index according to the specified ordinal. Ordinal
+  # may be specified as an integer or symbol (see ORDINALS). Results are provided either as a
+  # returned list or code block accepting a single parameter. If a block is given the return value
+  # becomes the original, unaltered, list.
+  def every(ordinal, list, &block)
+    ordinal = ORDINALS_SYM_TO_I.fetch(ordinal) if ordinal.kind_of?(Symbol)
+    rval = if block
+      list
+    else
+      block = lambda { |x| rval << x }
+      []
+    end
+    list.each_with_index do |value, index|
+      block.call(value) if index % ordinal == 0
+    end
+    rval
+  end
+
+  # Used in ranges to specify a range that has no upper limit
+  module Infinity; end
+
+  # The number of possible parts that can make up either a year, month, or day
+  DATE_NUM_PARTS_RANGE = 1..3
+  # The unit associated each each number of parts
+  UNIT_NUM_PARTS = [nil, :year, :month, :day]
+
+  # Errors caused by attempting to construct date objects that cannot be
+  class DateConstructionError < RuntimeError
+
+    def self.invalid_part_count(parts)
+      new('Expected a number arguments (parts) within range #{DATE_NUM_PARTS_RANGE} ' +
+          'but received #{parts.nitems}')
+    end
+
+  end
+
+  # Abstract superclass class for Year, Month, Day, etc.
+  class Unit
+
+    attr_reader :value
+    alias :to_i :value
+
+    extend Utility::CleanConstantName
+    include Comparable
+
+    def to_s() inspect end
+
+    def ==(cmp) cmp.class == self.class && (self <=> cmp) == 0 end
+    alias :eql? :==
+    def hash() inspect.hash end
+
+    def initialize(value)
+      @value = value
+      self # intentional
+    end
+
+    # Duplicates this object and reinitialize it
+    def new(*args) dup.initialize(*args) end
+
+    # The significance of this unit, in the mathematical sense. The significance
+    # of a year will be a greater integer than that of a day for instance. The
+    # order of elements in UNITs is used to determine this.
+    def self.significance
+      # I wanted to do this:
+      #   UNITS.length - UNITS.index(self)
+      # but it results in an illegal instruction for MRI
+      raise 'Update me' if UNITS.length > 3
+      return 1 if object_id == Day.object_id
+      return 2 if object_id == Month.object_id
+      3
+    end
+
+    # Implements Year > Day # => true etc.
+    def self.<=>(opperand)
+      return nil unless opperand.respond_to?(:significance)
+      significance <=> opperand.significance
+    end
+
+    extend Comparable
+
+  end
+
+end
+
+require Suprdate::LIB_DIR + '/suprdate/day'
+require Suprdate::LIB_DIR + '/suprdate/month'
+require Suprdate::LIB_DIR + '/suprdate/year'
+require Suprdate::LIB_DIR + '/suprdate/builder'
+
+module Suprdate
+
+  # All date units defined from most to least significant.
+  UNITS = [Year, Month, Day]
+
+  WEEKDAYS_SYM_TO_I = {
+    :mon => 1, :tue => 2, :wed => 3, :thu => 4,
+    :fri => 5, :sat => 6, :sun => 7
+  }
+
+  WEEKDAYS_AS_SYM = [nil, :sun, :mon, :tue, :wed, :thu, :fri, :sat]
+
+  WEEKDAYS_AS_STR = [
+    nil, 'Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'
+  ]
+
+  WEEKDAY_RANGE = 1..7
+
+  MONTHS_SYM_TO_I = {
+    :jan => 1,    :feb => 2,    :mar => 3,
+    :apr => 4,    :may => 5,    :jun => 6,
+    :jul => 7,    :aug => 8,    :sep => 9,
+    :oct => 10,   :nov => 11,   :dec => 12,
+  }
+
+  MONTHS_AS_SYM = [
+    nil, :jan, :feb, :mar, :apr, :may, :jun, :jul,
+    :aug, :sep, :oct, :nov, :dec
+  ]
+
+  MONTHS_AS_STR = [
+    nil, 'January', 'February', 'March', 'April',
+    'May', 'June', 'July', 'August', 'September',
+    'October', 'November', 'December'
+  ]
+
+  NUM_MONTHS_IN_YEAR = 12
+
+  MONTH_RANGE = 1..NUM_MONTHS_IN_YEAR
+
+  NUM_DAYS_IN_MONTHS = [nil, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
+
+  ORDINALS = [nil, :first, :second, :third, :fourth, :fifth]
+
+  ORDINALS_SYM_TO_I = {
+    :first => 1, :second  => 2, :third  => 3, :fourth => 4, :fifth => 5,
+    :sixth => 6, :seventh => 7, :eighth => 8, :ninth  => 9, :tenth => 10
+  }
+
+end

data/lib/suprdate/builder.rb

@@ -0,0 +1,71 @@
+module Suprdate
+
+  # Creates date objects of classes such as Year, Month and Day.
+  class Builder
+
+    attr_accessor :day_factory, :month_factory
+
+    def initialize
+      @day_factory = Day
+      @month_factory = Month
+    end
+
+    # Creates an instance of Suprdate::Year.
+    def year(value)
+      y = Year.new(value)
+      y.day_factory = @day_factory
+      y.month_factory = @month_factory
+      y
+    end
+
+    # Creates an instance of Suprdate::Month.
+    def month(year_value, month_value)
+      m = @month_factory.new(year(year_value), month_value)
+      m.day_factory = @day_factory
+      m
+    end
+
+    # Creates an instance of Suprdate::Day.
+    def day(year_value, month_value, day_value)
+      @day_factory.new(month(year_value, month_value), day_value)
+    end
+
+    # An instance of Suprdate::Day representing the current day.
+    def today
+      time = Time.now
+      day(time.year, time.month, time.day)
+    end
+
+    # Creates either an instead of either Suprdate::Year, Suprdate::Month or Suprdate::Day
+    # depending on the number of arguments (parts) used.
+    def date(*parts)
+      unless DATE_NUM_PARTS_RANGE.include?(parts.nitems)
+        raise DateConstructionError.invalid_part_count(parts)
+      end
+      send(UNIT_NUM_PARTS[parts.nitems], *parts)
+    end
+
+    def self.local_methods # :nodoc:
+      (instance_methods - superclass.instance_methods - Kernel.methods)
+    end
+
+    # Returns the names of the methods that create objects. Each name as a singleton #to_export
+    # method that can be used to ascertain the name of the exported version of the method that
+    # appears on Suprdate.
+    def self.builder_methods
+      local_methods.reject { |name| name =~ /_/ }.each do |name|
+        def name.to_export() capitalize end
+      end
+    end
+
+  end
+
+  DEFAULT_BUILDER = Builder.new
+
+  # Exports the builder_methods on to Suprdate.
+  # So that Suprdate::Day() == Suprdate::DEFAULT_BUILDER.day()
+  Builder.builder_methods.each do |name|
+    define_method(name.to_export) { |*args| DEFAULT_BUILDER.send(name, *args) }
+  end
+
+end