ta_by_star 4.0.0

data/lib/by_star/base.rb

@@ -0,0 +1,76 @@
+module ByStar
+
+  module Base
+
+    include ByStar::Between
+    include ByStar::Directional
+
+    def by_star_field(*args)
+      options = args.extract_options!
+      @by_star_start_field ||= args[0]
+      @by_star_end_field   ||= args[1]
+      @by_star_offset      ||= options[:offset]
+      @by_star_scope       ||= options[:scope]
+      @by_star_index_scope ||= options[:index_scope]
+      @by_star_field_type  ||= options[:field_type]
+    end
+
+    def by_star_offset(options = {})
+      (options[:offset] || @by_star_offset || 0).seconds
+    end
+
+    def by_star_start_field(options={})
+      field = options[:field] ||
+          options[:start_field] ||
+          @by_star_start_field ||
+          by_star_default_field
+      field.to_s
+    end
+
+    def by_star_end_field(options={})
+      field = options[:field] ||
+          options[:end_field] ||
+          @by_star_end_field ||
+          by_star_start_field
+      field.to_s
+    end
+
+    def by_star_field_type(options={})
+      field = options[:field_type] ||
+          @by_star_field_type
+      field.to_s
+    end
+
+    protected
+
+    # Wrapper function which extracts time and options for each by_star query.
+    # Note the following syntax examples are valid:
+    #
+    #   Post.by_month                   # defaults to current time
+    #   Post.by_month(2, year: 2004)    # February, 2004
+    #   Post.by_month(Time.now)
+    #   Post.by_month(Time.now, field: "published_at")
+    #   Post.by_month(field: "published_at")
+    #
+    def with_by_star_options(*args, &block)
+      options = args.extract_options!.symbolize_keys!
+      time = args.first || Time.zone.now
+      block.call(time, options)
+    end
+
+    def by_star_eval_index_scope(start_time, end_time, options)
+      value = options[:index_scope] || @by_star_index_scope
+      value = value.call(start_time, end_time, options) if value.is_a?(Proc)
+      case value
+        when nil, false then nil
+        when Time, DateTime, Date then value.in_time_zone
+        when ActiveSupport::Duration then start_time - value
+        when Numeric then start_time - value.seconds
+        when :beginning_of_day
+          offset = options[:offset] || 0
+          (start_time - offset).beginning_of_day + offset
+        else raise 'ByStar :index_scope option value is not a supported type.'
+      end
+    end
+  end
+end

data/lib/by_star/between.rb

