geoip 0.8.9 → 0.9.0

data/README.rdoc

@@ -16,19 +16,31 @@ This release adds support for timezone names, thanks to Tonni Aagesen.
 == SYNOPSIS:
 
   require 'geoip'
-  GeoIP.new('GeoLiteCity.dat').country('www.atlantis.sk')
-  => ["www.atlantis.sk", "217.67.18.26", "SK", "SVK", "Slovakia", "EU", "02", "Bratislava", "", 48.15, 17.1167, nil, nil, "Europe/Bratislava"]
+
+  # Use the country database:
+  GeoIP.new('GeoIP.dat').country('www.atlantis.sk')
+  => ["www.atlantis.sk", "217.67.18.26", 196, "SK", "SVK", "Slovakia", "EU"]
 
   Returned values are the requested hostname, the IP address as a dotted quad,
-  Maxmind's country code, the ISO3166-1 country code, the ISO3166-2 country code,
-  the ISO3166 country name, and the continent code.
+  Maxmind's country code, the ISO3166-1 alpha-2 country code, the ISO3166-2 alpha-3
+  country code, the ISO3166 country name, and the continent code.
+
+  # Use the city database:
+  GeoIP.new('GeoLiteCity.dat').country('www.atlantis.sk')
+  => ["www.atlantis.sk", "217.67.18.26", "SK", "SVK", "Slovakia", "EU", "02", "Bratislava", "", 48.15, 17.1167, nil, nil, "Europe/Bratislava"]
 
   GeoIP.new('GeoCity.dat').city('github.com')
   => ["github.com", "207.97.227.239", "US", "USA", "United States", "NA", "CA", "San Francisco", "94110", 37.7484, -122.4156, 807, 415, "America/Los_Angeles"]
 
-  Returned values are the country values followed by region or state name,
+  Returned values are the requested hostname, the IP address as a dotted quad,
+  the ISO3166-1 alpha-2 country code, the ISO3166-2 alpha-3 country code, the
+  ISO3166 country name, the continent code, the region (state or territory) name,
   city name, postal_code/zipcode, latitude, longitude, USA DMA code, USA area code,
-  timezone name. Sorry it's not a Hash... historical.
+  timezone name.
+
+  Result arrays from both city and country also contain accessor methods as appropriate:
+  request, ip, country_code, country_code2, country_code3, country_name, continent_code,
+  region_name, city_name, postal_code, latitude, longitude, dma_code, area_code, timezone
 
   GeoIP.new('GeoIPASNum.dat').asn("www.fsb.ru")
   => ["AS8342", "RTComm.RU Autonomous System"]

data/lib/geoip.rb

@@ -50,8 +50,11 @@ rescue LoadError
 end
 
 class GeoIP
-    VERSION = "0.8.9"
+    # The GeoIP GEM version number
+    VERSION = "0.9.0"
+
     private
+    # Ordered list of the ISO3166 2-character country codes, ordered by GeoIP ID
     CountryCode = [
         "--","AP","EU","AD","AE","AF","AG","AI","AL","AM","AN",
         "AO","AQ","AR","AS","AT","AU","AW","AZ","BA","BB",
@@ -81,6 +84,7 @@ class GeoIP
         "BL","MF"
     ]
 
+    # Ordered list of the ISO3166 3-character country codes, ordered by GeoIP ID
     CountryCode3 = [
         "--","AP","EU","AND","ARE","AFG","ATG","AIA","ALB","ARM","ANT",
         "AGO","AQ","ARG","ASM","AUT","AUS","ABW","AZE","BIH","BRB",
@@ -110,6 +114,7 @@ class GeoIP
         "BLM","MAF"
     ]
 
+    # Ordered list of the English names of the countries, ordered by GeoIP ID
     CountryName = [
         "N/A",
         "Asia/Pacific Region",
@@ -366,6 +371,7 @@ class GeoIP
         "Saint Martin"
     ]
 
