timeliness 0.1.0

data/lib/timeliness/formats.rb

@@ -0,0 +1,221 @@
+module Timeliness
+  module Formats
+
+    # Format tokens:
+    #       y = year
+    #       m = month
+    #       d = day
+    #       h = hour
+    #       n = minute
+    #       s = second
+    #       u = micro-seconds
+    #    ampm = meridian (am or pm) with or without dots (e.g. am, a.m, or a.m.)
+    #       _ = optional space
+    #      tz = Timezone abbreviation (e.g. UTC, GMT, PST, EST)
+    #      zo = Timezone offset (e.g. +10:00, -08:00, +1000)
+    #
+    # All other characters are considered literal. You can embed regexp in the
+    # format but no guarantees that it will remain intact. If you don't use capture
+    # groups, dots or backslashes in the regexp, it may well work as expected.
+    # For special characters, use POSIX character classes for safety.
+    #
+    # Repeating tokens:
+    #       x = 1 or 2 digits for unit (e.g. 'h' means an hour can be '9' or '09')
+    #      xx = 2 digits exactly for unit (e.g. 'hh' means an hour can only be '09')
+    #
+    # Special Cases:
+    #      yy = 2 or 4 digit year
+    #    yyyy = exactly 4 digit year
+    #     mmm = month long name (e.g. 'Jul' or 'July')
+    #     ddd = Day name of 3 to 9 letters (e.g. Wed or Wednesday)
+    #       u = microseconds matches 1 to 6 digits
+
+    @time_formats = [
+      'hh:nn:ss',
+      'hh-nn-ss',
+      'h:nn',
+      'h.nn',
+      'h nn',
+      'h-nn',
+      'h:nn_ampm',
+      'h.nn_ampm',
+      'h nn_ampm',
+      'h-nn_ampm',
+      'h_ampm'
+    ]
+
+    @date_formats = [
+      'yyyy-mm-dd',
+      'yyyy/mm/dd',
+      'yyyy.mm.dd',
+      'm/d/yy',
+      'd/m/yy',
+      'm\d\yy',
+      'd\m\yy',
+      'd-m-yy',
+      'dd-mm-yyyy',
+      'd.m.yy',
+      'd mmm yy'
+    ]
+
+    @datetime_formats = [
+      'yyyy-mm-dd hh:nn:ss.u',
+      'yyyy-mm-dd hh:nn:ss',
+      'yyyy-mm-dd h:nn',
+      'yyyy-mm-dd h:nn_ampm',
+      'm/d/yy h:nn:ss',
+      'm/d/yy h:nn_ampm',
+      'm/d/yy h:nn',
+      'd/m/yy hh:nn:ss',
+      'd/m/yy h:nn_ampm',
+      'd/m/yy h:nn',
+      'dd-mm-yyyy hh:nn:ss',
+      'dd-mm-yyyy h:nn_ampm',
+      'dd-mm-yyyy h:nn',
+      'ddd, dd mmm yyyy hh:nn:ss tz', # RFC 822
+      'ddd, dd mmm yyyy hh:nn:ss zo', # RFC 822
+      'ddd mmm d hh:nn:ss zo yyyy', # Ruby time string
+      'yyyy-mm-ddThh:nn:ssZ', # ISO 8601 without zone offset
+      'yyyy-mm-ddThh:nn:sszo' # ISO 8601 with zone offset
+    ]
+
+    # All tokens available for format construction. The token array is made of
+    # regexp and key for format component mapping, if any.
+    #
+    @format_tokens = {
+      'ddd'  => [ '\w{3,9}' ],
+      'dd'   => [ '\d{2}',   :day ],
+      'd'    => [ '\d{1,2}', :day ],
+      'mmm'  => [ '\w{3,9}', :month ],
+      'mm'   => [ '\d{2}',   :month ],
+      'm'    => [ '\d{1,2}', :month ],
+      'yyyy' => [ '\d{4}',   :year ],
+      'yy'   => [ '\d{4}|\d{2}', :year ],
+      'hh'   => [ '\d{2}',   :hour ],
+      'h'    => [ '\d{1,2}', :hour ],
+      'nn'   => [ '\d{2}',   :min ],
+      'n'    => [ '\d{1,2}', :min ],
+      'ss'   => [ '\d{2}',   :sec ],
+      's'    => [ '\d{1,2}', :sec ],
+      'u'    => [ '\d{1,6}', :usec ],
+      'ampm' => [ '[aApP]\.?[mM]\.?', :meridian ],
+      'zo'   => [ '[+-]\d{2}:?\d{2}', :offset ],
+      'tz'   => [ '[A-Z]{1,4}' ],
+      '_'    => [ '\s?' ]
+    }
+
+    # Component argument values will be passed to the format method if matched in
+    # the time string. The key should match the key defined in the format tokens.
+    #
+    # The array consists of the position the value should be inserted in
+    # the time array, and the code to place in the time array.
+    #
+    # If the position is nil, then the value won't be put in the time array. If the
+    # code is nil, then just the raw value is used.
+    #
+    @format_components = {
+      :year     => [ 0, 'unambiguous_year(year)'],
+      :month    => [ 1, 'month_index(month)'],
+      :day      => [ 2 ],
+      :hour     => [ 3, 'full_hour(hour, meridian ||= nil)'],
+      :min      => [ 4 ],
+      :sec      => [ 5 ],
+      :usec     => [ 6, 'microseconds(usec)'],
+      :offset   => [ 7, 'offset_in_seconds(offset)'],
+      :meridian => [ nil ]
+    }
+
+    US_FORMAT_REGEXP = /\Am{1,2}[^m]/
+
+    class << self
+      attr_accessor :time_formats, :date_formats, :datetime_formats, :format_tokens, :format_components
+      attr_reader :date_format_set, :time_format_set, :datetime_format_set
+
+      # Adds new formats. Must specify format type and can specify a :before
+      # option to nominate which format the new formats should be inserted in
+      # front on to take higher precedence.
+      #
+      # Error is raised if format already exists or if :before format is not found.
+      #
+      def add_formats(type, *add_formats)
+        formats = send("#{type}_formats")
+        options = add_formats.last.is_a?(Hash) ? add_formats.pop : {}
+        before  = options[:before]
+        raise "Format for :before option #{format} was not found." if before && !formats.include?(before)
+
+        add_formats.each do |format|
+          raise "Format #{format} is already included in #{type} formats" if formats.include?(format)
+
+          index = before ? formats.index(before) : -1
+          formats.insert(index, format)
+        end
+        compile_formats
+      end
+
+      # Delete formats of specified type. Error raised if format not found.
+      #
+      def remove_formats(type, *remove_formats)
+        remove_formats.each do |format|
+          unless send("#{type}_formats").delete(format)
+            raise "Format #{format} not found in #{type} formats"
+          end
+        end
+        compile_formats
+      end
+
+      # Removes US date formats so that ambigious dates are parsed as European format
+      #
+      def use_euro_formats
+        @date_format_set     = FormatSet.compile(date_formats.select { |format| US_FORMAT_REGEXP !~ format })
+        @datetime_format_set = FormatSet.compile(datetime_formats.select { |format| US_FORMAT_REGEXP !~ format })
+      end
+
+      # Restores default to parse ambiguous dates as US format
+      #
+      def use_us_formats
+        @date_format_set     = FormatSet.compile(date_formats)
+        @datetime_format_set = FormatSet.compile(datetime_formats)
+      end
+
+      def compile_formats
+        @sorted_token_keys   = nil
+        @time_format_set     = FormatSet.compile(time_formats)
+        @date_format_set     = FormatSet.compile(date_formats)
+        @datetime_format_set = FormatSet.compile(datetime_formats)
+      end
+
+      def sorted_token_keys
+        @sorted_token_keys ||= format_tokens.keys.sort {|a,b| a.size <=> b.size }.reverse
+      end
+
+      # Returns format for type and other possible matching format set based on type
+      # and value length. Gives minor speed-up by checking string length.
+      def format_set(type, string)
+        case type
+        when :date
+          [ @date_format_set, @datetime_format_set ]
+        when :time
+          if string.length < 11
+            [ @time_format_set ]
+          else
+            [ @datetime_format_set, @time_format_set ]
+          end
+        when :datetime
+          if string.length < 11
+            [ @date_format_set, @datetime_format_set ]
+          else
+            [ @datetime_format_set, @date_format_set ]
+          end
+        else
+          if string.length < 11
+            [ @date_format_set, @time_format_set, @datetime_format_set ]
+          else
+            [ @datetime_format_set, @date_format_set, @time_format_set ]
+          end
+        end
+      end
+
+    end
+
+  end
+end

