timeliness 0.2.0 → 0.3.0

data/.gitignore

@@ -0,0 +1 @@
+pkg/*

data/.rspec

@@ -0,0 +1 @@
+--color

data/CHANGELOG.rdoc

@@ -1,3 +1,9 @@
+= 0.3.0 - 2010-11-27
+* Support for parsed timezone offset or abbreviation being used in creating time value
+* Added timezone abbreviation mapping config option
+* Allow 2nd argument for parse method to be the type, :now value, or options hash.
+* Refactoring
+
 = 0.2.0 - 2010-10-27
 * Allow a lambda for date_for_time_type which is evaluated on parse
 * Return the offset or zone in array from _parse

data/README.rdoc

@@ -14,9 +14,9 @@ Date/time parser for Ruby with the following features:
 * I18n support (for months), if I18n gem loaded.
 * Fewer WTFs than Time/Date parse method.
 * Has no dependencies.
-* Works with Ruby MRI 1.8.*, 1.9.2, Rubinius
+* Works with Ruby MRI 1.8.*, 1.9.2, Rubinius and JRuby.
 
-Extracted from my {validates_timeliness gem}[http://github.com/adzap/validates_timeliness], it has been rewritten cleaner and much faster. It's most suitable for when
+Extracted from the {validates_timeliness gem}[http://github.com/adzap/validates_timeliness], it has been rewritten cleaner and much faster. It's most suitable for when
 you need to control the parsing behaviour. It's faster than the Time/Date class parse methods, so it
 has general appeal.
 
@@ -64,6 +64,9 @@ It can also be specified with :now option:
 
   Timeliness.parse('12:13:14', :now => Time.mktime(2010,9,8)) #=> Wed Sep 08 12:13:14 1000 2010
 
+As well conforming to the Ruby Time class style.
+
+  Timeliness.parse('12:13:14', Time.mktime(2010,9,8)) #=> Wed Sep 08 12:13:14 1000 2010
 
 === Timezone
 
@@ -95,13 +98,36 @@ To get super finicky, you can restrict the parsing to a single format with the :
   Timeliness.parse('08/09/2010 12:13:14', :format => 'yyyy-mm-dd hh:nn:ss')  #=> nil
 
 
+=== String with Offset or Zone Abbreviations
+
+Sometimes you may want to parse a string with a zone abbreviation (e.g. MST) or the zone offset (e.g. +1000).
+These values are supported by the parser and will be used when creating the time object. The return value
+will be in the default timezone or the zone specified with the :zone option.
+
+  Timeliness.parse('Wed, 08 Sep 2010 12:13:14 MST') => Thu, 09 Sep 2010 05:13:14 EST 10:00
+
+  Timeliness.parse('2010-09-08T12:13:14-06:00')     => Thu, 09 Sep 2010 05:13:14 EST 10:00
+
+To enable zone abbreviations to work you must have loaded ActiveSupport.
+
+The zone abbreviations supported are those defined in the TzInfo gem, used by ActiveSupport. If you find some
+that are missing you can add more:
+
+  Timeliness.timezone_mapping.update(
+    'ZZZ' => 'Sleepy Town'
+  )
+
+Where 'Sleepy Town' is a valid zone name supported by ActiveSupport/TzInfo.
+
+
 === Raw Parsed Values
 
 If you would like to get the raw array of values before the time object is created, you can with
 
-  Timeliness._parse('2010-09-08 12:13:14') # => [2010, 9, 8, 12, 13, 14, nil, nil]
+  Timeliness._parse('2010-09-08 12:13:14.123456 MST') # => [2010, 9, 8, 12, 13, 14, 123456, 'MST']
 
-The last two nils are for the empty value of microseconds, and timezone or offset.
+The last two value are the microseconds, and zone abbreviation or offset.
+Note: The format for this value is not defined. You can add it yourself, easily.
 
 
 == Formats

data/Rakefile

@@ -1,28 +1,9 @@
 require 'rubygems'
 require 'rake/rdoctask'
-require 'rake/gempackagetask'
 require 'rubygems/specification'
 require 'rspec/core/rake_task'
-require 'lib/timeliness/version'
 
 GEM_NAME = "timeliness"
-GEM_VERSION = Timeliness::VERSION
-
-spec = Gem::Specification.new do |s|
-  s.name = GEM_NAME
-  s.version = GEM_VERSION
-  s.platform = Gem::Platform::RUBY
-  s.rubyforge_project = "timeliness"
-  s.has_rdoc = true
-  s.extra_rdoc_files = ["README.rdoc", "CHANGELOG.rdoc"]
-  s.summary = %q{Control time (parsing), quickly.}
-  s.description = %q{Fast date/time parser with customisable formats and I18n support.}
-  s.author = "Adam Meehan"
-  s.email = "adam.meehan@gmail.com"
-  s.homepage = "http://github.com/adzap/timeliness"
-  s.require_path = 'lib'
-  s.files = %w(timeliness.gemspec LICENSE CHANGELOG.rdoc README.rdoc Rakefile) + Dir.glob("{lib,spec}/**/*")
-end
 
 desc 'Default: run specs.'
 task :default => :spec