+    # Ordered list of the ISO3166 2-character continent code of the countries, ordered by GeoIP ID
     CountryContinent = [
         "--","AS","EU","EU","AS","AS","SA","SA","EU","AS","SA",
         "AF","AN","SA","OC","EU","OC","SA","AS","EU","SA",
@@ -395,6 +401,7 @@ class GeoIP
         "SA","SA"
     ]
 
+    # Hash of the timezone codes mapped to timezone name, per zoneinfo
     TimeZone = {
         "USAL" => "America/Chicago", "USAK" => "America/Anchorage", "USAZ" => "America/Phoenix",
         "USAR" => "America/Chicago", "USCA" => "America/Los_Angeles", "USCO" => "America/Denver",
@@ -624,37 +631,36 @@ class GeoIP
     }
 
     public
-    # Edition enumeration:
-    (GEOIP_COUNTRY_EDITION,
-    GEOIP_CITY_EDITION_REV1,
-    GEOIP_REGION_EDITION_REV1,
-    GEOIP_ISP_EDITION,
-    GEOIP_ORG_EDITION,
-    GEOIP_CITY_EDITION_REV0,
-    GEOIP_REGION_EDITION_REV0,
-    GEOIP_PROXY_EDITION,
-    GEOIP_ASNUM_EDITION,
-    GEOIP_NETSPEED_EDITION,
-    ) = *1..10
+    GEOIP_COUNTRY_EDITION = 1
+    GEOIP_CITY_EDITION_REV1 = 2
+    GEOIP_REGION_EDITION_REV1 = 3
+    GEOIP_ISP_EDITION = 4
+    GEOIP_ORG_EDITION = 5
+    GEOIP_CITY_EDITION_REV0 = 6
+    GEOIP_REGION_EDITION_REV0 = 7
+    GEOIP_PROXY_EDITION = 8
+    GEOIP_ASNUM_EDITION = 9
+    GEOIP_NETSPEED_EDITION = 10
 
     private
-    COUNTRY_BEGIN = 16776960
-    STATE_BEGIN_REV0 = 16700000
-    STATE_BEGIN_REV1 = 16000000
-    STRUCTURE_INFO_MAX_SIZE = 20
-    DATABASE_INFO_MAX_SIZE = 100
-    MAX_ORG_RECORD_LENGTH = 300
-    MAX_ASN_RECORD_LENGTH = 300 # unverified
-    US_OFFSET = 1
-    CANADA_OFFSET = 677
-    WORLD_OFFSET = 1353
-    FIPS_RANGE = 360
-    FULL_RECORD_LENGTH = 50
+    COUNTRY_BEGIN = 16776960          #:nodoc:
+    STATE_BEGIN_REV0 = 16700000       #:nodoc:
+    STATE_BEGIN_REV1 = 16000000       #:nodoc:
+    STRUCTURE_INFO_MAX_SIZE = 20      #:nodoc:
+    DATABASE_INFO_MAX_SIZE = 100      #:nodoc:
+    MAX_ORG_RECORD_LENGTH = 300       #:nodoc:
+    MAX_ASN_RECORD_LENGTH = 300       #:nodoc: unverified
+    US_OFFSET = 1                     #:nodoc:
+    CANADA_OFFSET = 677               #:nodoc:
+    WORLD_OFFSET = 1353               #:nodoc:
+    FIPS_RANGE = 360                  #:nodoc:
+    FULL_RECORD_LENGTH = 50           #:nodoc:
 
-    STANDARD_RECORD_LENGTH = 3
-    SEGMENT_RECORD_LENGTH = 3
+    STANDARD_RECORD_LENGTH = 3        #:nodoc:
+    SEGMENT_RECORD_LENGTH = 3         #:nodoc:
 
     public
+    # The Edition number that identifies which kind of database you've opened
     attr_reader :databaseType
 
     # Open the GeoIP database and determine the file format version
@@ -710,15 +716,20 @@ class GeoIP
     # Search the GeoIP database for the specified host, returning country info
     #
     # +hostname+ is a String holding the host's DNS name or numeric IP address.