data/lib/timeliness/helpers.rb

@@ -0,0 +1,49 @@
+module Timeliness
+  module Helpers
+
+    def full_hour(hour, meridian)
+      hour = hour.to_i
+      return hour if meridian.nil?
+      if meridian.delete('.').downcase == 'am'
+        raise if hour == 0 || hour > 12
+        hour == 12 ? 0 : hour
+      else
+        hour == 12 ? hour : hour + 12
+      end
+    end
+
+    def unambiguous_year(year)
+      if year.length <= 2
+        century = Time.now.year.to_s[0..1].to_i
+        century -= 1 if year.to_i >= Timeliness.ambiguous_year_threshold
+        year = "#{century}#{year.rjust(2,'0')}"
+      end
+      year.to_i
+    end
+    
+    def month_index(month)
+      return month.to_i if month.to_i > 0
+      month.length > 3 ? month_names.index(month.capitalize) : abbr_month_names.index(month.capitalize)
+    end
+
+    def month_names
+      defined?(I18n) ? I18n.t('date.month_names') : Date::MONTHNAMES
+    end
+
+    def abbr_month_names
+      defined?(I18n) ? I18n.t('date.abbr_month_names') : Date::ABBR_MONTHNAMES
+    end
+
+    def microseconds(usec)
+      (".#{usec}".to_f * 1_000_000).to_i
+    end
+
+    def offset_in_seconds(offset)
+      sign = offset =~ /^-/ ? -1 : 1
+      parts = offset.scan(/\d\d/).map {|p| p.to_f }
+      parts[1] = parts[1].to_f / 60
+      (parts[0] + parts[1]) * sign * 3600
+    end
+
+  end
+end

