address_geocoder 0.0.1

data/lib/address_geocoder.rb

@@ -0,0 +1,11 @@
+require 'yaml'
+require 'maps_api'
+
+# Namespace for classes and modules directly relating to the gem
+# @since 0.0.1
+module AddressGeocoder
+  # The collection of countries supported by this gem
+  COUNTRIES = YAML.load_file('countries.yaml')
+  # The regex used to check the state and city for validity
+  REGEX = /\A[a-zA-Z\ ]*\z/
+end

data/lib/address_geocoder/client.rb

@@ -0,0 +1,180 @@
+require 'address_geocoder/error'
+
+module AddressGeocoder
+  # @abstract Abstract base class for interacting with maps APIs
+  class Client
+    # @!attribute api_key
+    # @return [String] the user's key to the chosen maps API
+    attr_accessor :api_key
+    # @!attribute language
+    # @return [String] the language in which to return the address
+    attr_accessor :language
+    # @!attribute [r] address
+    # @return [Hash] our address object. It contains country, state, city,
+    #   postal code, and street.
+    attr_reader :address
+    # @!attribute [r] response
+    # @return [Hash] the response from the maps API
+    attr_reader :response
+    # @!attribute [r] former_address
+    # @return [Hash] the address that was last called from the maps API
+    attr_reader :former_address
+
+    def initialize(args = {})
+      @address = {}
+      assign_initial(args)
+    end
+
+    # Determines whether an address is likely to be valid or not
+    # @return [Boolean] true, or false if address is likely to be invalid.
+    # @todo .certain? should be a parser method
+    def valid_address?
+      check_country
+      if values_changed?
+        reset
+        @requester.make_call
+      end
+      @requester.success? && @requester.certain?
+    end
+
+    # Gathers a list of matching addresses from the maps API
+    # @return [Array<Hash>] a list of matching addresses
+    def suggested_addresses
+      check_country
+      if values_changed?
+        reset
+        @requester.make_call
+      end
+      return false unless @requester.success?
+      @requester.array_result.map do |result|
+        @parser.fields = result
+        @parser.parse_response
+      end
+    end
+
+    # @abstract Assigns the entered variables to their proper instance variables
+    # @param args [Hash] arguments to pass to the class
+    # @option args [String] :country a country's alpha2
+    # @option args [String] :api_key the user's key to the chosen maps API
+    # @option args [String] :state the state of the address to be validated
+    # @option args [String] :city the city of the address to be validated
+    # @option args [String] :postal_code the postal code of the address to be
+    #   validated
+    # @option args [String] :street the street of the address to be validated
+    # @option args [String] :language (en) the language in which to return the
+    #   address
+    # @return [void]
+    def assign_initial(args)
+      raise NeedToOveride, 'assign_initial' unless @requester && @parser
+      Client.instance_methods(false).each do |var|
+        next if var.to_s[/\=/].nil?
+        value = args[var.to_s.tr('=', '').to_sym].to_s
+        next unless value
+        send(var, value)
+      end
+    end
+
+    # Matches the given alpha2 to a yaml country and assigns it to the address
+    # object
+    # @param str [String] a country's alpha2
+    # @return [Hash, nil] a country object from the yaml, or nil if the provided
+    #   alpha2 could not be matched.
+    def country=(str)
+      if COUNTRIES[str]
+        @address[:country]          = COUNTRIES[str]
+        @address[:country][:alpha2] = str
+      else
+        @address[:country] = nil
+      end
+      @address[:country]
+    end
+
+    # Assigns the given state to the address object if it passes verification
+    # @param str [String] a state name
+    # @return [String, nil] the entered state, or nil if the provided string
+    #   could not be verified.
+    def state=(str)
+      @address[:state] = simple_check_and_assign!(str)
+    end
+
+    # Assigns the given city to the address object if it passes verification
+    # @param str [String] a city name
+    # @return [String, nil] the entered city, or nil if the provided string
+    #   could not be verified.
+    def city=(str)
+      @address[:city] = simple_check_and_assign!(str)
+    end
+
+    # Assigns the given postal code to the address object if it passes
+    # verification
+    # @param str [String] a postal code
+    # @return [String, nil] the entered postal code, or nil if the provided
+    #   string could not be verified.
+    def postal_code=(str)
+      @address[:postal_code] = pc_check_and_assign!(str)
+    end
+
+    # Assigns the given street to the address object if it passes
+    # verification
+    # @param str [String] a street
+    # @return [String, nil] the entered street, or nil if the provided
+    #   string was empty.
+    def street=(str)
+      @address[:street] = nil
+      @address[:street] = str unless str.empty?
+    end
+
+    private
+
+    # Determines whether the given alpha2 exists in the countries yaml
+    # @raise [ArgumentError] if the given value is not an alpha2 or does not
+    #   match any country in the yaml
+    # @return [void]
+    def check_country
+      raise ArgumentError, 'Invalid country' unless @address[:country]
+    end
+
+    # Resets the former address to new data
+    # @return [void]
+    def reset
+      @former_address     = @address
+      @parser.address     = @address
+      @requester.address  = @address
+      @requester.language = @language
+      @requester.api_key  = @api_key
+    end
+
+    # Determines whether the inputted address values have changed in any way
+    # @return [Boolean] true, or false if nothing has been called or the
+    #   current address information does not match the information from when the
+    #   maps API was last called
+    def values_changed?
+      return true unless @response
+      @address != @former_address
+    end
+
+    # Determines whether the given city/state is valid or not
+    # @param var [String] a city/state name
+    # @return [String, nil] the given city/state, or false if it does not pass
+    #   the Regex
+    def simple_check_and_assign!(var)
+      var if var.to_s[REGEX] != ''
+    end
+
+    # Determines whether the given postal code is valid or not
+    # @note validations include checking length, whether or not the given
+    #   country has a postal code, and checking to make sure the postal code is
+    #   not all one letter or all 0.
+    # @param postal_code [String, Integer] a postal code
+    # @return [String, nil] the given postal code as a string, or nil if it is
+    #   not valid.
+    def pc_check_and_assign!(postal_code)
+      pc = postal_code.to_s.tr(' ', '')
+      return nil unless @address.fetch(:country).fetch(:has_postal_code)
+      return nil if pc.length < 3
+      all_one_char = pc.delete(pc[0]) == ''
+      return nil if all_one_char && !(pc[0].to_i.in? Array(1..9))
+      pc
+    end
+  end
+end

