texp 0.0.3 → 0.0.7

data/lib/texp.rb

@@ -1,4 +1,7 @@
-require 'texp/core'
+require 'date'
+require 'texp/time_ext'
+require 'texp/version'
+require 'texp/errors'
 require 'texp/base'
 require 'texp/parse'
 require 'texp/day_of_week'
@@ -10,4 +13,6 @@ require 'texp/day_interval'
 require 'texp/every_day'
 require 'texp/window'
 require 'texp/logic'
+require 'texp/dsl'
+require 'texp/operators'
 require 'texp/ext'

data/lib/texp/base.rb

@@ -1,9 +1,10 @@
-require 'texp/hash_builder'
-
 module TExp
+
+  ####################################################################
   # Abstract Base class for all Texp Temporal Expressions.
   class Base
-
+    include Enumerable
+    
     # Convert the temporal expression into an encoded string (that can
     # be parsed by TExp.parse).
     def to_s
@@ -12,8 +13,75 @@ module TExp
       codes.join("")
     end
 
-    private
+    # Create a new temporal expression with a new anchor date.
+    def reanchor(date)
+      self
+    end
+
+    # Return the first day of the window for the temporal expression.
+    # If the temporal expression is not a windowed expression, then
+    # the first day of the window is the given date.
+    def first_day_of_window(date)
+      includes?(date) ? date : nil
+    end
+
+    # Return the last day of the window for the temporal expression.
+    # If the temporal expression is not a windowed expression, then
+    # the last day of the window is the given date.
+    def last_day_of_window(date)
+      includes?(date) ? date : nil
+    end
 
+    # Iterate over all temporal expressions and subexpressions (in
+    # post order).
+    def each()                  # :yield: temporal_expression
+      yield self
+    end
+    
+    # :call-seq:
+    #   window(days)
+    #   window(predays, postdays)
+    #   window(n, units)
+    #   window(pre, pre_units, post, post_units)
+    #
+    # Create a new temporal expression that matches a window around
+    # any date matched by the current expression.
+    #
+    # If a single numeric value is given, then a symetrical window of
+    # the given number of days is created around each date matched by
+    # the current expression.  If a symbol representing units is given
+    # in addition to the numeric, then the appropriate scale factor is
+    # applied to the numeric value.
+    #
+    # If two numberic values are given (with or without unit symbols),
+    # then the window will be asymmetric.  The firsts numeric value
+    # will be the pre-window, and the second numeric value will be the
+    # post window.
+    #
+    # The following unit symbols are recognized:
+    #
+    # * :day, :days   (scale by 1)
+    # * :week, :weeks (scale by 7)
+    # * :month, :months (scale by 30)
+    # * :year, :years (scale by 365)
+    #
+    # <b>Examples:</b>
+    #
+    #   texp.window(3)         # window of 3 days on either side
+    #   texp.window(3, :days)  # window of 3 days on either side
+    #   texp.window(1, :week)  # window of 1 week on either side
+    #   texp.window(3, :days, 2, :weeks)
+    #                          # window of 3 days before any match,
+    #                          # and 2 weeks after any match.
+    #
+    def window(*args)
+      prewindow, postwindow = TExp.normalize_units(args)
+      postwindow ||= prewindow
+      TExp::Window.new(self, prewindow, postwindow)
+    end
+
+    private
+    
     # Coerce +arg+ into a list (i.e. Array) if it is not one already.
     def listize(arg)
       case arg
@@ -23,12 +91,12 @@ module TExp
         [arg]
       end
     end
-
+    
     # Encode the date into the codes receiver.
     def encode_date(codes, date)
       codes << date.strftime("%Y-%m-%d")
     end
-
+    
     # Encode the list into the codes receiver.  All
     def encode_list(codes, list)
       if list.empty?
@@ -46,7 +114,7 @@ module TExp
         codes << "]"
       end
     end
-
+    
     # For the list of integers as a list of ordinal numbers.  By
     # default, use 'or' as a connectingin word. (e.g. [1,2,3] => "1st,
     # 2nd, or 3rd")
@@ -91,7 +159,7 @@ module TExp
       11 => "th",
       12 => "th",
       13 => "th",
-    }
+    }                           # :nodoc:
 
     # Return the ordinal abbreviation for the integer +n+.  (e.g. 1 =>
     # "1st", 3 => "3rd")
@@ -141,6 +209,67 @@ module TExp
       def parse_callback(stack)
         stack.push new(stack.pop)
       end