data/lib/timeliness/parser.rb

@@ -0,0 +1,94 @@
+module Timeliness
+  module Parser
+
+    class << self
+
+      def parse(value, *args)
+        return value unless value.is_a?(String)
+
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        type = args.first
+
+        time_array = _parse(value, type, options)
+        return nil if time_array.nil?
+
+        if type == :date
+          time_array[3..7] = nil
+        elsif type == :time
+          time_array[0..2] = current_date(options)
+        elsif type.nil?
+          dummy_date = current_date(options)
+          time_array[0] ||= dummy_date[0]
+          time_array[1] ||= dummy_date[1]
+          time_array[2] ||= dummy_date[2]
+        end
+        make_time(time_array[0..6], options[:zone])
+      end
+
+      def make_time(time_array, zone=nil)
+        return nil unless fast_date_valid_with_fallback(*time_array[0..2])
+
+        zone ||= Timeliness.default_timezone
+        case zone
+        when :utc, :local
+          time_with_datetime_fallback(zone, *time_array.compact)
+        when :current
+          Time.zone.local(*time_array)
+        else
+          Time.use_zone(zone) { Time.zone.local(*time_array) }
+        end
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def _parse(string, type=nil, options={})
+        if options[:strict] && type
+          set = Formats.send("#{type}_format_set")
+          set.match(string, options[:format])
+        else
+          values = nil
+          Formats.format_set(type, string).find {|set| values = set.match(string, options[:format]) }
+          values
+        end
+      rescue
+        nil
+      end
+
+      private
+
+      def current_date(options)
+        now = if options[:now]
+          options[:now]
+        elsif options[:zone]
+          case options[:zone]
+          when :utc, :local
+            Time.now.send("get#{options[:zone]}")
+          when :current
+            Time.current
+          else
+            Time.use_zone(options[:zone]) { Time.current }
+          end
+        end
+        now ||= Timeliness.date_for_time_type
+        now.is_a?(Array) ? now[0..2] : Array(now).reverse[4..6]
+      end
+
+      # Taken from ActiveSupport and simplified
+      def time_with_datetime_fallback(utc_or_local, year, month=1, day=1, hour=0, min=0, sec=0, usec=0)
+       return nil if hour > 23 || min > 59 || sec > 59
+        ::Time.send(utc_or_local, year, month, day, hour, min, sec, usec)
+      rescue
+        offset = utc_or_local == :local ? (::Time.local(2007).utc_offset.to_r/86400) : 0
+        ::DateTime.civil(year, month, day, hour, min, sec, offset)
+      end
+
+      # Enforce strict date part validity which the Time class does not.
+      # Only does full date check if month and day are possibly invalid.
+      def fast_date_valid_with_fallback(year, month, day)
+        month < 13 && (day < 29 || Date.valid_civil?(year, month, day))
+      end
+
+    end
+
+  end
+end

data/lib/timeliness/version.rb

@@ -0,0 +1,3 @@
+module Timeliness
+  VERSION = '0.1.0'
+end

data/spec/spec_helper.rb

@@ -0,0 +1,36 @@
+require 'rspec'
+
+require 'active_support/time'
+require 'timecop'
+require 'timeliness'
+
+module TimelinessHelpers
+  def parser
+    Timeliness::Parser
+  end
+
+  def formats
+    Timeliness::Formats
+  end
+
+  def parse(*args)
+    Timeliness::Parser.parse(*args)
+  end
+
+  def current_date(options={})
+    Timeliness::Parser.send(:current_date, options)
+  end
+
+  def should_parse(*args)
+    Timeliness::Parser.parse(*args).should_not be_nil
+  end
+
+  def should_not_parse(*args)
+    Timeliness::Parser.parse(*args).should be_nil
+  end
+end
+
+Rspec.configure do |c|
+  c.mock_with :rspec
+  c.include TimelinessHelpers
+end

data/spec/timeliness/format_set_spec.rb

@@ -0,0 +1,106 @@
+require 'spec_helper'
+
+describe Timeliness::FormatSet do
+  context ".define_format_method" do
+    it "should define method which outputs date array with values in correct order" do
+      define_method_for('yyyy-mm-dd').call('2000', '1', '2').should == [2000,1,2,nil,nil,nil,nil]
+    end
+
+    it "should define method which outputs date array from format with different order" do
+      define_method_for('dd/mm/yyyy').call('2', '1', '2000').should == [2000,1,2,nil,nil,nil,nil]
+    end
+
+    it "should define method which outputs time array" do
+      define_method_for('hh:nn:ss').call('01', '02', '03').should == [nil,nil,nil,1,2,3,nil]
+    end
+
+    it "should define method which outputs time array with meridian 'pm' adjusted hour" do
+      define_method_for('hh:nn:ss ampm').call('01', '02', '03', 'pm').should == [nil,nil,nil,13,2,3,nil]
+    end
+
+    it "should define method which outputs time array with meridian 'am' unadjusted hour" do
+      define_method_for('hh:nn:ss ampm').call('01', '02', '03', 'am').should == [nil,nil,nil,1,2,3,nil]
+    end
+
+    it "should define method which outputs time array with microseconds" do
+      define_method_for('hh:nn:ss.u').call('01', '02', '03', '99').should == [nil,nil,nil,1,2,3,990000]
+    end
+
+    it "should define method which outputs datetime array with zone offset" do
+      define_method_for('yyyy-mm-dd hh:nn:ss.u zo').call('2001', '02', '03', '04', '05', '06', '99', '+10:00').should == [2001,2,3,4,5,6,990000,36000]
+    end
+  end
+
+  context "compiled regexp" do
+
+    context "for time formats" do
+      format_tests = {
+        'hh:nn:ss'  => {:pass => ['12:12:12', '01:01:01'], :fail => ['1:12:12', '12:1:12', '12:12:1', '12-12-12']},
+        'hh-nn-ss'  => {:pass => ['12-12-12', '01-01-01'], :fail => ['1-12-12', '12-1-12', '12-12-1', '12:12:12']},
+        'h:nn'      => {:pass => ['12:12', '1:01'], :fail => ['12:2', '12-12']},
+        'h.nn'      => {:pass => ['2.12', '12.12'], :fail => ['2.1', '12:12']},
+        'h nn'      => {:pass => ['2 12', '12 12'], :fail => ['2 1', '2.12', '12:12']},
+        'h-nn'      => {:pass => ['2-12', '12-12'], :fail => ['2-1', '2.12', '12:12']},
+        'h:nn_ampm' => {:pass => ['2:12am', '2:12 pm', '2:12 AM', '2:12PM'], :fail => ['1:2am', '1:12  pm', '2.12am']},
+        'h.nn_ampm' => {:pass => ['2.12am', '2.12 pm'], :fail => ['1:2am', '1:12  pm', '2:12am']},
+        'h nn_ampm' => {:pass => ['2 12am', '2 12 pm'], :fail => ['1 2am', '1 12  pm', '2:12am']},
+        'h-nn_ampm' => {:pass => ['2-12am', '2-12 pm'], :fail => ['1-2am', '1-12  pm', '2:12am']},
+        'h_ampm'    => {:pass => ['2am', '2 am', '12 pm'], :fail => ['1.am', '12  pm', '2:12am']},
+      }
+      format_tests.each do |format, values|
+        it "should correctly match times in format '#{format}'" do
+          regexp = compile_regexp(format)
+          values[:pass].each {|value| value.should match(regexp)}
+          values[:fail].each {|value| value.should_not match(regexp)}
+        end
+      end
+    end
+
+    context "for date formats" do
+      format_tests = {
+        'yyyy/mm/dd' => {:pass => ['2000/02/01'], :fail => ['2000\02\01', '2000/2/1', '00/02/01']},
+        'yyyy-mm-dd' => {:pass => ['2000-02-01'], :fail => ['2000\02\01', '2000-2-1', '00-02-01']},
+        'yyyy.mm.dd' => {:pass => ['2000.02.01'], :fail => ['2000\02\01', '2000.2.1', '00.02.01']},
+        'm/d/yy'     => {:pass => ['2/1/01', '02/01/00', '02/01/2000'], :fail => ['2/1/0', '2.1.01']},
+        'd/m/yy'     => {:pass => ['1/2/01', '01/02/00', '01/02/2000'], :fail => ['1/2/0', '1.2.01']},
+        'm\d\yy'     => {:pass => ['2\1\01', '2\01\00', '02\01\2000'], :fail => ['2\1\0', '2/1/01']},
+        'd\m\yy'     => {:pass => ['1\2\01', '1\02\00', '01\02\2000'], :fail => ['1\2\0', '1/2/01']},
+        'd-m-yy'     => {:pass => ['1-2-01', '1-02-00', '01-02-2000'], :fail => ['1-2-0', '1/2/01']},
+        'd.m.yy'     => {:pass => ['1.2.01', '1.02.00', '01.02.2000'], :fail => ['1.2.0', '1/2/01']},
+        'd mmm yy'   => {:pass => ['1 Feb 00', '1 Feb 2000', '1 February 00', '01 February 2000'],
+                          :fail => ['1 Fe 00', 'Feb 1 2000', '1 Feb 0']}
+      }
+      format_tests.each do |format, values|
+        it "should correctly match dates in format '#{format}'" do
+          regexp = compile_regexp(format)
+          values[:pass].each {|value| value.should match(regexp)}
+          values[:fail].each {|value| value.should_not match(regexp)}
+        end
+      end
+    end
+
+    context "for datetime formats" do
+      format_tests = {
+        'ddd mmm d hh:nn:ss zo yyyy'  => {:pass => ['Sat Jul 19 12:00:00 +1000 2008'], :fail => []},
+        'yyyy-mm-ddThh:nn:ss(?:Z|zo)' => {:pass => ['2008-07-19T12:00:00+10:00', '2008-07-19T12:00:00Z'], :fail => ['2008-07-19T12:00:00Z+10:00']},
+      }
+      format_tests.each do |format, values|
+        it "should correctly match datetimes in format '#{format}'" do
+          regexp = compile_regexp(format)
+          values[:pass].each {|value| value.should match(regexp)}
+          values[:fail].each {|value| value.should_not match(regexp)}
+        end
+      end
+    end
+
+  end
+
+  def define_method_for(format)
+    Timeliness::FormatSet.compile([format]).method(:"format_#{format}")
+  end
+
+  def compile_regexp(format)
+    Timeliness::FormatSet.compile([format]).regexp
+  end
+
+end