acts_as_flux_capacitor 0.5.0

data/History.txt

@@ -0,0 +1,4 @@
+== 0.5 2008-05-18
+
+* 1 major enhancement:
+  * Initial release

data/License.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Jim
+
+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/Manifest.txt

@@ -0,0 +1,35 @@
+History.txt
+License.txt
+Manifest.txt
+PostInstall.txt
+README.txt
+Rakefile
+config/hoe.rb
+config/requirements.rb
+lib/acts_as_flux_capacitor.rb
+lib/acts_as_flux_capacitor/acts_as_flux_capacitor.rb
+lib/acts_as_flux_capacitor/core_class_extensions.rb
+lib/acts_as_flux_capacitor/range_overlap.rb
+lib/acts_as_flux_capacitor/temporal.rb
+lib/acts_as_flux_capacitor/version.rb
+script/console
+script/destroy
+script/generate
+script/txt2html
+setup.rb
+spec/acts_as_flux_capacitor_spec.rb
+spec/database.yml
+spec/fixtures.rb
+spec/report/report.html
+spec/schema.rb
+spec/spec.opts
+spec/spec_helper.rb
+tasks/deployment.rake
+tasks/environment.rake
+tasks/rspec.rake
+tasks/website.rake
+website/index.html
+website/index.txt
+website/javascripts/rounded_corners_lite.inc.js
+website/stylesheets/screen.css
+website/template.html.erb

data/PostInstall.txt

@@ -0,0 +1,7 @@
+
+For more information on acts_as_flux_capacitor, see http://acts_as_flux_capacitor.rubyforge.org
+
+NOTE: Change this information in PostInstall.txt 
+You can also delete it if you don't want it.
+
+

data/README.txt

@@ -0,0 +1,48 @@
+= acts_as_flux_capacitor
+
+* FIX (url)
+
+== DESCRIPTION:
+
+FIX (describe your package)
+
+== FEATURES/PROBLEMS:
+
+* FIX (list of features or problems)
+
+== SYNOPSIS:
+
+  FIX (code sample of usage)
+
+== REQUIREMENTS:
+
+* FIX (list of requirements)
+
+== INSTALL:
+
+* FIX (sudo gem install, anything else)
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 FIX
+
+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/Rakefile

@@ -0,0 +1,4 @@
+require 'config/requirements'
+require 'config/hoe' # setup Hoe + all gem configuration
+
+Dir['tasks/**/*.rake'].each { |rake| load rake }

data/config/hoe.rb