data/lib/address_geocoder/error.rb

@@ -0,0 +1,31 @@
+module AddressGeocoder
+  # @abstract Abstract base class for errors
+  class Error < RuntimeError
+  end
+
+  # Class that defines an error, to be thrown when a method needs to be
+  # overwritten by a child class.
+  class NeedToOveride < Error
+    def initialize(msg = nil)
+      @msg = msg
+    end
+
+    def message
+      msg = 'This Method Needs To Be Overrided'
+      @msg ? "#{msg}: #{@msg}" : msg
+    end
+  end
+
+  # Class that defines an error representing a failure in connection with a
+  # third party Maps API
+  class ConnectionError < Error
+    def initialize(msg = nil)
+      @msg = msg
+    end
+
+    def message
+      msg = 'Failed To Connect'
+      @msg ? "#{msg}: #{@msg}" : msg
+    end
+  end
+end

data/lib/address_geocoder/parser.rb

@@ -0,0 +1,24 @@
+require 'address_geocoder/error'
+
+module AddressGeocoder
+  # @abstract Abstract base class for parsing maps API responses
+  class Parser
+    # @!attribute [w] address
+    # @return [Hash] an address object
+    attr_writer :address
+    # @!attribute [w] fields
+    # @return [Hash] a maps API response
+    attr_writer :fields
+
+    def initialize(args = {})
+      @address = args[:address]
+      @fields  = args[:fields]
+    end
+
+    # @abstract Abstract base method for parsing maps API responses
+    # @return (see AddressGeocoder::Client#suggested_addresses)
+    def parse_response
+      raise NeedToOveride, 'parse_response'
+    end
+  end
+end

