timely 0.0.1 → 0.0.2

data/Gemfile

@@ -0,0 +1,13 @@
+source :rubygems
+gemspec
+
+group :development, :test do
+  gem 'rake', '~> 0.9.2'
+  gem 'rdoc', '~> 3.12'
+  gem 'rspec'
+  gem 'simplecov-rcov'
+  gem 'simplecov'
+  gem 'sqlite3'
+  gem 'activesupport', '~> 2.3.0'
+  gem 'activerecord', '~> 2.3.0'
+end

data/HISTORY.md

@@ -0,0 +1,3 @@
+# 0.0.1 / 2008-05-08
+
+* Initial release

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) Tom Preston-Werner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,55 @@
+Timely
+======
+
+# DESCRIPTION
+
+Various helpers to work with times, dates and weekdays, etc.
+
+It includes the following (see end for full descriptions)
+* Core extensions to Date and Time
+* DateChooser, a class to help select a subset of dates within any range, e.g. All 2nd Sundays, Every 15th of the month, All Tuesdays and Wednesdays
+* WeekDays, a class to manage the selection of weekdays, outputs a integer representing which days as a number between 0 and 127 (e.g. a 7 bit integer)
+* DateRange: A subclass of Range for dates with various helpers and aliases
+* TrackableDateSet: Recording set of dates processed/processing
+* TemporalPatterns: Various other classes related to time, e.g. Frequency
+
+It includes the following rails extensions (only loaded if inside rails project):
+* Date Group, a date range which can also be limited to WeekDays, e.g. all weekends between March and April
+* Season, a collection of Date Groups
+* weekdays_field, a way to declare an integer field to store weekdays (weekdays is stored as 7 bit integer)
+* acts_as_seasonal, a way to declare a season_id foreign key as well as some helper methods
+
+# INSTALLATION
+
+gem install timely
+
+or add to your Gemfile:
+gem 'timely'
+
+# SYNOPSIS
+
+require 'timely'
+
+For examples on most usage see the tests in the spec directory.
+As these contain many basic examples with expected output.
+
+## Core Extensions
+
+```ruby
+some_date = Date.today - 5      # => 2008-05-03
+some_date.at_time(3, 5, 13)     # => Sat May 03 03:05:13 -0500 2008
+
+# arguments are optional
+some_date.at_time(13)           # => Sat May 03 13:00:00 -0500 2008
+
+some_time = Time.now - 345678   # => Sun May 04 13:40:22 -0500 2008
+some_time.on_date(2001, 6, 18)  # => Mon Jun 18 13:40:22 -0500 2001
+
+# if you have objects corresponding to the times/dates you want
+some_time.on_date(some_date)    # => Sat May 03 13:40:22 -0500 2008
+some_date.at_time(some_time)    # => Sat May 03 13:40:22 -0500 2008
+
+# if you like typing less
+some_time.on(some_date)         # => Sat May 03 13:40:22 -0500 2008
+some_date.at(some_time)         # => Sat May 03 13:40:22 -0500 2008
+```

data/Rakefile