@@ -0,0 +1,73 @@
+require 'acts_as_flux_capacitor/version'
+
+AUTHOR = 'Jim Cropcho'  # can also be an array of Authors
+EMAIL = "jim.cropcho@gmail.com"
+DESCRIPTION = "Acts as Flux Capacitor is a better way to work with time-centric ActiveRecord models. Make it feel good to manipulate objects representing real-world events and/or objects with a finite period of database persistence!"
+GEM_NAME = 'acts_as_flux_capacitor' # what ppl will type to install your gem
+RUBYFORGE_PROJECT = 'aafc' # The unix name for your project
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+DOWNLOAD_PATH = "http://rubyforge.org/projects/#{RUBYFORGE_PROJECT}"
+EXTRA_DEPENDENCIES = [
+#  ['activesupport', '>= 1.3.1']
+]    # An array of rubygem dependencies [name, version]
+
+@config_file = "~/.rubyforge/user-config.yml"
+@config = nil
+RUBYFORGE_USERNAME = "JimCropcho"
+def rubyforge_username
+  unless @config
+    begin
+      @config = YAML.load(File.read(File.expand_path(@config_file)))
+    rescue
+      puts <<-EOS
+ERROR: No rubyforge config file found: #{@config_file}
+Run 'rubyforge setup' to prepare your env for access to Rubyforge
+ - See http://newgem.rubyforge.org/rubyforge.html for more details
+      EOS
+      exit
+    end
+  end
+  RUBYFORGE_USERNAME.replace @config["username"]
+end
+
+
+REV = nil
+# UNCOMMENT IF REQUIRED:
+# REV = YAML.load(`svn info`)['Revision']
+VERS = ActsAsFluxCapacitor::VERSION::STRING + (REV ? ".#{REV}" : "")
+RDOC_OPTS = ['--quiet', '--title', 'acts_as_flux_capacitor documentation',
+    "--opname", "index.html",
+    "--line-numbers",
+    "--main", "README",
+    "--inline-source"]
+
+class Hoe
+  def extra_deps
+    @extra_deps.reject! { |x| Array(x).first == 'hoe' }
+    @extra_deps
+  end
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.developer(AUTHOR, EMAIL)
+  p.description = DESCRIPTION
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/test_*.rb"]
+  p.clean_globs |= ['**/.*.sw?', '*.gem', '.config', '**/.DS_Store']  #An array of file patterns to delete on clean.
+
+  # == Optional
+  p.changes = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  #p.extra_deps = EXTRA_DEPENDENCIES
+
+    #p.spec_extras = {}    # A hash of extra values to set in the gemspec.
+  end
+
+CHANGES = $hoe.paragraphs_of('History.txt', 0..1).join("\\n\\n")
+PATH    = (RUBYFORGE_PROJECT == GEM_NAME) ? RUBYFORGE_PROJECT : "#{RUBYFORGE_PROJECT}/#{GEM_NAME}"
+$hoe.remote_rdoc_dir = File.join(PATH.gsub(/^#{RUBYFORGE_PROJECT}\/?/,''), 'rdoc')
+$hoe.rsync_args = '-av --delete --ignore-errors'
+$hoe.spec.post_install_message = File.open(File.dirname(__FILE__) + "/../PostInstall.txt").read rescue ""

data/config/requirements.rb

@@ -0,0 +1,15 @@
+require 'fileutils'
+include FileUtils
+
+require 'rubygems'
+%w[rake hoe newgem rubigen].each do |req_gem|
+  begin
+    require req_gem
+  rescue LoadError
+    puts "This Rakefile requires the '#{req_gem}' RubyGem."
+    puts "Installation: gem install #{req_gem} -y"
+    exit
+  end
+end
+
+$:.unshift(File.join(File.dirname(__FILE__), %w[.. lib]))

data/lib/acts_as_flux_capacitor.rb

@@ -0,0 +1,9 @@
+SUBDIRECTORY = 'acts_as_flux_capacitor'
+
+require 'date'
+require File.join(SUBDIRECTORY, 'version')
+require File.join(SUBDIRECTORY, 'temporal')
+require File.join(SUBDIRECTORY, 'range_overlap')
+require File.join(SUBDIRECTORY, 'core_class_extensions')
+require File.join(SUBDIRECTORY, 'acts_as_flux_capacitor')
+

data/lib/acts_as_flux_capacitor/acts_as_flux_capacitor.rb

@@ -0,0 +1,352 @@
+module HolmesLabs #:nodoc:
+  module Acts #:nodoc:
+    module FluxCapacitor
+      module ActiveRecord #:nodoc:
+        def self.included(base) # :nodoc:
+	        base.extend ClassMethods
+        end
+				 
+        module ClassMethods
+	        def acts_as_flux_capacitor
+						unless acts_as_flux_capacitor?
+							class << self
+								alias_method :original_find, :find
+							end
+						end
+						include Temporal
+	          include InstanceMethods
+            include OperateOnEvents
+            include OperateOnDurations
+            include CompareEvents
+						include Validation
+	        end
+					
+					def flux_capacitor?
+						included_modules.include?(InstanceMethods)
+					end
+					alias acts_as_flux_capacitor? flux_capacitor?
+				end
+        
+				protected
+				
+        module InstanceMethods #:nodoc:
+          def self.included(base) # :nodoc:
+            base.extend ClassMethods
+            base.extend QueryGenerators
+          end
+					
+					module ClassMethods
+						
+						CUSTOM_FIND_OPTIONS = [
+							:before, # raw sql
+							:after, # raw sql
+							
+							:now,
+							:at,
+							
+							:past,
+							:present,
+							:future,
+							
+							:from,
+							:to,
+							
+							:starts_before, # raw sql
+							:ends_after # raw sql
+						]
+						
+						def find(*args)
+							options = args.extract_options!
+							
+							current_time				= options.delete(:current_time)
+							temporal_conditions = extract_temporal_conditions!(options)
+							sql_temporal 				= sql_generate_temporal(temporal_conditions,current_time)
+							
+							puts temporal_conditions.size
+							puts sql_temporal
+							
+							with_scope(	:find 	=> { 
+														:conditions => sql_temporal , 
+														:order 			=> sql_oldest_first }) do
+								original_find(*(args << options))
+							end
+						end
+						
+						def overlap(an_event,another_event)
+							an_event.to_range.overlap(another_event.to_range)
+						end
+						
+						def overlap?(an_event,another_event)
+							an_event.to_range.overlap?(another_event.to_range)
+						end
+private
+						def extract_temporal_conditions!(options)
+							temporal_conditions = {}
+							
+							options.each do |key,val|
+								temporal_conditions.merge!({key, options.delete(key)}) if CUSTOM_FIND_OPTIONS.include?(key)
+							end
+							
+							
+							require 'pp'# ; pp "(#{temporal_conditions.class}) #{temporal_conditions.first.keys}: #{temporal_conditions.first.values}"
+							pp temporal_conditions
+							temporal_conditions
+						end
+					end
+											
+					module QueryGenerators
+					private
+						
+						def sql_before(some_time, current_time = nil)
+							# table_name comes from ActiveRecord.
+							"#{table_name}.ends_at < '#{some_time.to_s(:db)}'"
+						end
+						alias sql_to sql_before
+						alias sql_ends_before sql_before
+						
+						def sql_after(some_time , current_time = nil)
+							# table_name comes from ActiveRecord.
+							"#{table_name}.begins_at > '#{some_time.to_s(:db)}'"
+						end
+						alias sql_from sql_after
+						alias sql_begins_after sql_after
+						
+						def sql_at(some_time , current_time = Time.now)
+							sql_join_conditions([	sql_starts_before(	some_time),
+																		sql_ends_after(			some_time)])
+						end
+						
+						def sql_ends_after(some_time , current_time = nil)
+							"#{table_name}.ends_at > '#{some_time.to_s(:db)}'"
+						end
+						
+						def sql_starts_before(some_time , current_time = nil)
+							"#{table_name}.begins_at < '#{some_time.to_s(:db)}'"
+						end
+						
+						def sql_past(is_true , current_time = Time.now)
+							if is_true
+								sql_before(current_time)
+							else
+								sql_join_conditions_or([	sql_present(	Time.now),
+																					sql_future(		Time.now)])
+							end
+						end
+						alias sql_ended sql_past
+						
+						def sql_present(is_true , current_time = Time.now)
+							if is_true
+								sql_at(current_time)
+							else
+								sql_join_conditions_or([	sql_past(		Time.now),
+																					sql_future(	Time.now)])
+							end
+						end
+						alias sql_now sql_present
+						
+						def sql_future(is_true, current_time = Time.now)
+							if is_true
+								sql_after(current_time)
+							else
+								sql_join_conditions_or([	sql_present(	Time.now),
+																					sql_past(			Time.now)])
+							end
+						end
+						
+						def sql_oldest_first(attrib = :begins_at)
+							"#{table_name}.#{attrib.to_s} ASC"
+						end
+						
+						def sql_join_conditions(conditions)
+							"#{conditions.join(") AND (")}"
+						end
+						
+						def sql_join_conditions_or(conditions)
+							"#{conditions.join(") OR (")}"
+						end
+						
+						def sql_generate_temporal(temporal_conditions,current_time)
+							sql_conditions = []
+							temporal_conditions.each do |condition,parameter|
+								puts "#{condition}: #{parameter}"
+								sql_conditions << send("sql_#{condition}" , parameter , current_time)
+							end
+							
+							require 'pp' ; pp sql_conditions
+							pp sql_join_conditions(sql_conditions)
+							sql_join_conditions(sql_conditions)
+						end
+					end
+					
+					def to_range
+						(start..finish)
+					end
+					alias range to_range
+					
+					def start ; read_attribute(:begins_at) ; end
+					def start=(val) ; write_attribute(:begins_at,val); end
+					
+					def finish ; read_attribute(:ends_at) ; end
+					def finish=(val) ; write_attribute(:ends_at,val) ; end
+					
+					alias start_time		start
+					alias start_time=		start=
+					alias beginning			start
+					alias beginning=		start=
+					alias end_time			finish
+					alias end_time=			finish=
+					alias from					start
+					alias from=					start=
+					alias to						finish
+					alias to=						finish=
+					alias ending				finish
+					alias ending=				finish=
+        end # InstanceMethods
+        
+        module OperateOnEvents
+					def at?(obj=Time.now)
+						bigger_than = self.start_time.before?(extract_time(obj,:start_time))   &&
+													self.end_time.after?(		extract_time(obj,:end_time 	))
+						smaller_than = 	self.start_time.after?( extract_time(obj,:start_time)) &&
+														self.end_time.before?(	extract_time(obj,:end_time))
+						same_size		= self.start_time == extract_time(obj,:start_time) &&
+													self.end_time		== extract_time(obj,:end_time)
+						return bigger_than || smaller_than || same_size
+					end
+					alias happening_at? at?
+					alias happened_at? at?
+					
+					def happening_now?(time = Time.now)
+						at?(time)
+					end
+					alias in_progress? 	happening_now?
+					alias now?					happening_now?
+					alias present?					happening_now?
+          
+          def started?(time = Time.now)
+            self.start_time.before?(time)
+          end
+          alias began? started?
+					
+					def ended?(time = Time.now)
+						self.end_time.before?(time)
+					end
+					alias finished? ended?
+					
+          def <=>(obj)
+            if self.before?(obj)
+              return -1
+            elsif at?(obj)
+              return 0
+            elsif self.after?(obj)
+              return 1
+            else
+              return 'ActsAsEvent: non-fatal error in #status'
+            end
+          end
+					
+          def transpose(duration)
+            new_event = self.clone
+						new_event.transpose!(duration)
+          end
+          alias shift       transpose
+          alias reschedule  transpose
+          alias move        transpose
+					
+					def transpose!(duration)
+            self.beginning 	+= duration
+						self.ending			+= duration
+						return self
+          end
+          alias shift!       transpose!
+          alias reschedule!  transpose!
+          alias move!        transpose!
+        end # OperateOnEvents
+				
+        module OperateOnDurations
+          def elapsed(time = Time.now)
+            time_since_beginning = self.class.length_of_time_since(self.beginning,time)
+						self.now?(time) ? time_since_beginning : nil
+          end
+          
+          def remaining(time = Time.now)
+            time_until_end = self.class.length_of_time_until(self.ending,time)
+						self.now?(time) ? time_until_end : nil 
+          end
+          
+          def percent_complete(time = Time.now)
+						amount_complete = self.elapsed(time)
+						amount_complete ? 100 * ((amount_complete * 1.0) / duration) : nil
+          end
+          alias percent_elapsed percent_complete
+          alias percent_finished percent_complete
+          
+          def percent_remaining(time = Time.now)
+						amount_remaining = self.remaining(time)
+						amount_remaining ? 100 * (( amount_remaining * 1.0) / duration) : nil 
+          end
+        end # OperateOnDurations
+				
+        module CompareEvents   
+          def overlaps_with?(other_event)
+						#this method possesses the associative property.
+            self.to_range.overlap?(other_event.to_range)
+          end
+          
+					def overlap_with(other_event)
+						(self.to_range.overlap(other_event.to_range)).size
+					end
+					alias overlap overlap_with
+					
+          def back_to_back_with?(other_event,tolerance = 0)
+						# tolerance is in seconds.
+            # first_event,second_event = self.class.send(:ordered_tuple,self,other_event)
+						# first_event.ends_at.approx_eql?(second_event.begins_at,tolerance)
+						self.start_time.before?(other_event.start_time) ? first_to_start = self : first_to_start = other_event
+						first_to_start.ends_at.approx_eql?(other_event.begins_at,tolerance)
+          end
+					
+					def duration
+						self.class.length_of_time_until(self.ending,self.beginning)
+					end
+					alias length_of_time	duration
+					alias length				 	duration
+					
+					def duration=(new_duration)
+						self.ending = self.beginning + new_duration
+					end
+					alias length_of_time=	duration=
+					alias length=				 	duration=
+				end # CompareEvents
+				
+				module Validation
+					
+					def validate
+						if self.begins_at.nil?
+							errors.add(:begins_at, "must have a start time")
+							if self.ends_at.nil?
+								errors.add(:ends_at, "must have an end time")
+							end
+						else
+							self.beginning.after?(self.ending) ? errors.add_to_base("An event cannot end before it begins") : nil
+						end
+					end
+				end
+      end # ActiveRecord
+    end # FluxCapacitor
+  end # Acts
+end # HolmesLabs
+ActiveRecord::Base.send :include, HolmesLabs::Acts::FluxCapacitor::ActiveRecord
+
+# TODO
+###########
+# allow events to be created by start time and duration
+# force exclusivity of events at any given time via parameter to acts_as_event()
+# add new validations
+# rake tasks
+# parameter to comparison operator to still allow true if overlap
+
+
+# NOTES
+###########
+# verify #find_* returns ordered results unless specified otherwise.