@@ -0,0 +1,190 @@
+module ByStar
+
+  module Between
+
+    def between_times(*args)
+      options = args.extract_options!.symbolize_keys!
+
+      start_time, end_time = ByStar::Normalization.extract_range(args)
+      offset = options[:offset] || 0
+      field_type = by_star_field_type(options)
+
+      if start_time.is_a?(Date)
+        start_time = field_type == 'date' ?
+          start_time :
+          ByStar::Normalization.apply_offset_start(start_time.in_time_zone, offset)
+      elsif start_time
+        start_time += offset.seconds
+      end
+
+      if end_time.is_a?(Date)
+        end_time = field_type == 'date' ?
+          end_time :
+          ByStar::Normalization.apply_offset_end(end_time.in_time_zone, offset)
+      elsif end_time
+        end_time += offset.seconds
+      end
+
+      start_field = by_star_start_field(options)
+      end_field = by_star_end_field(options)
+
+      scope = self
+      scope = if !start_time && !end_time
+                scope # do nothing
+              elsif !end_time
+                by_star_after_query(scope, start_field, start_time)
+              elsif !start_time
+                by_star_before_query(scope, start_field, end_time)
+              elsif start_field == end_field
+                by_star_point_query(scope, start_field, start_time, end_time)
+              elsif options[:strict]
+                by_star_span_strict_query(scope, start_field, end_field, start_time, end_time)
+              else
+                by_star_span_loose_query(scope, start_field, end_field, start_time, end_time, options)
+              end
+
+      scope = by_star_order(scope, options[:order]) if options[:order]
+      scope
+    end
+
+    def between_dates(*args)
+      options = args.extract_options!
+      start_date, end_date = ByStar::Normalization.extract_range(args)
+      start_date = ByStar::Normalization.date(start_date)
+      end_date   = ByStar::Normalization.date(end_date)
+      between_times(start_date, end_date, options)
+    end
+
+    def at_time(*args)
+      with_by_star_options(*args) do |time, options|
+        start_field = by_star_start_field(options)
+        end_field = by_star_end_field(options)
+
+        scope = self
+        scope = if start_field == end_field
+                  by_star_point_overlap_query(scope, start_field, time)
+                else
+                  by_star_span_overlap_query(scope, start_field, end_field, time, options)
+                end
+        scope = by_star_order(scope, options[:order]) if options[:order]
+        scope
+      end
+    end
+
+    def by_day(*args)
+      with_by_star_options(*args) do |time, options|
+        date = ByStar::Normalization.date(time)
+        between_dates(date, date, options)
+      end
+    end
+
+    def by_week(*args)
+      with_by_star_options(*args) do |time, options|
+        date = ByStar::Normalization.week(time, options)
+        start_day = Array(options[:start_day])
+        between_dates(date.beginning_of_week(*start_day), date.end_of_week(*start_day), options)
+      end
+    end
+
+    def by_cweek(*args)
+      with_by_star_options(*args) do |time, options|
+        by_week(ByStar::Normalization.cweek(time, options), options)
+      end
+    end
+
+    def by_weekend(*args)
+      with_by_star_options(*args) do |time, options|
+        date = ByStar::Normalization.week(time, options)
+        between_dates(date.beginning_of_weekend, date.end_of_weekend, options)
+      end
+    end
+
+    def by_fortnight(*args)
+      with_by_star_options(*args) do |time, options|
+        date = ByStar::Normalization.fortnight(time, options)
+        between_dates(date.beginning_of_fortnight, date.end_of_fortnight, options)
+      end
+    end
+
+    def by_month(*args)
+      with_by_star_options(*args) do |time, options|
+        date = ByStar::Normalization.month(time, options)
+        between_dates(date.beginning_of_month, date.end_of_month, options)
+      end
+    end
+
+    def by_calendar_month(*args)
+      with_by_star_options(*args) do |time, options|
+        date = ByStar::Normalization.month(time, options)
+        start_day = Array(options[:start_day])
+        between_dates(date.beginning_of_calendar_month(*start_day), date.end_of_calendar_month(*start_day), options)
+      end
+    end
+
+    def by_quarter(*args)
+      with_by_star_options(*args) do |time, options|
+        date = ByStar::Normalization.quarter(time, options)
+        between_dates(date.beginning_of_quarter, date.end_of_quarter, options)
+      end
+    end
+
+    def by_year(*args)
+      with_by_star_options(*args) do |time, options|
+        date = ByStar::Normalization.year(time, options)
+        between_dates(date.beginning_of_year, date.to_date.end_of_year, options)
+      end
+    end
+
+    def today(options = {})
+      by_day(Date.current, options)
+    end
+
+    def yesterday(options = {})
+      by_day(Date.yesterday, options)
+    end
+
+    def tomorrow(options = {})
+      by_day(Date.tomorrow, options)
+    end
+
+    def past_day(options = {})
+      between_times(Time.current - 1.day, Time.current, options)
+    end
+
+    def past_week(options = {})
+      between_times(Time.current - 1.week, Time.current, options)
+    end
+
+    def past_fortnight(options = {})
+      between_times(Time.current - 2.weeks, Time.current, options)
+    end
+
+    def past_month(options = {})
+      between_times(Time.current - 1.month, Time.current, options)
+    end
+
+    def past_year(options = {})
+      between_times(Time.current - 1.year, Time.current, options)
+    end
+
+    def next_day(options = {})
+      between_times(Time.current, Time.current + 1.day, options)
+    end
+
+    def next_week(options = {})
+      between_times(Time.current, Time.current  + 1.week, options)
+    end
+
+    def next_fortnight(options = {})
+      between_times(Time.current, Time.current + 2.weeks, options)
+    end
+
+    def next_month(options = {})
+      between_times(Time.current, Time.current + 1.month, options)
+    end
+
+    def next_year(options = {})
+      between_times(Time.current, Time.current + 1.year, options)
+    end
+  end
+end