-    # Return an array of seven elements:
+    # If the database is a City database (normal), return the result that +city+ would return.
+    # Otherwise, return an array of seven elements:
     # * The host or IP address string as requested
     # * The IP address string after looking up the host
-    # * The GeoIP country-ID as an integer
-    # * The ISO3166-1 two-character country code
-    # * The ISO3166-2 three-character country code
-    # * The ISO3166 English-language name of the country
+    # * The GeoIP country-ID as an integer (N.B. this is excluded from the city results!)
+    # * The two-character country code (ISO 3166-1 alpha-2)
+    # * The three-character country code (ISO 3166-2 alpha-3)
+    # * The ISO 3166 English-language name of the country
     # * The two-character continent code
     #
+    # The array has been extended with methods listed in GeoIP::CountryAccessors.ACCESSORS:
+    # request, ip, country_code, country_code2, country_code3, country_name, continent_code.
+    # In addition, +to_hash+ provides a symbol-keyed hash for the above values.
+    #
     def country(hostname)
         if (@databaseType == GEOIP_CITY_EDITION_REV0 ||
             @databaseType == GEOIP_CITY_EDITION_REV1)
@@ -734,7 +745,7 @@ class GeoIP
 
         # Convert numeric IP address to an integer
         ipnum = iptonum(ip)
-        if (@databaseType != GEOIP_COUNTRY_EDITION && 
+        if (@databaseType != GEOIP_COUNTRY_EDITION &&
             @databaseType != GEOIP_PROXY_EDITION &&
             @databaseType != GEOIP_NETSPEED_EDITION)
             throw "Invalid GeoIP database type, can't look up Country by IP"
@@ -743,118 +754,36 @@ class GeoIP
         [   hostname,                   # Requested hostname
             ip,                         # Ip address as dotted quad
             code,                       # GeoIP's country code
-            CountryCode[code],          # ISO3166-1 code
-            CountryCode3[code],         # ISO3166-2 code
-            CountryName[code],          # Country name, per IS03166
-            CountryContinent[code] ]    # Continent code.
-    end
-
-    # Search the GeoIP database for the specified host, returning city info
-    #
-    # +hostname+ is a String holding the host's DNS name or numeric IP address
-    # Return an array of twelve or fourteen elements:
-    # * All elements from the country query
-    # * The region (state or territory) name
-    # * The city name
-    # * The postal code (zipcode)
-    # * The latitude
-    # * The longitude
-    # * The dma_code and area_code, if available (REV1 City database)
-    # * The timezone name, if known
-    private
-
-    def read_city(pos, hostname = '', ip = '')
-        off = pos + (2*@record_length-1) * @databaseSegments[0]
-        record = atomic_read(FULL_RECORD_LENGTH, off)
-        return nil unless record && record.size == FULL_RECORD_LENGTH
-
-        # The country code is the first byte:
-        code = record[0]
-        code = code.ord if code.respond_to?(:ord)
-        record = record[1..-1]
-        @iter_pos += 1 unless @iter_pos.nil?
-
-        spl = record.split("\x00", 4)
-        # Get the region:
-        region = spl[0]
-        @iter_pos += (region.size + 1) unless @iter_pos.nil?
-
-        # Get the city:
-        city = spl[1]
-        @iter_pos += (city.size + 1) unless @iter_pos.nil?
-        # set the correct encoding in ruby 1.9 compatible environments:
-        city.force_encoding('iso-8859-1') if city.respond_to?(:force_encoding)
-
-        # Get the postal code:
-        postal_code = spl[2]
-        @iter_pos += (postal_code.size + 1) unless @iter_pos.nil?
-
-        record = spl[3]
-        # Get the latitude/longitude:
-        if(record && record[0,3]) then
-            latitude  = le_to_ui(record[0,3].unpack('C*')) / 10000.0 - 180
-            record = record[3..-1]
-            @iter_pos += 3 unless @iter_pos.nil?
-        else
-            latitude = ''
-        end
-        if(record && record[0,3]) then
-            longitude = le_to_ui(record[0,3].unpack('C*')) / 10000.0 - 180
-            record = record[3..-1]
-            @iter_pos += 3 unless @iter_pos.nil?
-        else
-            longitude = ''
-        end
-
-        us_area_codes = []
-        if (record &&
-                record[0,3] &&
-                @databaseType == GEOIP_CITY_EDITION_REV1 &&
-                CountryCode[code] == "US")      # UNTESTED
-            dmaarea_combo = le_to_ui(record[0,3].unpack('C*'))
-            dma_code = dmaarea_combo / 1000;
-            area_code = dmaarea_combo % 1000;
-            us_area_codes = [ dma_code, area_code ]
-            @iter_pos += 3 unless @iter_pos.nil?
-        else
-            us_area_codes = [ nil, nil ]  # Ensure that TimeZone is always at the same offset
-        end
-
-        [   hostname,                   # Requested hostname
-            ip,                         # Ip address as dotted quad
-            CountryCode[code],          # ISO3166-1 code
-            CountryCode3[code],         # ISO3166-2 code
-            CountryName[code],          # Country name, per IS03166
-            CountryContinent[code],     # Continent code.
-            region,                     # Region name
-            city,                       # City name
-            postal_code,                # Postal code
-            latitude,
-            longitude,
-        ] +
-            us_area_codes +
-            [ TimeZone["#{CountryCode[code]}#{region}"] || TimeZone["#{CountryCode[code]}"] ]
+            CountryCode[code],          # ISO3166-1 alpha-2 code
+            CountryCode3[code],         # ISO3166-2 alpha-3 code
+            CountryName[code],          # Country name, per ISO 3166
+            CountryContinent[code]      # Continent code.
+        ].extend(CountryAccessors)
     end
 