+    end # class << self
+  end # class Base
+
+  ####################################################################
+  # Base class for temporal expressions with a single sub-expressions
+  # (i.e. term).
+  class SingleTermBase < Base
+    # Create a single term temporal expression.
+    def initialize(term)
+      @term = term
+    end
+
+    # Create a new temporal expression with a new anchor date.
+    def reanchor(date)
+      new_term = @term.reanchor(date)
+      (@term == new_term) ? self : self.class.new(new_term)
+    end
+
+    # Iterate over all temporal expressions and subexpressions (in
+    # post order).
+    def each()                  # :yield: temporal_expression
+      yield @term
+      yield self
+    end
+  end # class SingleTermBase
+
+  ####################################################################
+  # Base class for temporal expressions with multiple sub-expressions
+  # (i.e. terms).
+  class MultiTermBase < Base
+
+    # Create an multi-term temporal expression.
+    def initialize(*terms)
+      @terms = terms
+    end
+
+    # Create a new temporal expression with a new anchor date.
+    def reanchor(date)
+      new_terms = @terms.collect { |term| term.reanchor(date) }
+      if new_terms == @terms
+        self
+      else
+        self.class.new(*new_terms)
+      end
+    end
+
+    # Iterate over all temporal expressions and subexpressions (in
+    # post order).
+    def each()                  # :yield: temporal_expression
+      @terms.each do |term| yield term end
+      yield self
     end
-  end
-end
+
+    class << self
+      # Parsing callback for terms based temporal expressions.  The
+      # top of the stack is assumed to be a list that is *-expanded to
+      # the temporal expression's constructor.
+      def parse_callback(stack)
+        stack.push self.new(*stack.pop)
+      end
+    end
+  end # class << self
+
+end # class MultiTermBase

data/lib/texp/builder.rb