data/lib/address_geocoder/requester.rb

@@ -0,0 +1,52 @@
+require 'httparty'
+require 'address_geocoder/error'
+
+module AddressGeocoder
+  # @abstract Abstract base class for making requests to maps APIs
+  class Requester
+    # @!attribute [w] parser
+    # @return [Parser] a class instance
+    attr_writer :parser
+    # @!attribute [w] address
+    # @return [Hash] the address to use in the request
+    attr_writer :address
+    # @!attribute [w] language
+    # @return [Hash] the language to return the request in
+    attr_writer :language
+    # @!attribute [w] api_key
+    # @return [Hash] the api_key to use in the request
+    attr_writer :api_key
+    # @!attribute [r] result
+    # @return [Hash] the result of a request to a maps API
+    attr_reader :result
+
+    def initialize(args = {})
+      @parser = args[:parser]
+    end
+
+    # @abstract Abstract base method for initiating a call to a maps API
+    # @return [void]
+    def make_call
+      raise NeedToOveride, 'make_call'
+    end
+
+    # @abstract Abstract base method for checking if a call to a maps API
+    #   suceeded
+    # @return [Boolean] true, or false if the request failed.
+    def success?
+      raise NeedToOveride, 'success?'
+    end
+
+    # @abstract Abstract base method for returning a compacted, flattened array
+    #   of different address responses.
+    # @return [Array<Hash>] a collection of possible addresses
+    def array_result
+      [@result['results']].flatten
+    end
+
+    # Raise a connection error
+    def connection_error(msg)
+      raise ConnectionError, msg
+    end
+  end
+end

data/lib/address_geocoder/url_generator.rb

@@ -0,0 +1,43 @@
+require 'uri'
+require 'address_geocoder/error'
+
+module AddressGeocoder
+  # @abstract Abstract base class for generatoring URLs to call maps APIs
+  # @todo If not other apis need this class then maybe this should be a map api
+  #   specific class (ie. might not need an abstract base class).
+  class UrlGenerator
+    # @!attribute api_key
+    # @return (see AddressGeocoder::Client#api_key)
+    attr_accessor :api_key
+
+    # @!attribute language
+    # @return (see AddressGeocoder::Client#language)
+    attr_accessor :language
+
+    # @!attribute address
+    # @return [Hash]
+    attr_accessor :address
+
+    def initialize(args = {})
+      @api_key  = args[:api_key]
+      @language = args[:language]
+      @address  = args[:address]
+    end
+
+    # @abstract Abstract base method for generating a URL with which to call a
+    #   maps API
+    # @return [String] a URL to use in calling a maps API
+    def generate_url
+      raise NeedToOveride, 'generate_url'
+    end
+
+    private
+
+    # Translate a hash into a query string
+    # @param hash [Hash] the object to be transformed
+    # @return [String] a URL query
+    def hash_to_query(hash)
+      URI.encode_www_form(hash)
+    end
+  end
+end

data/lib/address_geocoder/version.rb

@@ -0,0 +1,3 @@
+module AddressGeocoder
+  VERSION = '0.0.1'
+end

data/lib/maps_api.rb

@@ -0,0 +1,7 @@
+require 'yaml'
+require 'maps_api/google'
+
+# Namespace for classes and modules that handling API communication
+# @since 0.0.1
+module MapsApi
+end

data/lib/maps_api/google.rb

@@ -0,0 +1,9 @@
+require 'maps_api/google/client'
+require 'maps_api/google/parser'
+require 'maps_api/google/requester'
+require 'maps_api/google/url_generator'
+
+# Namespace for classes that interact with the Google Maps API
+# @since 0.0.1
+module Google
+end

data/lib/maps_api/google/client.rb