data/lib/by_star/directional.rb

@@ -0,0 +1,35 @@
+module ByStar
+
+  module Directional
+
+    def before(*args)
+      with_by_star_options(*args) do |time, options|
+        field = by_star_start_field(options)
+        time = ByStar::Normalization.time(time)
+        by_star_before_query(self, field, time)
+      end
+    end
+    alias_method :before_now, :before
+
+    def after(*args)
+      with_by_star_options(*args) do |time, options|
+        field = by_star_start_field(options)
+        time = ByStar::Normalization.time(time)
+        by_star_after_query(self, field, time)
+      end
+    end
+    alias_method :after_now, :after
+
+    def oldest(*args)
+      with_by_star_options(*args) do |time, options|
+        oldest_query(options)
+      end
+    end
+
+    def newest(*args)
+      with_by_star_options(*args) do |time, options|
+        newest_query(options)
+      end
+    end
+  end
+end

data/lib/by_star/kernel/date.rb

@@ -0,0 +1,41 @@
+module ByStar
+
+  module Kernel
+
+    module Date
+
+      # A "Weekend" is defined as beginning of Saturday to end of Sunday.
+      # The weekend for a given date will be the the next weekend if the day Mon-Thurs,
+      # otherwise the current weekend if the day is Fri-Sun.
+      def beginning_of_weekend
+        beginning_of_week(:monday).advance(days: 5)
+      end
+
+      def end_of_weekend
+        beginning_of_weekend + 1
+      end
+
+      # A "Fortnight" is defined as a two week period, with the first fortnight of the
+      # year beginning on 1st January.
+      def beginning_of_fortnight
+        beginning_of_year + 14 * ((self - beginning_of_year) / 14).to_i
+      end
+
+      def end_of_fortnight
+        beginning_of_fortnight + 13
+      end
+
+      # A "Calendar Month" is defined as a month as it appears on a calendar, including days form
+      # previous/following months which are part of the first/last weeks of the given month.
+      def beginning_of_calendar_month(*args)
+        beginning_of_month.beginning_of_week(*args)
+      end
+
+      def end_of_calendar_month(*args)
+        end_of_month.end_of_week(*args)
+      end
+    end
+  end
+end
+
+::Date.__send__(:include, ByStar::Kernel::Date)

data/lib/by_star/kernel/in_time_zone.rb

@@ -0,0 +1,20 @@
+module ByStar
+
+  module Kernel
+
+    module InTimeZone
+      extend ActiveSupport::Concern
+
+      included do
+        if method_defined?(:to_time_in_current_zone) && !method_defined?(:in_time_zone)
+          alias_method :in_time_zone, :to_time_in_current_zone
+        end
+      end
+    end
+  end
+end
+
+::Date.__send__(:include, ByStar::Kernel::InTimeZone)
+::Time.__send__(:include, ByStar::Kernel::InTimeZone)
+::DateTime.__send__(:include, ByStar::Kernel::InTimeZone)
+::ActiveSupport::TimeWithZone.__send__(:include, ByStar::Kernel::InTimeZone)

data/lib/by_star/kernel/time.rb

