timezone 0.6.0 → 0.99.0

data/lib/timezone/configure.rb

@@ -1,235 +1,256 @@
 require 'timezone/net_http_client'
 require 'timezone/lookup'
+require 'timezone/deprecate'
 
 module Timezone
-  # Configuration class for the Timezone gem.
-  #
-  # You'll want to sign up for a geonames username at
-  # {http://www.geonames.org/login Geonames}. Use the username to
-  # configure your application for latitude and longitude based
-  # timezone searches.
-  # Alternatively, you'll want to sign up for a Google api key at
-  # {https://code.google.com/apis/console/ Google}. Use the api key to
-  # configure your application for latitude and longitude based
-  # timezone searches.
-  #
-  # If you aren't going to initialize timezone objects based on lat,lng
-  # then this configuration is not necessary.
-  #
-  # @example
-  #     Timezone::Configure.begin do |c|
-  #       c.geonames_url = 'api.geonames.org'
-  #       c.username = 'foo-bar'
-  #       c.google_api_key = 'abc123'
-  #     end
+  # @deprecated `Timezone::Configure` will be removed in the release
+  #   of the `timezone gem. Use `Timezone::Lookup::config` instead.
   #
+  # The old way to configure this gem.
+  # rubocop:disable Style/ClassVars
   class Configure
-    # The Google API key
-    #
-    # @return [String]
-    #   the Google API key ('abc123')
+    DEPRECATE = '[DEPRECATED] `Timezone::Configure` will be removed ' \
+      'in the release of the `timezone gem. Use `Timezone::Lookup` ' \
+      'instead.'.freeze
+
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.google_api_key
-      @google_api_key ||= nil
+      @@google_api_key ||= nil
     end
 
-    # Google API key
-    #
-    # @param [String] api_key
-    #   the Google API key
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.google_api_key=(api_key)
-      @google_api_key = api_key
+      @@google_api_key = api_key
     end
 
-    # The Google Client ID (for enterprise)
-    #
-    # @return [String]
-    #   the Google Client ('abc123')
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.google_client_id
-      @google_client_id ||= nil
+      @@google_client_id ||= nil
     end
 
-    # Google Client ID (for enterprise)
-    #
-    # @param [String] client
-    #   the Google Client
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.google_client_id=(client)
-      @google_client_id = client
+      @@google_client_id = client
     end
 
-    # Use Google API if key has been set
-    #
-    # @return [Boolean]
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.use_google?
-      !!google_api_key
+      !google_api_key.nil?
     end
 
-    # Sign Google API request if client given (for enterprise)
-    #
-    # @return [Boolean]
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.use_google_enterprise?
-      use_google? && !!google_client_id
+      use_google? && !google_client_id.nil?
     end
 
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.lookup=(lookup)
       @lookup = lookup && lookup.new(self)
     end
 
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.lookup
       return @lookup if @lookup
 
       use_google? ? google_lookup : geonames_lookup
     end
 
+    # Responsible for mapping old configuration options to new
+    # configuration style for forwards-compatability with the
+    # updated Google lookup.
+    class GoogleConfigMapper
+      def initialize(config)
+        @config = config
+      end
+
+      def protocol; @config.protocol; end
+
+      def url; @config.url; end
+
+      def http_client; @config.http_client; end
+
+      def api_key; @config.google_api_key; end
+
+      def client_id; @config.google_client_id; end
+
+      def request_handler; nil; end
+    end
+
+    private_constant :GoogleConfigMapper
+
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.google_lookup
-      @google_lookup ||= Timezone::Lookup::Google.new(self)
+      @google_lookup ||=
+        Timezone::Lookup::Google.new(GoogleConfigMapper.new(self))
+    end
+
+    # Responsible for mapping old configuration options to new
+    # configuration style for forwards-compatability with the
+    # updated Geonames lookup.
+    class GeonamesConfigMapper
+      def initialize(config)
+        @config = config
+      end
+
+      def protocol; @config.protocol; end
+
+      def url; @config.url; end
+
+      def username; @config.username; end
+
+      def http_client; @config.http_client; end
+
+      def request_handler; nil; end
     end
 
+    private_constant :GeonamesConfigMapper
+
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.geonames_lookup
-      @geonames_lookup ||= Timezone::Lookup::Geonames.new(self)
+      @geonames_lookup ||=
+        Timezone::Lookup::Geonames.new(GeonamesConfigMapper.new(self))
     end
 