-    public
-
     # Search the GeoIP database for the specified host, returning city info.
     #
     # +hostname+ is a String holding the host's DNS name or numeric IP address.
-    # Return an array of twelve or fourteen elements:
+    # Return an array of fourteen elements:
     # * The host or IP address string as requested
     # * The IP address string after looking up the host
-    # * The GeoIP country-ID as an integer
-    # * The ISO3166-1 two-character country code
-    # * The ISO3166-2 three-character country code
-    # * The ISO3166 English-language name of the country
+    # * The two-character country code (ISO 3166-1 alpha-2)
+    # * The three-character country code (ISO 3166-2 alpha-3)
+    # * The ISO 3166 English-language name of the country
     # * The two-character continent code
-    # * The region name
+    # * The region name (state or territory)
     # * The city name
-    # * The postal code
+    # * The postal code (zipcode)
     # * The latitude
     # * The longitude
-    # * The USA dma_code and area_code, if available (REV1 City database)
+    # * The USA dma_code if known (only REV1 City database)
+    # * The USA area_code if known (only REV1 City database)
+    # * The timezone name, if known
+    #
+    # The array has been extended with methods listed in GeoIP::CityAccessors.ACCESSORS:
+    # request, ip, country_code2, country_code3, country_name, continent_code,
+    # region_name, city_name, postal_code, latitude, longitude, dma_code, area_code, timezone.
+    # In addition, +to_hash+ provides a symbol-keyed hash for the above values.
     #
     def city(hostname)
         ip = hostname
@@ -879,10 +808,11 @@ class GeoIP
         # and I'll send you the test program so you can test whatever IP range you think is causing
         # problems, as I don't care to undertake an exhaustive search of the 32-bit space.
         return nil if pos == @databaseSegments[0]
-        read_city(pos, hostname, ip)
+        read_city(pos, hostname, ip).extend(CityAccessors)
     end
 
     # Search a ISP GeoIP database for the specified host, returning the ISP
+    # Not all GeoIP databases contain ISP information. Check http://maxmind.com
     #
     # +hostname+ is a String holding the host's DNS name or numeric IP address.
     # Return the ISP name