@@ -0,0 +1,41 @@
+module ByStar
+
+  module Kernel
+
+    module Time
+
+      # A "Weekend" is defined as beginning of Saturday to end of Sunday.
+      # The weekend for a given date will be the the next weekend if the day Mon-Thurs,
+      # otherwise the current weekend if the day is Fri-Sun.
+      def beginning_of_weekend
+        beginning_of_week(:monday).advance(days: 5)
+      end
+
+      def end_of_weekend
+        (beginning_of_weekend + 47.hours).end_of_hour
+      end
+
+      # A "Fortnight" is defined as a two week period, with the first fortnight of the
+      # year beginning on 1st January.
+      def beginning_of_fortnight
+        (beginning_of_year + 1.fortnight * ((self - beginning_of_year) / 1.fortnight).to_i).beginning_of_day
+      end
+
+      def end_of_fortnight
+        (beginning_of_fortnight + 13.days).end_of_day
+      end
+
+      # A "Calendar Month" is defined as a month as it appears on a calendar, including days form
+      # previous/following months which are part of the first/last weeks of the given month.
+      def beginning_of_calendar_month(*args)
+        beginning_of_month.beginning_of_week(*args)
+      end
+
+      def end_of_calendar_month(*args)
+        end_of_month.end_of_week(*args)
+      end
+    end
+  end
+end
+
+::Time.__send__(:include, ByStar::Kernel::Time)

data/lib/by_star/normalization.rb

@@ -0,0 +1,156 @@
+module ByStar
+
+  class ParseError < StandardError; end
+
+  module Normalization
+
+    class << self
+
+      def date(value)
+        value = parse_time(value) if value.is_a?(String)
+        value = value.try(:in_time_zone) unless value.is_a?(Date)
+        value.try(:to_date)
+      end
+
+      def time(value)
+        value = parse_time(value) if value.is_a?(String)
+        value.try(:in_time_zone)
+      end
+
+      def week(value, options={})
+        value = try_string_to_int(value)
+        case value
+          when Integer then week_integer(value, options)
+          else date(value)
+        end
+      end
+
+      def week_integer(value, options={})
+        raise ParseError, 'Week number must be between 0 and 52' unless value.in?(0..52)
+        time = Time.zone.local(options[:year] || Time.zone.now.year)
+        time.beginning_of_year + value.to_i.weeks
+      end
+
+      def cweek(value, options={})
+        _value = value
+        if _value.is_a?(Integer)
+          raise ParseError, 'cweek number must be between 1 and 53' unless value.in?(1..53)
+          _value -= 1
+        end
+        week(_value, options)
+      end
+
+      def fortnight(value, options={})
+        value = try_string_to_int(value)
+        case value
+          when Integer then fortnight_integer(value, options)
+          else date(value)
+        end
+      end
+
+      def fortnight_integer(value, options={})
+        raise ParseError, 'Fortnight number must be between 0 and 26' unless value.in?(0..26)
+        time = Time.zone.local(options[:year] || Time.zone.now.year)
+        time + (value * 2).weeks
+      end
+
+      def quarter(value, options={})
+        value = try_string_to_int(value)
+        case value
+          when Integer then quarter_integer(value, options)
+          else date(value)
+        end
+      end
+
+      def quarter_integer(value, options={})
+        raise ParseError, 'Quarter number must be between 1 and 4' unless value.in?(1..4)
+        time = Time.zone.local(options[:year] || Time.zone.now.year)
+        time.beginning_of_year + ((value - 1) * 3).months
+      end
+
+      def month(value, options={})
+        value = try_string_to_int(value)
+        case value
+          when Integer, String then month_integer(value, options)
+          else date(value)
+        end
+      end
+
+      def month_integer(value, options={})
+        year = options[:year] || Time.zone.now.year
+        Time.zone.parse "#{year}-#{value}-01"
+      rescue
+        raise ParseError, 'Month must be a number between 1 and 12 or a month name'
+      end
+
+      def year(value, options={})
+        value = try_string_to_int(value)
+        case value
+          when Integer then year_integer(value)
+          else date(value)
+        end
+      end
+
+      def year_integer(value)
+        Time.zone.local(extrapolate_year(value))
+      end
+
+      def extrapolate_year(value)
+        case value.to_i
+          when 0..69
+            2000 + value
+          when 70..99
+            1900 + value
+          else
+            value.to_i
+        end
+      end
+
+      def try_string_to_int(value)
+        value.is_a?(String) ? Integer(value) : value
+      rescue
+        value
+      end
+
+      def time_in_units(seconds)
+        days = seconds / 1.day
+        time = Time.at(seconds).utc
+        { days: days, hour: time.hour, min: time.min, sec: time.sec }
+      end
+
+      def apply_offset_start(time, offset)
+        units = time_in_units(offset)
+        time += units.delete(:days).days
+        time.change(units)
+      end
+
+      def apply_offset_end(time, offset)
+        units = time_in_units(offset)
+        time += units.delete(:days).days
+        (time + 1.day).change(units) - 1.second
+      end
+
+      def extract_range(args)
+        case args[0]
+        when Array, Range then [args[0].first, args[0].last]
+        else args[0..1]
+        end
+      end
+
+      private
+
+      def parse_time(value)
+        defined?(Chronic) ? parse_time_chronic(value) : parse_time_fallback(value)
+      end
+
+      def parse_time_chronic(value)
+        Chronic.time_class = Time.zone
+        Chronic.parse(value) || raise(ByStar::ParseError, "Chronic could not parse String #{value.inspect}")
+      end
+
+      def parse_time_fallback(value)
+        Time.zone.parse(value) || raise(ByStar::ParseError, "Cannot parse String #{value.inspect}")
+      end
+    end
+  end
+end