-    # The Geonames API URL
-    #
-    # @return [String]
-    #   the Geonames API URL ('api.geonames.org')
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.geonames_url
       @@geonames_url ||= 'api.geonames.org'
     end
 
-    # The Geonames API URL
-    #
-    # @param [String] url
-    #   the Geonames API URL
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.geonames_url=(url)
       @@geonames_url = url
     end
 
-    class << self
-      alias url= geonames_url=
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
+    def self.url=(url)
+      self.geonames_url = url
     end
 
-    # The Google API URL
-    #
-    # @return [String]
-    #   the Google API URL ('maps.googleapis.com')
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.google_url
       @@google_url ||= 'maps.googleapis.com'
     end
 
-    # The Google API URL
-    #
-    # @param [String] url
-    #   the Google API URL
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.google_url=(url)
       @@google_url = url
     end
 
-    # Use Google URL if key has been set else use Geonames URL
-    #
-    # @return [String]
-    #   the Google or Geonames API URL
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.url
       use_google? ? google_url : geonames_url
     end
 
-    # The Geonames API HTTP protocol
-    #
-    # @param [String] protocol
-    #   the Geonames API HTTP procotol
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.geonames_protocol=(protocol)
       @@geonames_protocol = protocol
     end
 
-    # The Geonames API HTTP protocol
-    #
-    # @return [String]
-    #   the Geonames API HTTP protocol ('http')
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.geonames_protocol
       @@geonames_protocol ||= 'http'
     end
 
-    # The Google API HTTP protocol
-    #
-    # @param [String] protocol
-    #   the Google API HTTP procotol
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.google_protocol=(protocol)
       @@google_protocol = protocol
     end
 
-    # The Google API HTTP protocol
-    #
-    # @return [String]
-    #   the Google API HTTP protocol ('https')
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.google_protocol
       @@google_protocol ||= 'https'
     end
 
-    # Use Google protocol if key has been set else use Geonames protocol
-    #
-    # @return [String]
-    #   the Google or Geonames API protocol
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.protocol
       use_google? ? google_protocol : geonames_protocol
     end
 
-    # The HTTP client that handles requests to Geonames and Google
-    #
-    # @return [Object]
-    #   the HTTP client ({Timezone::NetHTTPClient Timezone::NetHTTPClient})
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.http_client
       @@http_client ||= Timezone::NetHTTPClient
     end
 
-    # The HTTP client that handles requests to Geonames and Google
-    #
-    # @param [Object] client
-    #   the HTTP client that handles requests to Geonames and Google
-    #
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.http_client=(client)
       @@http_client = client
     end
 
-    # The Geonames API username
-    #
-    # @return [String]
-    #   the Geonames API username ('foo-bar')
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.username
       @@username ||= nil
     end
 
-    # The Geonames API username
-    #
-    # @param [String] username
-    #   the Geonames API username
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.username=(username)
       @@username = username
     end
 
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.begin
+      Deprecate.call(self, :begin, DEPRECATE)
       yield self
     end
 
-    def self.replace(what, with = Hash.new)
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
+    def self.replace(what, with = {})
       replacements # instantiate @@replacements
       @@replacements[what] = with[:with]
     end
 
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.replacements
       @@replacements ||= {}
     end
 
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.default_for_list
       @@default_list ||= nil
     end
 
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.default_for_list=(*list)
       @@default_list = list.flatten!
     end
 
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.order_list_by
       @@order_by ||= :utc_offset
     end
 
+    # @deprecated `Timezone::Configure` will be removed in the release
+    #   of the `timezone gem. Use `Timezone::Lookup instead.
     def self.order_list_by=(order)
       @@order_by = order
     end

data/lib/timezone/deprecate.rb

@@ -0,0 +1,32 @@
+module Timezone
+  # This class provides a way to set a custom hook for deprecations.
+  module Deprecate
+    class << self
+      # Set the custom deprecation callback. By default this
+      # issues a deprecation warning.
+      #
+      # @param callback [#call] the custom callback
+      #
+      # @example Send a message to StatsD
+      #   Timezone::Deprecate.callback = lambda do |klass, method, _|
+      #     StatsD.increment(sanitize(klass, method))
+      #   end
+      #
+      # @example Send a message to a custom logger
+      #   Timezone::Deprecate.callback = lambda do |klass, method, msg|
+      #     MyLogger.log("[#{klass} : #{method}] #{msg}")
+      #   end
+      attr_writer :callback
+
+      # @!visibility private
+      def callback
+        @callback || -> (_, _, message) { warn(message) }
+      end
+
+      # @!visibility private
+      def call(klass, method, message)
+        callback && callback.call(klass, method, message)
+      end
+    end
+  end
+end

