tzinfo 0.3.62 → 1.0.0

data/lib/tzinfo/data_source.rb

@@ -0,0 +1,182 @@
+#--
+# Copyright (c) 2012-2013 Philip Ross
+# 
+# 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.
+#++
+
+module TZInfo
+  # InvalidDataSource is raised if the DataSource is used doesn't implement one 
+  # of the required methods.
+  class InvalidDataSource < StandardError
+  end
+  
+  # DataSourceNotFound is raised if no data source could be found (i.e. 
+  # if 'tzinfo/data' cannot be found on the load path and no valid zoneinfo 
+  # directory can be found on the system).
+  class DataSourceNotFound < StandardError
+  end
+
+  # The base class for data sources of timezone and country data.
+  #
+  # Use DataSource.set to change the data source being used.
+  class DataSource
+    # The currently selected data source.
+    @@instance = nil
+        
+    # Returns the currently selected DataSource instance.
+    def self.get
+      set(create_default_data_source) unless @@instance
+      @@instance
+    end
+    
+    # Sets the currently selected data source for Timezone and Country data.
+    #
+    # This should usually be set to one of the two standard data source types:
+    #
+    # * +:ruby+ - read data from the Ruby modules included in the TZInfo::Data 
+    #   library (tzinfo-data gem).
+    # * +:zoneinfo+ - read data from the zoneinfo files included with most
+    #   Unix-like operating sytems (e.g. in /usr/share/zoneinfo).
+    #
+    # To set TZInfo to use one of the standard data source types, call
+    # \TZInfo::DataSource.set in one of the following ways:
+    #
+    #   TZInfo::DataSource.set(:ruby)
+    #   TZInfo::DataSource.set(:zoneinfo)
+    #   TZInfo::DataSource.set(:zoneinfo, zoneinfo_dir)
+    #
+    # \DataSource.set(:zoneinfo) will automatically search for the zoneinfo
+    # directory by checking the paths specified in 
+    # ZoneinfoDataSource.search_paths. ZoneinfoDirectoryNotFound will be raised
+    # if no valid zoneinfo directory could be found.
+    #
+    # \DataSource.set(:zoneinfo, zoneinfo_dir) uses the specified zoneinfo
+    # directory as the data source. If the directory is not a valid zoneinfo
+    # directory, an InvalidZoneinfoDirectory exception will be raised.
+    #
+    # Custom data sources can be created by subclassing TZInfo::DataSource and
+    # implementing the following methods:
+    #
+    # * \load_timezone_info
+    # * \timezone_identifiers
+    # * \data_timezone_identifiers
+    # * \linked_timezone_identifiers
+    # * \load_country_info
+    # * \country_codes
+    #
+    # To have TZInfo use the custom data source, call \DataSource.set 
+    # as follows:
+    #
+    #   TZInfo::DataSource.set(CustomDataSource.new)
+    #
+    # To avoid inconsistent data, \DataSource.set should be called before
+    # accessing any Timezone or Country data.
+    #
+    # If \DataSource.set is not called, TZInfo will use TZInfo::Data as the
+    # data source. If TZInfo::Data is not available (i.e. if 
+    # require 'tzinfo/data' fails), then TZInfo will search for a zoneinfo 
+    # directory instead (using the search path specified by
+    # TZInfo::ZoneinfoDataSource::DEFAULT_SEARCH_PATH).
+    def self.set(data_source_or_type, *args)
+      if data_source_or_type.kind_of?(DataSource)
+        @@instance = data_source_or_type
+      elsif data_source_or_type == :ruby
+        @@instance = RubyDataSource.new
+      elsif data_source_or_type == :zoneinfo
+        raise ArgumentError, "wrong number of arguments #{args.length} for 1" if args.length > 1
+        @@instance = ZoneinfoDataSource.new(*args)
+      else
+        raise ArgumentError, 'data_source_or_type must be a DataSource instance or a data source type (:ruby)'
+      end
+    end
+    
+    # Returns a TimezoneInfo instance for a given identifier. The TimezoneInfo
+    # instance should derive from either DataTimzoneInfo for timezones that
+    # define their own data or LinkedTimezoneInfo for links or aliases to
+    # other timezones.
+    #
+    # Raises InvalidTimezoneIdentifier if the timezone is not found or the 
+    # identifier is invalid.
+    def load_timezone_info(identifier)
+      raise InvalidDataSource, 'load_timezone_info not defined'
+    end
+    
+    # Returns an array of all the available timezone identifiers.
+    def timezone_identifiers
+      raise InvalidDataSource, 'timezone_identifiers not defined'
+    end
+    
+    # Returns an array of all the available timezone identifiers for
+    # data timezones (i.e. those that actually contain definitions).
+    def data_timezone_identifiers
+      raise InvalidDataSource, 'data_timezone_identifiers not defined'
+    end
+    
+    # Returns an array of all the available timezone identifiers that
+    # are links to other timezones.
+    def linked_timezone_identifiers
+      raise InvalidDataSource, 'linked_timezone_identifiers not defined'
+    end
+    
+    # Returns a CountryInfo instance for the given ISO 3166-1 alpha-2
+    # country code. Raises InvalidCountryCode if the country could not be found
+    # or the code is invalid.
+    def load_country_info(code)
+      raise InvalidDataSource, 'load_country_info not defined'
+    end
+    
+    # Returns an array of all the available ISO 3166-1 alpha-2
+    # country codes.
+    def country_codes
+      raise InvalidDataSource, 'country_codes not defined'
+    end
+    
+    # Returns the name of this DataSource.
+    def to_s
+      "Default DataSource"
+    end
+    
+    # Returns internal object state as a programmer-readable string.
+    def inspect
+      "#<#{self.class}>"
+    end
+    
+    private
+    
+    # Creates a DataSource instance for use as the default. Used if
+    # no preference has been specified manually.
+    def self.create_default_data_source
+      has_tzinfo_data = false
+      
+      begin
+        require 'tzinfo/data'
+        has_tzinfo_data = true
+      rescue LoadError
+      end
+    
+      return RubyDataSource.new if has_tzinfo_data
+      
+      begin
+        return ZoneinfoDataSource.new
+      rescue ZoneinfoDirectoryNotFound
+        raise DataSourceNotFound, 'No timezone data source could be found. To resolve this, either install TZInfo::Data (e.g. by running `gem install tzinfo-data`) or specify a zoneinfo directory using `TZInfo::DataSource.set(:zoneinfo, zoneinfo_path)`.'
+      end
+    end
+  end
+end