@@ -906,7 +836,7 @@ class GeoIP
         record = record.sub(/\000.*/n, '')
         record
     end
-    
+
     # Search a ASN GeoIP database for the specified host, returning the AS number + description
     #
     # +hostname+ is a String holding the host's DNS name or numeric IP address.
@@ -914,7 +844,7 @@ class GeoIP
     #
     # Source:
     # http://geolite.maxmind.com/download/geoip/database/asnum/GeoIPASNum.dat.gz
-    #   
+    #
     def asn(hostname)
         ip = hostname
         if ip.kind_of?(String) && ip !~ /^[0-9.]*$/
@@ -932,10 +862,10 @@ class GeoIP
         off = pos + (2*@record_length-1) * @databaseSegments[0]
         record = atomic_read(MAX_ASN_RECORD_LENGTH, off)
         record = record.sub(/\000.*/n, '')
-        
+
         if record =~ /^(AS\d+)\s(.*)$/
-          # AS####, Description 
-          return [$1, $2]
+          # AS####, Description
+          return [$1, $2].extend(ASNAccessors)
         end
     end
 
@@ -964,8 +894,92 @@ class GeoIP
     end
 
     private
-      
-    def iptonum(ip)     # Convert numeric IP address to integer
+
+    # Search the GeoIP database for the specified host, returning city info
+    #
+    # +hostname+ is a String holding the host's DNS name or numeric IP address
+    # Return an array of fourteen elements:
+    # * All elements from the country query (except GeoIP's country code, bah!)
+    # * The region (state or territory) name
+    # * The city name
+    # * The postal code (zipcode)
+    # * The latitude
+    # * The longitude
+    # * The dma_code and area_code, if available (REV1 City database)
+    # * The timezone name, if known
+    def read_city(pos, hostname = '', ip = '')  #:nodoc:
+        off = pos + (2*@record_length-1) * @databaseSegments[0]
+        record = atomic_read(FULL_RECORD_LENGTH, off)
+        return nil unless record && record.size == FULL_RECORD_LENGTH
+
+        # The country code is the first byte:
+        code = record[0]
+        code = code.ord if code.respond_to?(:ord)
+        record = record[1..-1]
+        @iter_pos += 1 unless @iter_pos.nil?
+
+        spl = record.split("\x00", 4)
+        # Get the region:
+        region = spl[0]
+        @iter_pos += (region.size + 1) unless @iter_pos.nil?
+
+        # Get the city:
+        city = spl[1]
+        @iter_pos += (city.size + 1) unless @iter_pos.nil?
+        # set the correct encoding in ruby 1.9 compatible environments:
+        city.force_encoding('iso-8859-1') if city.respond_to?(:force_encoding)
+
+        # Get the postal code:
+        postal_code = spl[2]
+        @iter_pos += (postal_code.size + 1) unless @iter_pos.nil?
+
+        record = spl[3]
+        # Get the latitude/longitude:
+        if(record && record[0,3]) then
+            latitude  = le_to_ui(record[0,3].unpack('C*')) / 10000.0 - 180
+            record = record[3..-1]
+            @iter_pos += 3 unless @iter_pos.nil?
+        else
+            latitude = ''
+        end
+        if(record && record[0,3]) then
+            longitude = le_to_ui(record[0,3].unpack('C*')) / 10000.0 - 180
+            record = record[3..-1]
+            @iter_pos += 3 unless @iter_pos.nil?
+        else
+            longitude = ''
+        end
+
+        if (record &&
+                record[0,3] &&
+                @databaseType == GEOIP_CITY_EDITION_REV1 &&
+                CountryCode[code] == "US")      # UNTESTED
+            dmaarea_combo = le_to_ui(record[0,3].unpack('C*'))
+            dma_code = dmaarea_combo / 1000;
+            area_code = dmaarea_combo % 1000;
+            @iter_pos += 3 unless @iter_pos.nil?
+        else
+            dma_code, area_code = nil, nil
+        end
+
+        [   hostname,                   # Requested hostname
+            ip,                         # Ip address as dotted quad
+            CountryCode[code],          # ISO3166-1 code
+            CountryCode3[code],         # ISO3166-2 code
+            CountryName[code],          # Country name, per IS03166
+            CountryContinent[code],     # Continent code.
+            region,                     # Region name
+            city,                       # City name
+            postal_code,                # Postal code
+            latitude,
+            longitude,
+            dma_code,
+            area_code
+        ] +
+            [ TimeZone["#{CountryCode[code]}#{region}"] || TimeZone["#{CountryCode[code]}"] ]
+    end
+
+    def iptonum(ip)     #:nodoc: Convert numeric IP address to integer
         if ip.kind_of?(String) &&
             ip =~ /^([0-9]+)\.([0-9]+)\.([0-9]+)\.([0-9]+)$/
             ip = be_to_ui(Regexp.last_match().to_a.slice(1..4))