data/lib/by_star/orm/active_record/by_star.rb

@@ -0,0 +1,75 @@
+module ByStar
+  module ActiveRecord
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      include ::ByStar::Base
+
+      protected
+
+      def by_star_default_field
+        "#{self.table_name}.created_at"
+      end
+
+      def by_star_point_query(scope, field, start_time, end_time)
+        scope.where("#{field} >= ? AND #{field} <= ?", start_time, end_time)
+      end
+
+      def by_star_span_strict_query(scope, start_field, end_field, start_time, end_time)
+        scope.where("#{start_field} >= ? AND #{start_field} <= ? AND #{end_field} >= ? AND #{end_field} <= ?", start_time, end_time, start_time, end_time)
+      end
+
+      def by_star_span_loose_query(scope, start_field, end_field, start_time, end_time, options)
+        index_scope = by_star_eval_index_scope(start_time, end_time, options)
+        scope = scope.where("#{end_field} > ? AND #{start_field} < ?", start_time, end_time)
+        scope = scope.where("#{start_field} >= ?", index_scope) if index_scope
+        scope
+      end
+
+      def by_star_point_overlap_query(scope, field, time)
+        scope.where("#{field} = ?", time)
+      end
+
+      def by_star_span_overlap_query(scope, start_field, end_field, time, options)
+        index_scope = by_star_eval_index_scope(time, time, options)
+        scope = scope.where("#{end_field} > ? AND #{start_field} <= ?", time, time)
+        scope = scope.where("#{start_field} >= ?", index_scope) if index_scope
+        scope
+      end
+
+      def by_star_before_query(scope, field, time)
+        scope.where("#{field} <= ?", time)
+      end
+
+      def by_star_after_query(scope, field, time)
+        scope.where("#{field} >= ?", time)
+      end
+
+      def by_star_order(scope, order)
+        scope.order(order)
+      end
+
+      def oldest_query(options={})
+        field = by_star_start_field(options)
+        reorder("#{field} ASC").first
+      end
+
+      def newest_query(options={})
+        field = by_star_start_field(options)
+        reorder("#{field} DESC").first
+      end
+    end
+
+    def previous(options={})
+      field = self.class.by_star_start_field(options)
+      value = self.send(field.split(".").last)
+      self.class.where("#{field} < ?", value).reorder("#{field} DESC").first
+    end
+
+    def next(options={})
+      field = self.class.by_star_start_field(options)
+      value = self.send(field.split(".").last)
+      self.class.where("#{field} > ?", value).reorder("#{field} ASC").first
+    end
+  end
+end