data/lib/tzinfo/data_timezone.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2006-2013 Philip Ross
+# Copyright (c) 2006-2010 Philip Ross
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -23,8 +23,6 @@
 module TZInfo
 
   # A Timezone based on a DataTimezoneInfo.
-  #
-  # @private
   class DataTimezone < InfoTimezone #:nodoc:
     
     # Returns the TimezonePeriod for the given UTC time. utc can either be

data/lib/tzinfo/data_timezone_info.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2006-2013 Philip Ross
+# Copyright (c) 2013 Philip Ross
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -21,204 +21,25 @@
 #++
 
 module TZInfo
-  # Thrown if no offsets have been defined when calling period_for_utc or
-  # periods_for_local. Indicates an error in the timezone data.
-  class NoOffsetsDefined < StandardError
-  end
-    
-  # Represents a (non-linked) timezone defined in a data module.
-  #
-  # @private
-  class DataTimezoneInfo < TimezoneInfo #:nodoc:
-            
-    # Constructs a new TimezoneInfo with its identifier.
-    def initialize(identifier)   
-      super(identifier)
-      @offsets = {}
-      @transitions = []
-      @previous_offset = nil
-      @transitions_index = nil
-    end
- 
-    # Defines a offset. The id uniquely identifies this offset within the
-    # timezone. utc_offset and std_offset define the offset in seconds of 
-    # standard time from UTC and daylight savings from standard time 
-    # respectively. abbreviation describes the timezone offset (e.g. GMT, BST,
-    # EST or EDT).
-    #
-    # The first offset to be defined is treated as the offset that applies
-    # until the first transition. This will usually be in Local Mean Time (LMT).
-    #
-    # ArgumentError will be raised if the id is already defined.
-    def offset(id, utc_offset, std_offset, abbreviation)
-      raise ArgumentError, 'Offset already defined' if @offsets.has_key?(id)
-      
-      offset = TimezoneOffsetInfo.new(utc_offset, std_offset, abbreviation)
-      @offsets[id] = offset
-      @previous_offset = offset unless @previous_offset
-    end
-    
-    # Defines a transition. Transitions must be defined in chronological order.
-    # ArgumentError will be raised if a transition is added out of order.
-    # offset_id refers to an id defined with offset. ArgumentError will be 
-    # raised if the offset_id cannot be found. numerator_or_time and
-    # denomiator specify the time the transition occurs as. See 
-    # TimezoneTransitionInfo for more detail about specifying times.
-    def transition(year, month, offset_id, numerator_or_time, denominator = nil)
-      offset = @offsets[offset_id]      
-      raise ArgumentError, 'Offset not found' unless offset
-            
-      if @transitions_index
-        if year < @last_year || (year == @last_year && month < @last_month)
-          raise ArgumentError, 'Transitions must be increasing date order'
-        end
-        
-        # Record the position of the first transition with this index.
-        index = transition_index(year, month)
-        @transitions_index[index] ||= @transitions.length
-                
-        # Fill in any gaps       
-        (index - 1).downto(0) do |i|
-          break if @transitions_index[i]
-          @transitions_index[i] = @transitions.length
-        end
-      else
-        @transitions_index = [@transitions.length]
-        @start_year = year
-        @start_month = month        
-      end
-      
-      @transitions << TimezoneTransitionInfo.new(offset, @previous_offset, 
-        numerator_or_time, denominator)
-      @last_year = year
-      @last_month = month             
-      @previous_offset = offset
-    end           
-    
+  # Represents a defined timezone containing transition data.
+  class DataTimezoneInfo < TimezoneInfo  
+  
     # Returns the TimezonePeriod for the given UTC time.