data/lib/timezone/error.rb

@@ -1,5 +1,6 @@
 module Timezone
-  # Error messages that can be raised by this gem. To catch any related error message, simply use Error::Base.
+  # Error messages that can be raised by this gem. To catch any
+  # related error message, use Error::Base.
   #
   #   begin
   #     ...
@@ -7,13 +8,23 @@ module Timezone
   #     puts "Timezone Error: #{e.message}"
   #   end
   module Error
+    # Top-level error. All other timezone errors subclass this one.
     class Base < StandardError; end
+    # Indicates an invalid timezone name.
     class InvalidZone < Base; end
+    # @deprecated this class will be removed in the next release of the gem.
     class NilZone < Base; end
-    class GeoNames < Base; end
-    class Google < Base; end
+    # Indicates a lookup failure.
+    class Lookup < Base; end
+    # Indicates an error during lookup using the geonames API.
+    class GeoNames < Lookup; end
+    # Indicates an error during lookup using the google API.
+    class Google < Lookup; end
+    # @deprecated this class will be removed in the next release of the gem.
     class ParseTime < Base; end
-    class Test < Base ; end
-    class InvalidConfig < Base ; end
+    # Indicates a missing stub during a test lookup.
+    class Test < Lookup; end
+    # Indicates an invalid configuration.
+    class InvalidConfig < Base; end
   end
 end

data/lib/timezone/loader.rb

@@ -1,27 +1,34 @@
 require 'timezone/error'
 
-module Timezone
+module Timezone # rubocop:disable Style/Documentation
+  # Responsible for loading and parsing timezone data from files.
   module Loader
-    ZONE_FILE_PATH = File.expand_path(File.dirname(__FILE__)+'/../../data')
+    ZONE_FILE_PATH = File.expand_path(File.dirname(__FILE__) + '/../../data')
     SOURCE_BIT = 0
 
     class << self
-      def load(zone)
+      def load(name)
+        raise ::Timezone::Error::InvalidZone unless valid?(name)
+
         @rules ||= {}
-        @rules[zone] ||= parse_zone_data(get_zone_data(zone))
+        @rules[name] ||= parse_zone_data(get_zone_data(name))
       end
 
       def names
-        @@names ||= parse_zone_names
+        @names ||= parse_zone_names
+      end
+
+      def valid?(name)
+        names.include?(name)
       end
 
       private
 
       def parse_zone_names
-        files = Dir[File.join(ZONE_FILE_PATH, "**/*")].map do |file|
+        files = Dir[File.join(ZONE_FILE_PATH, '**/*')].map do |file|
           next if File.directory?(file)
 
-          file.gsub("#{ZONE_FILE_PATH}/", '')
+          file.sub("#{ZONE_FILE_PATH}/", '')
         end
 
         files.compact
@@ -35,7 +42,7 @@ module Timezone
           source = source.to_i
           dst = dst == '1'
           offset = offset.to_i
-          source = rules.last[SOURCE_BIT]+source if rules.last
+          source = rules.last[SOURCE_BIT] + source if rules.last
           rules << [source, name, dst, offset]
         end
 
@@ -43,15 +50,11 @@ module Timezone
       end
 
       # Retrieve the data from a particular time zone
-      def get_zone_data(zone)
-        file = File.join(ZONE_FILE_PATH, zone)
-
-        if !File.exists?(file)
-          raise Timezone::Error::InvalidZone, "'#{zone}' is not a valid zone."
-        end
-
-        File.read(file)
+      def get_zone_data(name)
+        File.read(File.join(ZONE_FILE_PATH, name))
       end
     end
   end
+
+  private_constant :Loader
 end

data/lib/timezone/lookup/basic.rb

@@ -2,9 +2,13 @@ require 'timezone/error'
 
 module Timezone
   module Lookup
+    # @abstract Subclass and override {#lookup} to implement
+    #   a custom Lookup class.
     class Basic
       attr_reader :config
 
+      # @param config [#protocol, #url, #request_handler] a configuration
+      #   object
       def initialize(config)
         if config.protocol.nil?
           raise(::Timezone::Error::InvalidConfig, 'missing protocol')
@@ -17,11 +21,29 @@ module Timezone
         @config = config
       end
 
+      # Returns an instance of the request handler.
+      #
+      # @return [#get] an instance of a request handler
       def client