@@ -47,18 +28,7 @@ Rake::RDocTask.new(:rdoc) do |rdoc|
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
 
-Rake::GemPackageTask.new(spec) do |pkg|
-  pkg.gem_spec = spec
-end
-
-desc "Install the gem locally"
-task :install => [:package] do
-  sh %{gem install pkg/#{GEM_NAME}-#{GEM_VERSION}}
-end
-
 desc "Create a gemspec file"
-task :make_spec do
-  File.open("#{GEM_NAME}.gemspec", "w") do |file|
-    file.puts spec.to_ruby
-  end
+task :build do
+  `gem build #{GEM_NAME}.gemspec`
 end

data/benchmark.rb

@@ -0,0 +1,161 @@
+$:.unshift(File.expand_path('lib'))
+
+require 'benchmark'
+require 'time'
+require 'parsedate'
+require 'timeliness'
+
+if defined?(JRUBY_VERSION)
+  # Warm up JRuby
+  20000.times do
+    Time.parse("2000-01-04 12:12:12")
+    Timeliness::Parser.parse("2000-01-04 12:12:12", :datetime)
+  end
+end
+
+n = 10000
+Benchmark.bm do |x|
+  x.report('timeliness - datetime') {
+    n.times do
+      Timeliness::Parser.parse("2000-01-04 12:12:12", :datetime)
+    end
+  }
+
+  x.report('timeliness - datetime with :format') {
+    n.times do
+      Timeliness::Parser.parse("2000-01-04 12:12:12", :datetime, :format => 'yyyy-mm-dd hh:nn:ss')
+    end
+  }
+
+  x.report('timeliness - date') {
+    n.times do
+      Timeliness::Parser.parse("2000-01-04", :date)
+    end
+  }
+
+  x.report('timeliness - date as datetime') {
+    n.times do
+      Timeliness::Parser.parse("2000-01-04", :datetime)
+    end
+  }
+
+  x.report('timeliness - time') {
+    n.times do
+      Timeliness::Parser.parse("12:01:02", :time)
+    end
+  }
+
+  x.report('timeliness - no type with datetime value') {
+    n.times do
+      Timeliness::Parser.parse("2000-01-04 12:12:12")
+    end
+  }
+
+  x.report('timeliness - no type with date value') {
+    n.times do
+      Timeliness::Parser.parse("2000-01-04")
+    end
+  }
+
+  x.report('timeliness - no type with time value') {
+    n.times do
+      Timeliness::Parser.parse("12:01:02")
+    end
+  }
+
+  x.report('timeliness - invalid format datetime') {
+    n.times do
+      Timeliness::Parser.parse("20xx-01-04 12:12:12", :datetime)
+    end
+  }
+
+  x.report('timeliness - invalid format date') {
+    n.times do
+      Timeliness::Parser.parse("20xx-01-04", :date)
+    end
+  }
+
+  x.report('timeliness - invalid format time') {
+    n.times do
+      Timeliness::Parser.parse("12:xx:02", :time)
+    end
+  }
+
+  x.report('timeliness - invalid value datetime') {
+    n.times do
+      Timeliness::Parser.parse("2000-01-32 12:12:12", :datetime)
+    end
+  }
+
+  x.report('timeliness - invalid value date') {
+    n.times do
+      Timeliness::Parser.parse("2000-01-32", :date)
+    end
+  }
+
+  x.report('timeliness - invalid value time') {
+    n.times do
+      Timeliness::Parser.parse("12:61:02", :time)
+    end
+  }
+
+  x.report('ISO regexp for datetime') {
+    n.times do
+      "2000-01-04 12:12:12" =~ /\A(\d{4})-(\d{2})-(\d{2}) (\d{2})[\. :](\d{2})([\. :](\d{2}))?\Z/
+      microsec = ($7.to_f * 1_000_000).to_i
+      Time.mktime($1.to_i, $2.to_i, $3.to_i, $3.to_i, $5.to_i, $6.to_i, microsec)
+    end
+  }
+
+  x.report('Time.parse - valid') {
+    n.times do
+      Time.parse("2000-01-04 12:12:12")
+    end
+  }
+
+  x.report('Time.parse - invalid ') {
+    n.times do
+      Time.parse("2000-01-32 12:12:12") rescue nil
+    end
+  }
+
+  x.report('Date._parse - valid') {
+    n.times do
+      hash = Date._parse("2000-01-04 12:12:12")
+      Time.mktime(hash[:year], hash[:mon], hash[:mday], hash[:hour], hash[:min], hash[:sec])
+    end
+  }
+
+  x.report('Date._parse - invalid ') {
+    n.times do
+      hash = Date._parse("2000-01-32 12:12:12")
+      Time.mktime(hash[:year], hash[:mon], hash[:mday], hash[:hour], hash[:min], hash[:sex]) rescue nil
+    end
+  }
+
+  x.report('parsedate - valid') {
+    n.times do
+      arr = ParseDate.parsedate("2000-01-04 12:12:12")
+      Date.new(*arr[0..2])
+      Time.mktime(*arr)
+    end
+  }
+
+  x.report('parsedate - invalid ') {
+    n.times do
+      arr = ParseDate.parsedate("2000-00-04 12:12:12")
+    end
+  }
+
+  x.report('strptime - valid') {
+    n.times do
+      DateTime.strptime("2000-01-04 12:12:12", '%Y-%m-%d %H:%M:%s')
+    end
+  }
+
+  x.report('strptime - invalid') {
+    n.times do
+      DateTime.strptime("2000-00-04 12:12:12", '%Y-%m-%d %H:%M:%s') rescue nil
+    end
+  }
+end

data/lib/timeliness.rb

@@ -2,7 +2,8 @@ require 'date'
 require 'forwardable'
 
 require 'timeliness/helpers'
-require 'timeliness/formats'
+require 'timeliness/definitions'
+require 'timeliness/format'
 require 'timeliness/format_set'
 require 'timeliness/parser'
 require 'timeliness/version'
@@ -11,7 +12,7 @@ module Timeliness
   class << self
     extend Forwardable
     def_delegators Parser, :parse, :_parse
-    def_delegators Formats, :add_formats, :remove_formats, :use_us_formats, :use_euro_formats
+    def_delegators Definitions, :add_formats, :remove_formats, :use_us_formats, :use_euro_formats
     attr_accessor :default_timezone, :date_for_time_type, :ambiguous_year_threshold
   end
 
@@ -26,7 +27,7 @@ module Timeliness
   @default_timezone = :local
 
   # Set the default date part for a time type values.
-  @date_for_time_type = [ 2000, 1, 1 ]
+  @date_for_time_type = lambda { Time.now }
 
   def self.date_for_time_type
     case @date_for_time_type
@@ -49,4 +50,4 @@ module Timeliness
   @ambiguous_year_threshold = 30
 end
 
-Timeliness::Formats.compile_formats
+Timeliness::Definitions.compile_formats

data/lib/timeliness/{formats.rb → definitions.rb}

@@ -1,5 +1,5 @@
 module Timeliness
-  module Formats
+  module Definitions
 
     # Format tokens:
     #       y = year
@@ -100,7 +100,7 @@ module Timeliness
       'u'    => [ '\d{1,6}', :usec ],
       'ampm' => [ '[aApP]\.?[mM]\.?', :meridian ],
       'zo'   => [ '[+-]\d{2}:?\d{2}', :offset ],
-      'tz'   => [ '[A-Z]{1,4}', :zone ],
+      'tz'   => [ '[A-Z]{1,5}', :zone ],
       '_'    => [ '\s?' ]
     }
 