@@ -973,7 +987,7 @@ class GeoIP
         ip
     end
 
-    def seek_record(ipnum)
+    def seek_record(ipnum)    #:nodoc:
         # Binary search in the file.
         # Records are pairs of little-endian integers, each of @record_length.
         offset = 0
@@ -989,14 +1003,14 @@ class GeoIP
     end
 
     # Convert a big-endian array of numeric bytes to unsigned int
-    def be_to_ui(s)
+    def be_to_ui(s)   #:nodoc:
         s.inject(0) { |m, o|
             (m << 8) + o.to_i
         }
     end
 
     # Same for little-endian
-    def le_to_ui(s)
+    def le_to_ui(s)   #:nodoc:
         be_to_ui(s.reverse)
     end
 
@@ -1005,7 +1019,7 @@ class GeoIP
     # and multiprocess-safe).  Otherwise we'll use a mutex to synchronize
     # access (only providing protection against multiple threads, but not
     # file descriptors shared across multiple processes).
-    def atomic_read(length, offset)
+    def atomic_read(length, offset)   #:nodoc:
         if @mutex
             @mutex.synchronize {
                 @file.seek(offset)
@@ -1015,6 +1029,49 @@ class GeoIP
             IO.pread(@file.fileno, length, offset)
         end
     end
+
+    module CountryAccessors   #:nodoc:
+      ACCESSORS = [
+        :request, :ip, :country_code, :country_code2, :country_code3, :country_name, :continent_code
+      ]
+      ACCESSORS.each_with_index do |method, i|
+        define_method(method) { self[i] }
+      end
+
+      def to_hash
+        ACCESSORS.inject({}) do |hash, key|
+          hash[key] = self.send(key)
+          hash
+        end
+      end
+    end
+
+    module CityAccessors    #:nodoc:
+      ACCESSORS = [
+        :request, :ip, :country_code2, :country_code3, :country_name, :continent_code,
+        :region_name, :city_name, :postal_code, :latitude, :longitude, :dma_code, :area_code, :timezone
+      ]
+      ACCESSORS.each_with_index do |method, i|
+        define_method(method) { self[i] }
+      end
+
+      def to_hash
+        ACCESSORS.inject({}) do |hash, key|
+          hash[key] = self.send(key)
+          hash
+        end
+      end
+    end
+
+    module ASNAccessors   #:nodoc:
+      def ip
+        self[0]
+      end
+
+      def asn
+        self[1]
+      end
+    end
 end
 
 if $0 == __FILE__

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: geoip
 version: !ruby/object:Gem::Version 
-  hash: 45
+  hash: 59
   prerelease: false
   segments: 
   - 0
-  - 8
   - 9
-  version: 0.8.9
+  - 0
+  version: 0.9.0
 platform: ruby
 authors: 
 - Clifford Heath
@@ -16,7 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-01-13 00:00:00 +11:00
+date: 2011-02-07 00:00:00 +11:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency