tzinfo 0.2.2 → 0.3.0

data/Rakefile

@@ -3,10 +3,12 @@
 # rake test - Runs all test cases.
 # rake package - Runs test cases and builds packages for distribution.
 # rake rdoc - Builds API documentation in doc dir.
-# rake build_tz_classes - Builds Timezone and Country classes. Expects to find
-#   source data in ../data.
-# rake build_tz_class zone=Zone/Name - Builds single Timezone class. Expects to
-#   find source data in ../data.
+# rake build_tz_modules - Builds Timezone modules and the Country index. 
+#   Expects to find source data in ../data.
+# rake build_tz_module zone=Zone/Name - Builds a single Timezone module. 
+#   Expects to find source data in ../data.
+# rake build_countries - Builds the Country index.
+#   Expects to find source data in ../data.
 
 require 'rake'
 require 'rake/testtask'
@@ -14,7 +16,7 @@ require 'rake/rdoctask'
 require 'rake/gempackagetask'
 require 'fileutils'
 
-PKG_VERSION = "0.2.2"
+PKG_VERSION = "0.3.0"
 PKG_FILES = FileList[
   'CHANGES',
   'LICENSE',
@@ -25,6 +27,9 @@ PKG_FILES = FileList[
   'test/**/*'
 ]
 
+RDOC_OPTIONS = %w[--exclude definitions --exclude indexes]
+RDOC_EXTRA_FILES = %w[README CHANGES]
+
 BUILD_TZ_CLASSES_DIR = 'lib/tzinfo.build_tz_classes'
 
 SPEC = Gem::Specification.new do |s|
@@ -40,8 +45,9 @@ SPEC = Gem::Specification.new do |s|
   end
   s.require_path = "lib"
   s.autorequire = "tzinfo"  
-  s.has_rdoc = false
-  s.extra_rdoc_files = ["README","CHANGES"]
+  s.has_rdoc = true
+  s.extra_rdoc_files = RDOC_EXTRA_FILES
+  s.rdoc_options = RDOC_OPTIONS
   s.rubyforge_project = "tzinfo"
 end
 
@@ -65,12 +71,13 @@ end
 Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_dir = 'doc'
   rdoc.title = "TZInfo"
-  rdoc.options << '--inline-source'  
-  rdoc.rdoc_files.include('README', 'CHANGES') 
+  rdoc.options << '--inline-source'
+  rdoc.options.concat RDOC_OPTIONS
+  rdoc.rdoc_files.include(*RDOC_EXTRA_FILES) 
   rdoc.rdoc_files.include('lib')  
 end
 
-task :build_tz_classes do
+task :build_tz_modules do
   require 'lib/tzinfo/tzdataparser'
   
   FileUtils.mkdir_p(BUILD_TZ_CLASSES_DIR)
@@ -78,7 +85,7 @@ task :build_tz_classes do
     p = TZInfo::TZDataParser.new('../data', BUILD_TZ_CLASSES_DIR)
     p.execute
     
-    ['countries', 'definitions'].each {|dir|
+    ['indexes', 'definitions'].each {|dir|
       sync_svn("#{BUILD_TZ_CLASSES_DIR}/#{dir}", "lib/tzinfo/#{dir}")
     }        
   ensure
@@ -154,10 +161,18 @@ def exec_svn(params)
   raise "SVN exited with status #$?" if $? != 0  
 end
 
-task :build_tz_class do
+task :build_tz_module do
   require 'lib/tzinfo/tzdataparser'
   p = TZInfo::TZDataParser.new('../data', 'lib/tzinfo')
   p.generate_countries = false
   p.only_zones = [ENV['zone']]
   p.execute
 end
+
+task :build_countries do
+  require 'lib/tzinfo/tzdataparser'
+  p = TZInfo::TZDataParser.new('../data', 'lib/tzinfo')
+  p.generate_countries = true
+  p.generate_zones = false
+  p.execute
+end

data/lib/tzinfo.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2005 Philip Ross
+# Copyright (c) 2005-2006 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
@@ -27,4 +27,7 @@ $:.unshift(File.dirname(__FILE__)) unless
 
 require 'tzinfo/timezone'
 require 'tzinfo/country'
-require 'tzinfo/tzdataparser'
+require 'tzinfo/tzdataparser'
+require 'tzinfo/timezone_proxy'
+require 'tzinfo/data_timezone'
+require 'tzinfo/linked_timezone'

data/lib/tzinfo/country.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2005 Philip Ross
+# Copyright (c) 2005-2006 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
@@ -20,6 +20,7 @@
 # THE SOFTWARE.
 #++
 
+require 'tzinfo/country_info'
 require 'tzinfo/timezone'
 
 module TZInfo
@@ -31,63 +32,66 @@ module TZInfo
   # For example:
   #
   #  us = Country.get('US')
-  #  puts us.zone_identifiers
-  #  puts us.zones    
+  #  us.zone_identifiers
+  #  us.zones
+  #  us.zone_info
   class Country
     include Comparable
     
-    # Cache of loaded countries by code to avoid using require if a country
-    # has already been loaded.
-    @@loaded_countries = {}
+    # Defined countries.
+    @@countries = {}
     
-    # Gets a Country by its ISO 3166 code. Raising an exception if it couldn't
-    # be found.
+    # Whether the countries index has been loaded yet.
+    @@index_loaded = false
+    
+    # Gets a Country by its ISO 3166 code. Raises an InvalidCountryCode 
+    # exception if it couldn't be found.
     def self.get(identifier)
-      instance = @@loaded_countries[identifier]
-      if instance.nil?     
-        raise InvalidCountryCode.new, 'Invalid identifier' if identifier !~ /^[A-Z]{2}$/
-        begin
-          require "tzinfo/countries/#{identifier}"
-          instance = Countries.const_get(identifier).instance
-          @@loaded_countries[instance.code] = instance
-        rescue LoadError, NameError => e
-          raise InvalidCountryCode, e.message
-        end
-      end
+      instance = @@countries[identifier]
+      
+      unless instance
+        load_index
+        info = Indexes::Countries.countries[identifier]        
+        raise InvalidCountryCode.new, 'Invalid identifier' unless info
+        instance = Country.new(info)
+        @@countries[identifier] = instance
+      end      
       
-      instance
+      instance        
     end
     
-    # If identifier is nil calls super(), else calls get(identifier).
-    def self.new(identifier = nil)
-      if identifier
-        get(identifier)
+    # If identifier is a CountryInfo object, initializes the Country instance, 
+    # otherwise calls get(identifier).
+    def self.new(identifier)      
+      if identifier.kind_of?(CountryInfo)
+        instance = super()
+        instance.send :setup, identifier
+        instance
       else
-        super()
+        get(identifier)
       end
     end
     
     # Returns an Array of all the valid country codes.
     def self.all_codes
-      require 'tzinfo/countries/Index'
-      Countries::Index.all_codes
+      load_index
+      Indexes::Countries.countries.keys
     end
     
     # Returns an Array of all the defined Countries.
     def self.all
-      all_codes.collect {|code|
-        get(code)
-      }
+      load_index
+      Indexes::Countries.countries.keys.collect {|code| get(code)}
     end       
     
     # The ISO 3166 country code.
     def code
-      'Unknown'
+      @info.code
     end
     
     # The name of the country.
     def name
-      'Unknown'
+      @info.name
     end
     
     # Alias for name.
@@ -95,75 +99,81 @@ module TZInfo
       name
     end
     
-    # Array of Timezone identifiers for the country.
-    def zone_names
-      []
+    # Returns internal object state as a programmer-readable string.
+    def inspect
+      "#<#{self.class}: #{@info.code}>"
     end
     
-    # Array of Timezone identifiers for the country.
+    # Returns a frozen array of all the zone identifiers for the country. These
+    # are in an order that
+    #   (1) makes some geographical sense, and
+    #   (2) puts the most populous zones first, where that does not contradict (1).
     def zone_identifiers
-      zone_names
+      @info.zone_identifiers
     end
+    alias zone_names zone_identifiers
     
     # An array of all the Timezones for this country. Returns TimezoneProxy
     # objects to avoid the overhead of loading Timezone definitions until
-    # a conversion is actually required.
+    # a conversion is actually required. The Timezones are returned in an order
+    # that
+    #   (1) makes some geographical sense, and
+    #   (2) puts the most populous zones first, where that does not contradict (1).
     def zones
-      zone_names.collect {|zone_name|
-        TimezoneProxy.new(zone_name)
+      zone_identifiers.collect {|id|
+        Timezone.get_proxy(id)        
       }
-    end        
+    end
     
-    # Two Countries are considered to be equal if their codes are equal.
-    def ==(c)
-      code == c.code
+    # Returns a frozen array of all the timezones for the for the country as
+    # CountryTimezone instances (containing extra information about each zone). 
+    # These are in an order that
+    #   (1) makes some geographical sense, and
+    #   (2) puts the most populous zones first, where that does not contradict (1).
+    def zone_info
+      @info.zones
+    end
+        
+    # Compare two Countries based on their code. Returns -1 if c is less
+    # than self, 0 if c is equal to self and +1 if c is greater than self.
+    def <=>(c)
+      code <=> c.code
     end
     
-    # Compare two Countries based on their code. Returns -1 if tz is less
-    # than self, 0 if tz is equal to self and +1 if tz is greater than self.
-    def <=>(tz)
-      code <=> tz.code
+    # Returns true if and only if the code of c is equal to the code of this
+    # Country.
+    def eql?(c)
+      self == c
     end
-            
-    protected
-      def self.setup
-        class_eval <<CODE
-            @@zone_names = []
-            @@instance = new
-            
-            def zone_names
-              @@zone_names
-            end            
-            
-            def code
-              @@code
-            end
-            
-            def name
-              @@name
-            end
-                        
-            def self.instance
-              @@instance
-            end 
-            
-            protected
-              def self.add_zone(zone_name)              
-                @@zone_names << zone_name
-              end
-              
-              def self.zones_added
-                @@zone_names.freeze
-              end
-              
-              def self.set_code(code)
-                @@code = code
-              end
-              
-              def self.set_name(name)
-                @@name = name
-              end                     
-CODE
-      end           
-  end    
+    
+    # Returns a hash value for this Country.
+    def hash
+      code.hash
+    end
+    
+    # Dumps this Country for marshalling.
+    def _dump(limit)
+      code
+    end
+    
+    # Loads a marshalled Country.
+    def self._load(data)
+      Country.get(data)
+    end
+    
+    private
+      # Loads in the index of countries if it hasn't already been loaded.
+      def self.load_index
+        unless @@index_loaded
+          require 'tzinfo/indexes/countries'
+          @@index_loaded = true
+        end        
+      end     
+      
+      # Called by Country.new to initialize a new Country instance. The info
+      # parameter is a CountryInfo that defines the country.
+      def setup(info)
+        @info = info        
+      end
+  end 
 end

data/lib/tzinfo/country_index_definition.rb

@@ -0,0 +1,50 @@
+#--
+# Copyright (c) 2006 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.
+#++
+
+require 'tzinfo/country_info'
+
+module TZInfo
+  # The country index file includes CountryIndexDefinition which provides
+  # a country method used to define each country in the index.
+  module CountryIndexDefinition #:nodoc:
+    def self.append_features(base)
+      super
+      base.extend(ClassMethods)
+    end
+    
+    module ClassMethods #:nodoc:
+      # Defines a country with an ISO 3166 country code, name and block. The
+      # block will be evaluated to obtain all the timezones for the country.
+      # Calls Country.country_defined with the definition of each country.
+      def country(code, name, &block)
+        @countries = {} unless @countries
+        @countries[code] = CountryInfo.new(code, name, &block)      
+      end
+      
+      # Returns a frozen hash of all the countries that have been defined in
+      # the index.
+      def countries
+        @countries.freeze
+      end
+    end
+  end
+end

data/lib/tzinfo/country_info.rb

@@ -0,0 +1,82 @@
+#--
+# Copyright (c) 2006 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.
+#++
+
+require 'tzinfo/country_timezone'
+
+module TZInfo  
+  # Class to store the data loaded from the country index. Instances of this
+  # class are passed to the blocks in the index that define timezones.
+  class CountryInfo #:nodoc:
+    attr_reader :code
+    attr_reader :name
+    
+    # Constructs a new CountryInfo with an ISO 3166 country code, name and 
+    # block. The block will be evaluated to obtain the timezones for the country
+    # (when they are first needed).
+    def initialize(code, name, &block)
+      @code = code
+      @name = name
+      @block = block
+      @zones = nil
+      @zone_identifiers = nil
+    end
+    
+    # Called by the index data to define a timezone for the country.
+    def timezone(identifier, latitude_numerator, latitude_denominator, 
+                 longitude_numerator, longitude_denominator, description = nil)
+      # Currently only store the identifiers.
+      @zones << CountryTimezone.new(identifier, latitude_numerator, 
+        latitude_denominator, longitude_numerator, longitude_denominator,
+        description)     
+    end
+    
+    # Returns a frozen array of all the zone identifiers for the country. These
+    # are in the order they were added using the timezone method.
+    def zone_identifiers
+      unless @zone_identifiers
+        @zone_identifiers = zones.collect {|zone| zone.identifier}
+        @zone_identifiers.freeze
+      end
+      
+      @zone_identifiers
+    end
+    
+    # Returns internal object state as a programmer-readable string.
+    def inspect
+      "#<#{self.class}: #@code>"
+    end
+    
+    # Returns a frozen array of all the timezones for the for the country as
+    # CountryTimezone instances. These are in the order they were added using 
+    # the timezone method.
+    def zones
+      unless @zones
+        @zones = []
+        @block.call(self) if @block
+        @block = nil
+        @zones.freeze
+      end
+      
+      @zones
+    end    
+  end
+end