@@ -0,0 +1,254 @@
+module TExp
+
+  # Builder methods are available as methods on TExp
+  # (e.g. +TExp.day()+).  Alternatively, you can include the
+  # +TExp::Builder+ module into whatever namespace to get direct
+  # access to these methods.
+  module Builder
+
+    # Return a temporal expression that matches any date that falls on
+    # a day of the month given in the argument list.
+    # Examples:
+    #
+    #    day(1)       # Match any date that falls on the 1st of any month
+    #    day(1, 15)   # Match any date that falls on the 1st or 15th of any month
+    #
+    def day(*days_of_month)
+      TExp::DayOfMonth.new(days_of_month)
+    end
+
+    # Return a temporal expression that matches any date in the
+    # specified week of the month.  Days 1 through 7 are considered
+    # the first week of the month; days 8 through 14 are the second
+    # week; and so on.
+    #
+    # The week is specified by a numeric argument.  Negative arguments
+    # are calculated from the end of the month (e.g. -1 would request
+    # the _last_ 7 days of the month).  The symbols <tt>:first</tt>,
+    # <tt>:second</tt>, <tt>:third</tt>, <tt>:fourth</tt>,
+    # <tt>:fifth</tt>, and <tt>:last</tt> are also recognized.
+    #
+    # Examples:
+    #
+    #   week(1)       # Match any date in the first 7 days of any month.
+    #   week(1, 2)    # Match any date in the first or second 7 days of any month.
+    #   week(:first)  # Match any date in the first 7 days of any month.
+    #   week(:last)   # Match any date in the last 7 days of any month.
+    #
+    def week(*weeks)
+      TExp::Week.new(weeks)
+    end
+
+    # Return a temporal expression that matches any date in the list
+    # of given months.
+    #
+    # <b>Examples:</b>
+    #
+    #   month(2)              # Match any date in February
+    #   month(2, 8)           # Match any date in February or August
+    #   month("February")     # Match any date in February
+    #   month("Sep", "Apr", "Jun", "Nov")
+    #                         # Match any date in any month with 30 days.
+    #
+    def month(*month)
+      TExp::Month.new(month)
+    end
+
+    # Return a temporal expression that matches the given list of
+    # years.
+    #
+    # <b>Examples:</b>
+    #
+    #   year(2008)              # Match any date in 2008
+    #   year(2000, 2004, 2008)  # Match any date in any of the three years
+    def year(*years)
+      TExp::Year.new(years)
+    end
+
+    # :call-seq:
+    #   on(day, month)
+    #   on(day, month_string)
+    #   on(day, month, year)
+    #   on(day, month_string, year)
+    #   on(date)
+    #   on(date_string)
+    #   on(time)
+    #   on(object_with_to_date)
+    #   on(object_with_to_s)
+    #
+    # Return a temporal expression that matches a particular date of
+    # the year.  The temporal expression will be pinned to a
+    # particular year if a year is given (either explicity as a
+    # parameter or implicitly via a +Date+ object).  If no year is
+    # given, then the temporal expression will match that date in any
+    # year.
+    #
+    # If only a single argument is given, then the argument may be a
+    # string (which is parsed), a Date, a Time, or an object that
+    # responds to +to_date+.  If the single argument is none of the
+    # above, then it is converted to a string (via +to_s+) and given
+    # to <tt>Date.parse()</tt>.
+    #
+    # Invalid arguments will cause +on+ to throw an ArgumentError
+    # exception.
+    #
+    # <b>Examples:</b>
+    #
+    # The following examples all match Feb 14 of any year.
+    #
+    #   on(14, 2)
+    #   on(14, "February")
+    #   on(14, "Feb")
+    #   on(14, :feb)
+    #
+    # The following examples all match Feb 14 of the year 2008.
+    #
+    #   on(14, 2, 2008)
+    #   on(14, "February", 2008)
+    #   on(14, "Feb", 2008)
+    #   on(14, :feb, 2008)
+    #   on("Feb 14, 2008")
+    #   on(Date.new(2008, 2, 14))
+    #
+    def on(*args)
+      if args.size == 1
+        arg = args.first
+        case arg
+        when String
+          date = Date.parse(arg)
+        when Date
+          date = arg
+        else
+          if arg.respond_to?(:to_date)
+            date = arg.to_date
+          else
+            date = try_parsing(arg.to_s)
+          end
+        end
+        on(date.day, date.month, date.year)
+      elsif args.size == 2
+        day, month = dm_args(args)
+        TExp::And.new(
+          TExp::DayOfMonth.new(day),
+          TExp::Month.new(month))
+      elsif args.size == 3
+        day, month, year = dmy_args(args)
+        TExp::And.new(
+          TExp::DayOfMonth.new(day),
+          TExp::Month.new(normalize_month(month)),
+          TExp::Year.new(year))
+      else
+        fail DateArgumentError
+      end
+    rescue DateArgumentError
+      fail ArgumentError, "Invalid arguents for on(): #{args.inspect}"
+    end
+    
+    # Return a temporal expression matching the given days of the
+    # week.
+    #
+    # <b>Examples:</b>
+    #
+    #   dow(2)                 # Match any date on a Tuesday
+    #   dow("Tuesday")         # Match any date on a Tuesday
+    #   dow(:mon, :wed, :fr)   # Match any date on a Monday, Wednesday or Friday
+    #
+    def dow(*dow)
+      TExp::DayOfWeek.new(normalize_dows(dow))
+    end
+
+    # Return a temporal expression that matches 
+    def every(n, unit, start_date=Date.today)
+      value = apply_units(unit, n)
+      TExp::DayInterval.new(start_date, value)
+    end
+
+    def normalize_units(args)   # :nodoc:
+      result = []
+      while ! args.empty?
+        arg = args.shift
+        case arg
+        when Numeric
+          result.push(arg)
+        when Symbol
+          result.push(apply_units(arg, result.pop))
+        else
+          fail ArgumentError, "Unabled to recognize #{arg}"
+        end
+      end
+      result
+    end
+    
+    private
+    
+    MONTHNAMES = Date::MONTHNAMES.collect { |mn| mn ? mn[0,3].downcase : nil }
+    DAYNAMES = Date::DAYNAMES.collect { |dn| dn[0,2].downcase }
+    
+    UNIT_MULTIPLIERS = {
+      :day => 1,      :days => 1,
+      :week => 7,     :weeks => 7,
+      :month => 30,   :months => 30,
+      :year => 365,   :years => 365,
+    }
+
+    def apply_units(unit, value)
+      UNIT_MULTIPLIERS[unit] * value
+    end
+
+    def try_parsing(string)
+      Date.parse(string)
+    rescue ArgumentError
+      fail DateArgumentError
+    end
+
+    def dm_args(args)
+      day, month = args
+      month = normalize_month(month)
+      check_valid_day_month(day, month)
+      [day, month]
+    end
+    
+    def dmy_args(args)
+      day, month, year = args
+      month = normalize_month(month)
+      check_valid_day_month(day, month)
+      [day, month, year]
+    end
+    
+    def check_valid_day_month(day, month)
+      unless day.kind_of?(Integer) &&
+          month.kind_of?(Integer) &&
+          month >= 1 &&
+          month <= 12 &&
+          day >= 1 &&
+          day <= 31
+        fail DateArgumentError
+      end
+    end
+    
+    def normalize_month(month_thing)
+      case month_thing
+      when Integer
+        month_thing
+      else
+        MONTHNAMES.index(month_thing.to_s[0,3].downcase)
+      end
+    end
+
+    def normalize_dows(dow_list)
+      dow_list.collect { |dow| normalize_dow(dow) }
+    end
+
+    def normalize_dow(dow_thing)
+      case dow_thing
+      when Integer
+        dow_thing
+      else
+        DAYNAMES.index(dow_thing.to_s[0,2].downcase)
+      end
+    end
+
+  end
+
+  extend Builder
+end