@@ -126,10 +126,25 @@ module Timeliness
       :meridian => [ nil ]
     }
 
+    # Mapping some common timezone abbreviations which are not mapped or
+    # mapped inconsistenly in ActiveSupport (TzInfo).
+    @timezone_mapping = {
+      'AEST' => 'Australia/Sydney',
+      'AEDT' => 'Australia/Sydney',
+      'ACST' => 'Australia/Adelaide',
+      'ACDT' => 'Australia/Adelaide',
+      'PST'  => 'PST8PDT',
+      'PDT'  => 'PST8PDT',
+      'CST'  => 'CST6CDT',
+      'CDT'  => 'CST6CDT',
+      'EDT'  => 'EST5EDT',
+      'MDT'  => 'MST7MDT'
+    }
+
     US_FORMAT_REGEXP = /\Am{1,2}[^m]/
 
     class << self
-      attr_accessor :time_formats, :date_formats, :datetime_formats, :format_tokens, :format_components
+      attr_accessor :time_formats, :date_formats, :datetime_formats, :format_tokens, :format_components, :timezone_mapping
       attr_reader :date_format_set, :time_format_set, :datetime_format_set
 
       # Adds new formats. Must specify format type and can specify a :before
@@ -191,7 +206,7 @@ module Timeliness
 
       # 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)
+      def format_sets(type, string)
         case type
         when :date
           [ @date_format_set, @datetime_format_set ]
@@ -217,6 +232,5 @@ module Timeliness
       end
 
     end
-
   end
 end

data/lib/timeliness/format.rb

@@ -0,0 +1,64 @@
+module Timeliness
+  class Format
+    include Helpers
+
+    attr_reader :format_string, :regexp, :regexp_string, :token_count
+
+    def initialize(format_string)
+      @format_string = format_string
+    end
+
+    def compile!
+      @token_count = 0
+      format = format_string.dup
+      format.gsub!(/([\.\\])/, '\\\\\1') # escapes dots and backslashes
+      found_tokens, token_order = [], []
+
+      # Substitute tokens with numbered placeholder
+      Definitions.sorted_token_keys.each do |token|
+        token_regexp_str, arg_key = Definitions.format_tokens[token]
+        if format.gsub!(/#{token}/, "%<#{found_tokens.size}>")
+          if arg_key
+            token_regexp_str = "(#{token_regexp_str})"
+            @token_count += 1
+          end
+          found_tokens << [token_regexp_str, arg_key]
+        end
+      end
+
+      # Replace placeholders with token regexps
+      format.scan(/%<(\d)>/).each {|token_index|
+        token_index = token_index.first
+        token_regexp_str, arg_key = found_tokens[token_index.to_i]
+        format.gsub!("%<#{token_index}>", token_regexp_str)
+        token_order << arg_key
+      }
+
+      define_process_method(token_order.compact)
+      @regexp_string = format
+      @regexp = Regexp.new("^(#{format})$")
+      self
+    rescue
+      raise "The format '#{format_string}' failed to compile using regexp string #{format}."
+    end
+
+    # Redefined on compile
+    def process(*args); end
+
+    private
+
+    def define_process_method(components)
+      values = [nil] * 8
+      components.each do |component|
+        position, code = Definitions.format_components[component]
+        values[position] = code || "#{component}.to_i" if position
+      end
+      instance_eval <<-DEF
+        def process(#{components.join(',')})
+          [#{values.map {|i| i || 'nil' }.join(',')}]
+        end
+      DEF
+    end
+
+  end
+end

data/lib/timeliness/format_set.rb

@@ -1,97 +1,42 @@
 module Timeliness
   class FormatSet
-    include Helpers
-
     attr_reader :formats, :regexp
 
-    class << self
-
-      def compile(formats)
-        set = new(formats)
-        set.compile!
-        set
-      end
-
-      def compile_format(string_format)
-        format = string_format.dup
-        format.gsub!(/([\.\\])/, '\\\\\1') # escapes dots and backslashes
-        found_tokens, token_order, value_token_count = [], [], 0
-
-        # Substitute tokens with numbered placeholder
-        Formats.sorted_token_keys.each do |token|
-          regexp_str, arg_key = *Formats.format_tokens[token]
-          if format.gsub!(/#{token}/, "%<#{found_tokens.size}>")
-            if arg_key
-              regexp_str = "(#{regexp_str})"
-              value_token_count += 1
-            end
-            found_tokens << [regexp_str, arg_key]
-          end
-        end
-
-        # Replace placeholders with token regexps
-        format.scan(/%<(\d)>/).each {|token_index|
-          token_index = token_index.first
-          regexp_str, arg_key = found_tokens[token_index.to_i]
-          format.gsub!("%<#{token_index}>", regexp_str)
-          token_order << arg_key
-        }
-
-        define_format_method(string_format, token_order.compact)
-        return format, value_token_count
-      rescue
-        raise "The following format regular expression failed to compile: #{format}\n from format #{string_format}."
-      end
-
-      # Compiles a format method which maps the regexp capture groups to method
-      # arguments based on order captured. A time array is built using the argument
-      # values placed in the position defined by the component.
-      #
-      def define_format_method(name, components)
-        values = [nil] * 8
-        components.each do |component|
-          position, code = *Formats.format_components[component]
-          values[position] = code || "#{component}.to_i" if position
-        end
-        class_eval <<-DEF
-          define_method(:"format_#{name}") do |#{components.join(',')}|
-            [#{values.map {|i| i || 'nil' }.join(',')}]
-          end
-        DEF
-      end
-
+    def self.compile(formats)
+      new(formats).compile!
     end
 
     def initialize(formats)
-      @formats = formats
+      @formats       = formats
+      @formats_hash  = {}
+      @match_indexes = {}
     end
 
     # Compiles the formats into one big regexp. Stores the index of where
-    # each format's capture values begin in the match data. Each individual
-    # format regpexp is also stored for use with the parse :format option.
-    #
+    # each format's capture values begin in the matchdata.
     def compile!
-      regexp_string   = ''
-      @format_regexps = {}
-      @match_indexes  = {}
-      @formats.inject(0) { |index, format|
-        format_regexp, token_count = self.class.compile_format(format)
-        @format_regexps[format] = Regexp.new("^(#{format_regexp})$")
-        @match_indexes[index]   = format
-        regexp_string = "#{regexp_string}(#{format_regexp})|"
-        index + token_count + 1 # add one for wrapper capture
+      regexp_string = ''
+      @formats.inject(0) { |index, format_string|
+        format = Format.new(format_string).compile!
+        @formats_hash[format_string] = format
+        @match_indexes[index] = format
+        regexp_string = "#{regexp_string}(#{format.regexp_string})|"
+        index + format.token_count + 1 # add one for wrapper capture
       }
       @regexp = Regexp.new("^(?:#{regexp_string.chop})$")
+      self
     end
 
-    def match(string, format=nil)
-      match_regexp = format ? @format_regexps[format] : @regexp
+    def match(string, format_string=nil)
+      format = @formats_hash[format_string] if format_string
+      match_regexp = format && format.regexp || @regexp
+
       if match_data = match_regexp.match(string)
         index    = match_data.captures.index(string)
         start    = index + 1
         values   = match_data.captures[start..(start+7)].compact
         format ||= @match_indexes[index]
-        send(:"format_#{format}", *values)
+        format.process(*values)
       end
     end