-    # Raises NoOffsetsDefined if no offsets have been defined.
     def period_for_utc(utc)
-      unless @transitions.empty?
-        utc = TimeOrDateTime.wrap(utc)               
-        index = transition_index(utc.year, utc.mon)
-        
-        start_transition = nil
-        start = transition_before_end(index)
-        if start
-          start.downto(0) do |i|
-            if @transitions[i].at <= utc
-              start_transition = @transitions[i]
-              break
-            end
-          end
-        end
-        
-        end_transition = nil
-        start = transition_after_start(index)      
-        if start
-          start.upto(@transitions.length - 1) do |i|
-            if @transitions[i].at > utc
-              end_transition = @transitions[i]
-              break
-            end
-          end
-        end
-               
-        if start_transition || end_transition
-          TimezonePeriod.new(start_transition, end_transition)
-        else
-          # Won't happen since there are transitions. Must always find one
-          # transition that is either >= or < the specified time.
-          raise 'No transitions found in search'
-        end        
-      else
-        raise NoOffsetsDefined, 'No offsets have been defined' unless @previous_offset        
-        TimezonePeriod.new(nil, nil, @previous_offset)
-      end
+      raise NotImplementedError, 'Subclasses must override period_for_utc'
     end
     
     # Returns the set of TimezonePeriods for the given local time as an array.    
     # Results returned are ordered by increasing UTC start date.
     # Returns an empty array if no periods are found for the given time.
-    # Raises NoOffsetsDefined if no offsets have been defined.    
     def periods_for_local(local)
-      unless @transitions.empty?
-        local = TimeOrDateTime.wrap(local)
-        index = transition_index(local.year, local.mon)
-        
-        result = []
-       
-        start_index = transition_after_start(index - 1)       
-        if start_index && @transitions[start_index].local_end > local           
-          if start_index > 0
-            if @transitions[start_index - 1].local_start <= local 
-              result << TimezonePeriod.new(@transitions[start_index - 1], @transitions[start_index])
-            end
-          else
-            result << TimezonePeriod.new(nil, @transitions[start_index])
-          end
-        end
-        
-        end_index = transition_before_end(index + 1)
-        
-        if end_index        
-          start_index = end_index unless start_index
-          
-          start_index.upto(transition_before_end(index + 1)) do |i|
-            if @transitions[i].local_start <= local
-              if i + 1 < @transitions.length
-                if @transitions[i + 1].local_end > local
-                  result << TimezonePeriod.new(@transitions[i], @transitions[i + 1])
-                end
-              else
-                result << TimezonePeriod.new(@transitions[i], nil)
-              end
-            end
-          end
-        end
-        
-        result
-      else
-        raise NoOffsetsDefined, 'No offsets have been defined' unless @previous_offset
-        [TimezonePeriod.new(nil, nil, @previous_offset)]
-      end
+      raise NotImplementedError, 'Subclasses must override periods_for_local'
     end
     
-    private
-      # Returns the index into the @transitions_index array for a given year 
-      # and month.
-      def transition_index(year, month)
-        index = (year - @start_year) * 2
-        index += 1 if month > 6
-        index -= 1 if @start_month > 6
-        index
-      end
-      
-      # Returns the index into @transitions of the first transition that occurs
-      # on or after the start of the given index into @transitions_index.
-      # Returns nil if there are no such transitions.
-      def transition_after_start(index)
-        if index >= @transitions_index.length
-          nil
-        else
-          index = 0 if index < 0
-          @transitions_index[index]
-        end
-      end
-      
-      # Returns the index into @transitions of the first transition that occurs
-      # before the end of the given index into @transitions_index.
-      # Returns nil if there are no such transitions.
-      def transition_before_end(index)
-        index = index + 1
-        
-        if index <= 0
-          nil
-        elsif index >= @transitions_index.length          
-          @transitions.length - 1
-        else      
-          @transitions_index[index] - 1          
-        end
-      end            
+    # Constructs a Timezone instance for the timezone represented by this
+    # DataTimezoneInfo.
+    def create_timezone
+      DataTimezone.new(self)
+    end
   end
 end

data/lib/tzinfo/info_timezone.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2006-2013 Philip Ross
+# Copyright (c) 2006-2010 Philip Ross
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -23,8 +23,6 @@
 module TZInfo
 
   # A Timezone based on a TimezoneInfo.
-  #
-  # @private
   class InfoTimezone < Timezone #:nodoc:
     
     # Constructs a new InfoTimezone with a TimezoneInfo instance.

data/lib/tzinfo/linked_timezone.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2006-2013 Philip Ross
+# Copyright (c) 2006-2010 Philip Ross
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -22,9 +22,6 @@
 
 module TZInfo
 
-  # A Timezone based on a LinkedTimezoneInfo.
-  #
-  # @private
   class LinkedTimezone < InfoTimezone #:nodoc:
     # Returns the TimezonePeriod for the given UTC time. utc can either be
     # a DateTime, Time or integer timestamp (Time.to_i). Any timezone 

data/lib/tzinfo/linked_timezone_info.rb

@@ -21,15 +21,13 @@
 #++
 
 module TZInfo
-  # Represents a linked timezone defined in a data module.
-  #
-  # @private
-  class LinkedTimezoneInfo < TimezoneInfo #:nodoc:
+  # Represents a timezone that is defined as a link or alias to another zone.
+  class LinkedTimezoneInfo < TimezoneInfo
         
     # The zone that provides the data (that this zone is an alias for).
     attr_reader :link_to_identifier
     
-    # Constructs a new TimezoneInfo with an identifier and the identifier
+    # Constructs a new LinkedTimezoneInfo with an identifier and the identifier
     # of the zone linked to.
     def initialize(identifier, link_to_identifier)
       super(identifier)
@@ -40,5 +38,11 @@ module TZInfo
     def inspect
       "#<#{self.class}: #@identifier,#@link_to_identifier>"
     end
+    
+    # Constructs a Timezone instance for the timezone represented by this
+    # DataTimezoneInfo.
+    def create_timezone
+      LinkedTimezone.new(self)
+    end
   end
 end

data/lib/tzinfo/offset_rationals.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2006-2013 Philip Ross
+# Copyright (c) 2006-2010 Philip Ross
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -26,9 +26,7 @@ module TZInfo
   
   # Provides a method for getting Rationals for a timezone offset in seconds.
   # Pre-reduced rationals are returned for all the half-hour intervals between
-  # -14 and +14 hours to avoid having to call gcd at runtime.
-  #
-  # @private
+  # -14 and +14 hours to avoid having to call gcd at runtime.  
   module OffsetRationals #:nodoc:
     @@rational_cache = {
       -50400 => RubyCoreSupport.rational_new!(-7,12),