-        @client ||= config.http_client.new(config.protocol, config.url)
+        # TODO: Remove http_client once on 1.0.0
+        @client ||=
+          if !config.request_handler.nil?
+            config.request_handler.new(config)
+          else
+            config.http_client.new(config.protocol, config.url)
+          end
       end
 
-      def lookup(lat, lng)
+      # Returns a timezone name for a given lat, long pair.
+      #
+      # @param lat [Double] latitude coordinate
+      # @param long [Double] longitude coordinate
+      # @return [String] the timezone name
+      # @return [nil] if the lat, long pair does not resolve to an
+      #   actual timezone
+      # @raise [Timezone::Error::Base] if an error occurred while
+      #   while performing the lookup
+      def lookup(_lat, _long)
         raise NoMethodError, 'lookup is not implemented'
       end
     end

data/lib/timezone/lookup/geonames.rb

@@ -5,17 +5,21 @@ require 'uri'
 
 module Timezone
   module Lookup
+    # @!visibility private
     class Geonames < ::Timezone::Lookup::Basic
       def initialize(config)
         if config.username.nil?
-          raise(::Timezone::Error::InvalidConfig, 'missing username')
+          raise(::Timezone::Error::InvalidConfig, 'missing username'.freeze)
         end
 
+        config.protocol ||= 'http'.freeze
+        config.url ||= 'api.geonames.org'.freeze
+
         super
       end
 
-      def lookup(lat, lng)
-        response = client.get(url(lat, lng))
+      def lookup(lat, long)
+        response = client.get(url(lat, long))
 
         return unless response.code =~ /^2\d\d$/
 
@@ -32,10 +36,10 @@ module Timezone
 
       private
 
-      def url(lat, lng)
+      def url(lat, long)
         query = URI.encode_www_form(
           'lat' => lat,
-          'lng' => lng,
+          'lng' => long,
           'username' => config.username)
         "/timezoneJSON?#{query}"
       end

data/lib/timezone/lookup/google.rb

@@ -8,53 +8,62 @@ require 'cgi'
 
 module Timezone
   module Lookup
+    # @!visibility private
     class Google < ::Timezone::Lookup::Basic
       def initialize(config)
-        if config.google_api_key.nil?
-          raise(::Timezone::Error::InvalidConfig, 'missing api key')
+        if config.api_key.nil?
+          raise(::Timezone::Error::InvalidConfig, 'missing api key'.freeze)
         end
+
+        config.protocol ||= 'https'.freeze
+        config.url ||= 'maps.googleapis.com'.freeze
+
         super
       end
 
-      def lookup(lat,lng)
-        response = client.get(url(lat,lng))
+      def lookup(lat, long)
+        response = client.get(url(lat, long))
 
-        if response.code == '403'
-          raise(Timezone::Error::Google, '403 Forbidden')
+        if response.code == '403'.freeze
+          raise(Timezone::Error::Google, '403 Forbidden'.freeze)
         end
 
         return unless response.code =~ /^2\d\d$/
         data = JSON.parse(response.body)
 
-        if data['status'] != 'OK'
+        if data['status'.freeze] != 'OK'.freeze
           raise(Timezone::Error::Google, data['errorMessage'])
         end
 
-        data['timeZoneId']
+        data['timeZoneId'.freeze]
       rescue => e
         raise(Timezone::Error::Google, e.message)
       end
 
       private
 
+      def use_google_enterprise?
+        !config.client_id.nil?
+      end
+
       def authorize(url)
-        if config.use_google_enterprise?
-          url += "&client=#{CGI.escape(config.google_client_id)}"
+        if use_google_enterprise?
+          url += "&client=#{CGI.escape(config.client_id)}"
 
           sha1 = OpenSSL::Digest.new('sha1')
-          binary_key = Base64.decode64(config.google_api_key.tr('-_','+/'))
+          binary_key = Base64.decode64(config.api_key.tr('-_', '+/'))
           binary_signature = OpenSSL::HMAC.digest(sha1, binary_key, url)
-          signature = Base64.encode64(binary_signature).tr('+/','-_').strip
+          signature = Base64.encode64(binary_signature).tr('+/', '-_').strip
 
           url + "&signature=#{signature}"
         else
-          url + "&key=#{config.google_api_key}"
+          url + "&key=#{config.api_key}"
         end
       end
 
-      def url(lat,lng)
+      def url(lat, long)
         query = URI.encode_www_form(
-          'location' => "#{lat},#{lng}",
+          'location' => "#{lat},#{long}",
           'timestamp' => Time.now.to_i)
 
         authorize("/maps/api/timezone/json?#{query}")