@@ -0,0 +1,19 @@
+require 'address_geocoder/client'
+require 'maps_api/google/parser'
+require 'maps_api/google/requester'
+
+module MapsApi
+  module Google
+    # Class for interacting with Google Maps API
+    class Client < ::AddressGeocoder::Client
+      # Assigns the entered variables to their proper instance variables
+      # @param (see AddressGeocoder::Client#assign_initial)
+      # @return (see AddressGeocoder::Client#assign_initial)
+      def assign_initial(args)
+        @parser    = Parser.new
+        @requester = Requester.new(parser: @parser)
+        super args
+      end
+    end
+  end
+end

data/lib/maps_api/google/parser.rb

@@ -0,0 +1,121 @@
+require 'address_geocoder/parser'
+
+module MapsApi
+  module Google
+    # Class for parsing Google Maps API responses
+    class Parser < ::AddressGeocoder::Parser
+      # List of Google's attribute title for streets
+      STREET_TYPES = { values: %w(route), name: 'street' }.freeze
+      # List of Google's attribute title for cities
+      CITY_TYPES   = { values: %w(neighborhood locality sublocality),
+                       name: 'city' }.freeze
+      # List of Google's attribute titles for states
+      STATE_TYPES  = { values: %w(administrative_area_level_4
+                                  administrative_area_level_3
+                                  administrative_area_level_2
+                                  administrative_area_level_1),
+                       name: 'state' }.freeze
+      # List of Google's attribute titles for postal codes
+      POSTAL_TYPES = { values: %w(postal_code postal_code_prefix),
+                       name: 'postal_code' }.freeze
+
+      # Convert Google Maps' response into our format with the goal of finding
+      # several matching addresses
+      # @return (see AddressGeocoder::Parser#parse_response)
+      def parse_response
+        @fields['address_components'].each do |field|
+          parse_field(field)
+        end
+        define_address
+      end
+
+      # Takes a specific field and converts it into our format
+      # @param field [Hash] one particular field from Google Maps' response
+      # @return [void]
+      def parse_field(field)
+        [STREET_TYPES, CITY_TYPES, STATE_TYPES, POSTAL_TYPES].each do |type|
+          if similar?(field['types'], type[:values])
+            send("add_#{type[:name]}", field)
+          end
+        end
+      end
+
+      # Check to see if the city should have been used in the call, and if so,
+      # was it?
+      # @return [Boolean] true, or false if the city should have been used but
+      # wasn't or vice versa
+      def city_present?(level)
+        [3, 4, 7].include?(level) && @address[:city]
+      end
+
+      # Check to see if the state should have been used in the call, and if so,
+      # was it?
+      # @return [Boolean] true, or false if the state should have been used but
+      # wasn't or vice versa
+      def state_present?(level)
+        4 == level && @address[:state]
+      end
+
+      # Check to see if the postal code should have been used in the call, and
+      # if so, was it?
+      # @return [Boolean] true, or false if the postal code should have been
+      # used but wasn't or vice versa
+      def pc_present?(level)
+        [5, 6, 7].include?(level) && @address[:postal_code]
+      end
+
+      def just_country?(google_response)
+        google_response['results'][0]['address_components'].count == 1
+      end
+
+      def not_correct_country?(google_response)
+        components = google_response['results']
+        components = components[0]['address_components']
+        !(components.select do |x|
+          x['short_name'] == @address[:country][:alpha2]
+        end).any?
+      end
+
+      private
+
+      def define_address
+        { country: @address[:country], city: @city, state: @state,
+          postal_code: @postal_code, street: @street }
+      end
+
+      def similar?(array1, array2)
+        (array1 & array2).any?
+      end
+
+      def add_street(field)
+        @street = field['long_name']
+      end
+
+      def add_city(field)
+        if @city
+          @state  = field['long_name']
+          @switch = true
+        else
+          @city = field['long_name']
+        end
+      end
+
+      def add_state(field)
+        str = if field['types'].include? 'administrative_area_level_1'
+                'short_name'
+              else
+                'long_name'
+              end
+        if @switch
+          @city   = @state
+          @switch = false
+        end
+        @state = field[str]
+      end
+
+      def add_postal_code(field)
+        @postal_code = field['long_name']
+      end
+    end
+  end
+end