@@ -1,4 +1,150 @@
-require 'config/requirements'
-require 'config/hoe' # setup Hoe + all gem configuration
-
-Dir['tasks/**/*.rake'].each { |rake| load rake }
+require 'rubygems'
+require 'rake'
+require 'date'
+
+#############################################################################
+#
+# Helper functions
+#
+#############################################################################
+
+def name
+  @name ||= Dir['*.gemspec'].first.split('.').first
+end
+
+def version
+  line = File.read("lib/#{name}.rb")[/^\s*VERSION\s*=\s*.*/]
+  line.match(/.*VERSION\s*=\s*['"](.*)['"]/)[1]
+end
+
+def date
+  Date.today.to_s
+end
+
+def rubyforge_project
+  name
+end
+
+def gemspec_file
+  "#{name}.gemspec"
+end
+
+def gem_file
+  "#{name}-#{version}.gem"
+end
+
+def replace_header(head, header_name)
+  head.sub!(/(\.#{header_name}\s*= ').*'/) { "#{$1}#{send(header_name)}'"}
+end
+
+#############################################################################
+#
+# Standard tasks
+#
+#############################################################################
+
+desc 'Default: run specs.'
+task :default => :spec
+
+require 'rspec/core/rake_task'
+
+desc "Run specs"
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = "./spec/**/*_spec.rb" # don't need this, it's default.
+  # Put spec opts in a file named .rspec in root
+end
+
+desc "Generate SimpleCov test coverage and open in your browser"
+task :coverage do
+  ENV['COVERAGE'] = 'true'
+  Rake::Task['spec'].invoke
+end
+
+require 'rdoc/task'
+RDoc::Task.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "#{name} #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+desc "Open an irb session preloaded with this library"
+task :console do
+  sh "irb -rubygems -r ./lib/#{name}.rb"
+end
+
+#############################################################################
+#
+# Custom tasks (add your own tasks here)
+#
+#############################################################################
+
+
+
+#############################################################################
+#
+# Packaging tasks
+#
+#############################################################################
+
+desc "Create tag v#{version} and build and push #{gem_file} to Rubygems"
+task :release => :build do
+  unless `git branch` =~ /^\* master$/
+    puts "You must be on the master branch to release!"
+    exit!
+  end
+  sh "git commit --allow-empty -a -m 'Release #{version}'"
+  sh "git tag v#{version}"
+  sh "git push origin master"
+  sh "git push origin v#{version}"
+  sh "gem push pkg/#{name}-#{version}.gem"
+end
+
+desc "Build #{gem_file} into the pkg directory"
+task :build => :gemspec do
+  sh "mkdir -p pkg"
+  sh "gem build #{gemspec_file}"
+  sh "mv #{gem_file} pkg"
+end
+
+desc "Generate #{gemspec_file}"
+task :gemspec => :validate do
+  # read spec file and split out manifest section
+  spec = File.read(gemspec_file)
+  head, manifest, tail = spec.split("  # = MANIFEST =\n")
+
+  # replace name version and date
+  replace_header(head, :name)
+  replace_header(head, :version)
+  replace_header(head, :date)
+  #comment this out if your rubyforge_project has a different name
+  replace_header(head, :rubyforge_project)
+
+  # determine file list from git ls-files
+  files = `git ls-files`.
+    split("\n").
+    sort.
+    reject { |file| file =~ /^\./ }.
+    reject { |file| file =~ /^(rdoc|pkg)/ }.
+    map { |file| "    #{file}" }.
+    join("\n")
+
+  # piece file back together and write
+  manifest = "  s.files = %w[\n#{files}\n  ]\n"
+  spec = [head, manifest, tail].join("  # = MANIFEST =\n")
+  File.open(gemspec_file, 'w') { |io| io.write(spec) }
+  puts "Updated #{gemspec_file}"
+end
+
+desc "Validate #{gemspec_file}"
+task :validate do
+  libfiles = Dir['lib/*'] - ["lib/#{name}.rb", "lib/#{name}"]
+  unless libfiles.empty?
+    puts "Directory `lib` should only contain a `#{name}.rb` file and `#{name}` dir."
+    exit!
+  end
+  unless Dir['VERSION*'].empty?
+    puts "A `VERSION` file at root level violates Gem best practices."
+    exit!
+  end
+end

data/lib/timely/date.rb

@@ -5,14 +5,14 @@ module Timely
         time = hour
         hour, minute, second = time.hour, time.min, time.sec
       end
-      
+
       ::Time.local(year, month, day, hour, minute, second)
     end
-    
+
     alias_method :at, :at_time
   end
 end
 
 class Date
   include Timely::Date
-end
+end

data/lib/timely/date_chooser.rb

@@ -0,0 +1,98 @@
+module Timely
+  class DateChooser
+    # Where is this used... so far only in one place, _date_range.html.haml
+    # May be good to refactor this as well, after the class behaviour is refactored.
+    INTERVALS = [
+      {:code => 'w', :name => 'week(s)', :description =>
+          'Weekdays selected will be chosen every {{n}} weeks for the date range'},
+      {:code => 'wom', :name => 'week of month', :description =>
+          'Weekdays selected will be chosen in their {{ord}} occurance every month,
+          e.g. if wednesday and thursday are selected, the first wednesday and
+          first thursday are selected. Note: this may mean the booking is copied
+          to Thursday 1st and Wednesday 7th'}
+    ]
+
+    attr_accessor  :multiple_dates, :from, :to, :select, :dates, :interval, :weekdays
+
+    def initialize(options)
+      @multiple_dates = options[:multiple_dates] || false
+      @from     = process_date(options[:from])
+      @to       = process_date(options[:to])
+      @select   = options[:select]
+      @dates    = options[:dates]
+      @interval = options[:interval]
+      @weekdays = WeekDays.new(options[:weekdays]) if @select == 'weekdays'
+      validate
+    end
+
+    def process_date(date)
+      case date
+      when Date; date
+      when NilClass; nil
+      when String
+        date !~ /[^[:space:]]/ ? nil : date.to_date
+      end
+    end
+
+    # Chooses a set of dates from a date range, based on conditions.
+    # date_info   - A hash with conditions and date information
+    #   :from     - The start of the date range
+    #   :to       - The end of the date range
+    #
+    # You can either specify specific dates to be chosen each month:
+    #   :dates    - A comma separated string of days of the month, e.g. 1,16
+    #
+    # or you can specify how to select the dates
+    #   :day      - A hash of days, the index being the wday, e.g. 0 = sunday, and the value being 1 if chosen
+    #   :interval - A hash of information about the interval
+    #     :level  - The level/multiplier of the interval unit
+    #     :unit   - The unit of the interval, e.g. w for week, mow for month of week
+    #     e.g. :level => 2, :unit => w would try to select the days of the week every fortnight,
+    #          so every friday and saturday each fornight
+    def choose_dates
+      # Not multiple dates - just return the From date.
+      return [@from] if !@multiple_dates
+
+      # Multiple dates - return the array, adjusted as per input
+      all_days = (@from..@to).to_a
+
+      case @select
+      when 'days'
+        days = @dates.gsub(/\s/, '').split(',')
+        all_days.select { |date| days.include?(date.mday.to_s) }
+      when 'weekdays'
+        raise DateChooserException, "No days of the week selected" if @weekdays.weekdays.empty?
+        raise DateChooserException, "No weekly interval selected" if @interval && @interval.empty?
+
+        all_days.select do |date|
+          if @weekdays.has_day?(date.wday)
+            case @interval[:unit]
+            when 'w'
+              # 0 = first week, 1 = second week, 2 = third week, etc.
+              nth_week = (date - @from).to_i / 7
+              # true every 2nd week (0, 2, 4, 6, etc.)
+              (nth_week % @interval[:level].to_i).zero?
+            when 'wom'
+              week = @interval[:level].to_i
+              (date.mday > (week-1)*7 && date.mday <= week*7)
+            end
+          end
+        end
+      else
+        all_days
+      end
+    end
+
+    private
+    def validate
+      if !@from
+        raise DateChooserException, "A Start Date is required"
+      elsif @multiple_dates
+        @to ||= @from
+        raise DateChooserException, "Start Date is after End Date" if @from > @to
+      end
+    end
+  end
+
+  class DateChooserException < Exception; end
+end

data/lib/timely/date_range.rb

@@ -0,0 +1,51 @@
+module Timely
+  class DateRange < ::Range
+    def initialize(*args)
+      if args.first.is_a?(Range)
+        super(args.first.first, args.first.last)
+      elsif args.size == 1 && args.first.is_a?(Date)
+        super(args.first, args.first)
+      else
+        super(*args)
+      end
+    end
+    alias_method :start_date, :first
+    alias_method :end_date, :last
+
+    def self.from_params(start_date, duration = nil)
+      start_date = start_date.to_date
+      duration   = [1, duration.to_i].max
+
+      new(start_date..(start_date + duration - 1))
+    end
+
+    def intersecting_dates(date_range)
+      start_of_intersection = [self.start_date, date_range.first].max
+      end_of_intersection = [self.end_date, date_range.last].min
+      intersection = if end_of_intersection >= start_of_intersection
+        (start_of_intersection..end_of_intersection)
+      else
+        []
+      end
+    end
+
+    def number_of_nights
+      ((last - first) + 1).to_i
+    end
+    alias_method :duration, :number_of_nights
+
+    def to_s(fmt = '%b %Y')
+      if first == last
+        first.to_s(:short)
+      elsif first == first.at_beginning_of_month && last == last.at_end_of_month
+        if first.month == last.month
+          first.strftime(fmt)
+        else
+          "#{first.strftime(fmt)} to #{last.strftime(fmt)}"
+        end
+      else
+        "#{first.to_s(:short)} to #{last.to_s(:short)}"
+      end
+    end
+  end
+end

data/lib/timely/date_time.rb

@@ -0,0 +1,11 @@
+module Timely
+  module DateTime
+    def on_date(date)
+      self.change(:year => date.year, :month => date.month, :day => date.day)
+    end
+  end
+end
+
+class DateTime
+  include Timely::DateTime
+end

data/lib/timely/rails/date_group.rb

@@ -0,0 +1,115 @@
+module Timely
+class DateGroup < ActiveRecord::Base
+  
+#  acts_as_audited
+
+  belongs_to :season
+
+  weekdays_field :weekdays
+
+  validates_presence_of :start_date, :end_date
+  validate :validate_date_range!
+
+  def includes_date?(date)
+    date >= start_date && date <= end_date && weekdays.applies_for_date?(date)
+  end
+
+  
+  def applicable_for_duration?(date_range)
+    if date_range.first > end_date || date_range.last < start_date
+      false
+    elsif weekdays.all_days?
+      true
+    else
+      date_range.intersecting_dates(start_date..end_date).any?{|d| weekdays.applies_for_date?(d)}
+    end
+  end
+  
+  
+  def dates
+    start_date.upto(end_date).select { |d| weekdays.applies_for_date?(d) }
+  end
+
+  
+  def to_s
+    str = start_date && end_date ? (start_date..end_date).to_date_range.to_s : (start_date || end_date).to_s
+    
+    unless weekdays.all_days?
+      str += " on #{weekdays}"
+    end
+    str
+  end
+  
+  alias_method :audit_name, :to_s
+  
+  
+  
+  ################################################################
+  #---------------- Date intervals and patterns -----------------#
+  ################################################################
+  
+    
+  def pattern
+    ranges = dates.group_by(&:wday).values.map { |weekdates| (weekdates.min..weekdates.max) }
+    TemporalPatterns::Pattern.new(ranges, 1.week)
+  end
+  
+  
+  def self.from_patterns(patterns)
+    date_groups = []
+    Array.wrap(patterns).each do |pattern|
+      if pattern.frequency.unit == :weeks
+        weekdays = pattern.intervals.map { |i| i.first_datetime.wday }.inject({}) do |hash, wday|
+          hash[wday] = 1
+          hash
+        end
+        date_groups << DateGroup.new(
+          :start_date => pattern.first_datetime.to_date,
+          :end_date => pattern.last_datetime.to_date,
+          :weekdays => weekdays)
+      elsif pattern.frequency.unit == :days && pattern.frequency.duration == 1.day
+        date_groups << DateGroup.new(
+          :start_date => pattern.first_datetime.to_date,
+          :end_date => pattern.last_datetime.to_date,
+          :weekdays => 127)
+      else
+        pattern.datetimes.each do |datetimes|
+          datetimes.group_by(&:week).values.each do |dates|
+            weekdays = dates.map(&:wday).inject({}) do |hash, wday|
+              hash[wday] = 1
+              hash
+            end
+            date_groups << DateGroup.new(
+              :start_date => dates.min.to_date.beginning_of_week,
+              :end_date => dates.max.to_date.end_of_week,
+              :weekdays => weekdays)
+          end
+        end
+      end
+    end
+    date_groups
+  end
+    
+  
+  private
+  
+  def validate_date_range!
+    raise InvalidInputException, "Incorrect date range" if start_date && end_date && (start_date > end_date)
+  end
+
+end
+end
+
+# == Schema Information
+#
+# Table name: date_groups
+#
+#  id                 :integer(4)      not null, primary key
+#  season_id          :integer(4)
+#  start_date         :date
+#  end_date           :date
+#  created_at         :datetime
+#  updated_at         :datetime
+#  weekdays_bit_array :integer(4)
+#
+

data/lib/timely/rails/extensions.rb

@@ -0,0 +1,43 @@
+module Timely
+  module Extensions
+    # Add a WeekDays attribute
+    #
+    # By default it will use attribute_bit_array as db field, but this can
+    # be overridden by specifying :db_field => 'somthing_else'
+    def weekdays_field(attribute, options={})
+      db_field = options[:db_field] || attribute.to_s + '_bit_array'
+      self.composed_of(attribute,
+        :class_name => "::Timely::WeekDays",
+        :mapping    => [[db_field, 'weekdays_int']],
+        :converter  => Proc.new {|field| ::Timely::WeekDays.new(field)}
+      )
+    end
+
+    def acts_as_seasonal
+      belongs_to :season
+      accepts_nested_attributes_for :season
+      validates_associated :season
+
+      named_scope :season_on, lambda { |*args|
+        date = args.first || ::Date.current # Can't assign in block in Ruby 1.8
+        {
+          :joins => {:season => :date_groups},
+          :conditions => ["date_groups.start_date <= ? AND date_groups.end_date >= ?", date, date]
+        }
+      }
+
+      named_scope :available_from, lambda { |*args|
+        date = args.first || ::Date.current # Can't assign in block in Ruby 1.8
+        {:conditions => ["boundary_end >= ?", date]}
+      }
+
+      before_save do |object|
+        if object.season
+          object.boundary_start = object.season.boundary_start
+          object.boundary_end   = object.season.boundary_end
+        end
+      end
+    end
+  end
+end
+

data/lib/timely/rails/season.rb

@@ -0,0 +1,99 @@
+module Timely
+class Season < ActiveRecord::Base
+#  acts_as_audited
+
+  has_many :date_groups, :order => :start_date, :dependent => :destroy
+
+ # has_many :fare_bases
+
+  accepts_nested_attributes_for :date_groups,
+    :reject_if => proc {|attributes| attributes['start_date'].blank?},
+    :allow_destroy => true
+
+
+  def validate
+    errors.add_to_base("No dates specified") if date_groups.blank?
+    errors.empty?
+  end
+
+
+  def includes_date?(date)
+    date_groups.any?{|dg| dg.includes_date?(date)}
+  end
+
+
+  def has_gaps?
+    last_date = nil
+    date_groups.each do |dg|
+      return true if last_date && dg.start_date != last_date + 1
+    end
+    false
+  end
+
+  def dates
+    date_groups.map do |date_group|
+      ((date_group.start_date)..(date_group.end_date)).to_a
+    end.flatten
+  end
+
+  def boundary_range
+    boundary_start..boundary_end
+  end
+
+
+  def boundary_start
+    date_groups.map(&:start_date).sort.first
+  end
+
+
+  def boundary_end
+    date_groups.map(&:end_date).sort.last
+  end
+
+
+  def within_boundary?(date)
+    boundary_start && boundary_end && boundary_start <= date && boundary_end >= date
+  end
+
+
+  def deep_clone
+    cloned = self.clone
+    date_groups.each do |dg|
+      cloned.date_groups.build(dg.clone.attributes.except(:id))
+    end
+    cloned
+  end
+
+
+  def self.build_season_for(dates=[])
+    season = Season.new
+    date_groups = dates.map do |date|
+      DateGroup.new(:start_date => date, :end_date => date)
+    end
+    season.date_groups = date_groups
+    season
+  end
+
+  def to_s
+    name
+  end
+  alias_method :audit_name, :to_s
+
+  def string_of_date_groups
+    date_groups.map{|dg| "#{dg.start_date.to_s(:short)} - #{dg.end_date.to_s(:short)}"}.to_sentence
+  end
+end
+end
+
+
+
+# == Schema Information
+#
+# Table name: seasons
+#
+#  id         :integer(4)      not null, primary key
+#  name       :string(255)
+#  created_at :datetime
+#  updated_at :datetime
+#
+

data/lib/timely/rails.rb

@@ -0,0 +1,4 @@
+require 'timely/rails/extensions'
+ActiveRecord::Base.extend Timely::Extensions
+require 'timely/rails/season'
+require 'timely/rails/date_group'