swissmatch-location 0.0.1

data/lib/swissmatch/loaderror.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+
+
+
+require 'swissmatch/loaderror'
+
+
+
+module SwissMatch
+
+  # Used to indicate an error while loading the swissmatch data.
+  class LoadError < StandardError
+
+    # Data associated with the error
+    attr_reader :data
+
+    # @param [String] message
+    #   Same as Exception#initialize, the message of the exception
+    # @param [Object] data
+    #   Arbitrary data
+    def initialize(message, data)
+      super(message)
+      @data = data
+    end
+  end
+end

data/lib/swissmatch/location/autoload.rb

@@ -0,0 +1,8 @@
+# encoding: utf-8
+
+# Require this file to automatically load swissmatch location data
+# It will try to load from a try the directory in SWISSMATCH_DATA
+# If the env variable SWISSMATCH_DATA is not set, it'll try the data dir in the gem.
+
+require 'swissmatch/location'
+SwissMatch.load

data/lib/swissmatch/location/ruby.rb

@@ -0,0 +1,43 @@
+# encoding: utf-8
+# This file provides a couple of ruby monkey patches.
+
+module Enumerable
+  unless method_defined?(:last) then
+
+    # @example
+    #     ary.last     ->  obj or nil
+    #     ary.last(n)  ->  new_ary
+    #
+    # @return
+    #   The last element(s) of self. If the enumerable is empty, the first form returns
+    #   nil, the second an empty Array.
+    #   The method is optimized to make use of reverse_each if present.
+    def last(n=nil)
+      reverse_each_method = method(:reverse_each)
+      has_reverse_each    = reverse_each_method && reverse_each_method.owner != Enumerable # native reverse_each needed
+      if n then
+        return_value = []
+        if has_reverse_each then
+          reverse_each { |val|
+            return_value.unshift(val)
+            return return_value if return_value.size == n
+          }
+        else
+          each { |val|
+            return_value.push(val)
+            return_value.shift if return_value.size > n
+          }
+        end
+      else
+        if has_reverse_each then
+          reverse_each { |value| return value }
+        else
+          return_value = nil
+          each { |value| return_value = value }
+        end
+      end
+
+      return_value
+    end
+  end
+end

data/lib/swissmatch/location/version.rb

@@ -0,0 +1,15 @@
+# encoding: utf-8
+
+begin
+  require 'rubygems/version' # newer rubygems use this
+rescue LoadError
+  require 'gem/version' # older rubygems use this
+end
+
+module SwissMatch
+  module Location
+
+    # The version of the swissmatch-location gem.
+    Version = Gem::Version.new("0.0.1")
+  end
+end

data/lib/swissmatch/location.rb

@@ -0,0 +1,249 @@
+# encoding: utf-8
+
+
+
+require 'date'
+require 'swissmatch/canton'
+require 'swissmatch/cantons'
+require 'swissmatch/communities'
+require 'swissmatch/community'
+require 'swissmatch/datafiles'
+require 'swissmatch/location/ruby'
+require 'swissmatch/location/version'
+require 'swissmatch/zipcode'
+require 'swissmatch/zipcodes'
+
+
+
+# From SwissMatch::Location
+# Deal with swiss zip codes, cities, communities and cantons.
+#
+# @note
+#   All strings passed to SwissMatch are expected to be utf-8. All strings
+#   returned by SwissMatch are also in utf-8.
+#
+# @example Load the data
+#     require 'swissmatch'
+#     SwissMatch.load
+#     # alternatively, just require 'swissmatch/location/autoload'
+#
+# @example Get the ONRP for a given zip-code + city
+#     require 'swissmatch/location/autoload'
+#     SwissMatch.zip_code(8000, 'Zürich').ordering_number # => 4384
+#     SwissMatch.zip_code(4384).name # => "Zürich"(de, 0)
+module SwissMatch
+
+  # This module only contains the version of the swissmatch-location gem
+  module Location
+  end
+
+  @data               = nil
+  class <<self
+    # @return [SwissMatch::DataFiles, nil] The data source used
+    attr_reader :data
+  end
+
+  # @param [String] name_or_plate
+  #   The name or license_tag of the canton
+  #
+  # @return [SwissMatch::Canton]
+  #   The canton with the given name or license_tag
+  def self.canton(name_or_plate)
+    @data.cantons[name_or_plate]
+  end
+
+  # @return [SwissMatch::Cantons]
+  #   All known cantons
+  def self.cantons
+    @data.cantons
+  end
+
+  # @param [Integer] key
+  #   The community number of the community
+  #
+  # @return [SwissMatch::Community]
+  #   The community with the community number
+  def self.community(key)
+    @data.communities.by_community_number(key)
+  end
+
+  # @param [String] name
+  #   The name of the communities
+  #
+  # @return [SwissMatch::Communities]
+  #   All communities, or those matching the given name
+  def self.communities(name=nil)
+    name ? @data.communities.by_name(name) : @data.communities
+  end
+
+  # @param [String, Integer] code_or_name
+  #   Either the 4 digit zip code as Integer or String, or the city name as a String in
+  #   utf-8.
+  #
+  # @return [Array<SwissMatch::ZipCode>]
+  #   A list of zip codes with the given code or name.
+  def self.zip_codes(code_or_name=nil)
+    case code_or_name
+      when Integer, /\A\d{4}\z/
+        @data.zip_codes.by_code(code_or_name.to_i)
+      when String
+        @data.zip_codes.by_name(code_or_name)
+      when nil
+        @data.zip_codes
+      else
+        raise ArgumentError, "Invalid argument, must be a ZipCode#code (Integer or String) or ZipCode#name (String)"
+    end
+  end
+
+  # Returns a single zip code. A zip code can be uniquely identified by any of:
+  # * Its ordering_number (ONRP, a 4 digit Integer)
+  # * Its zip code (4 digit Integer) and add-on (2 digit Integer)
+  # * Its zip code (4 digit Integer) and any official name (String)
+  # The data can be passed in different ways, e.g. all numbers can be passed either
+  # as a String or as an Integer. The identification by zip code and add-on can be done
+  # by either using a combined 6 digit number (e.g. 800000 for "8000 Zürich"), or by
+  # passing 2 arguments, passing the zip code and the add-on separately.
+  #
+  # === IMPORTANT
+  # You must be aware, that passing a single 4-digit code to SwissMatch::zip_code uses
+  # the ONRP, and NOT the zip-code. The 4 digit zip code alone does NOT uniquely identify
+  # a zip code.
+  #
+  #
+  # @example Get a zip code by ONRP
+  #   SwissMatch.zip_code(4384)           # => #<SwissMatch::ZipCode:003ff996cf8d3c 8000 Zürich>
+  #
+  # @example Get a zip code by 4-digit code and add-on
+  #   SwissMatch.zip_code(8000, 0)        # => #<SwissMatch::ZipCode:003ff996cf8d3c 8000 Zürich>
+  #   SwissMatch.zip_code("8000", "00")   # => #<SwissMatch::ZipCode:003ff996cf8d3c 8000 Zürich>
+  #   SwissMatch.zip_code(800000)         # => #<SwissMatch::ZipCode:003ff996cf8d3c 8000 Zürich>
+  #   SwissMatch.zip_code("800000")       # => #<SwissMatch::ZipCode:003ff996cf8d3c 8000 Zürich>
+  #
+  # @example Get a zip code by 4-digit code and name
+  #   SwissMatch.zip_code(8000, "Zürich") # => #<SwissMatch::ZipCode:003ff996cf8d3c 8000 Zürich>
+  #   SwissMatch.zip_code(8000, "Zurigo") # => #<SwissMatch::ZipCode:003ff996cf8d3c 8000 Zürich>
+  #
+  #
+  # @param [String, Integer] code
+  #   The 4 digit zip code as Integer or String
+  # @param [String, Integer] city_or_add_on
+  #   Either the 2 digit zip-code add-on as string or integer, or the city name as a
+  #   String in utf-8.
+  #
+  # @return [SwissMatch::ZipCode]
+  #   The zip codes with the given code and the given add-on or name.
+  def self.zip_code(code, city_or_add_on=nil)
+    case city_or_add_on
+      when nil
+        @data.zip_codes.by_ordering_number(code.to_i)
+      when Integer, /\A\d\d\z/
+        @data.zip_codes.by_code_and_add_on(code.to_i, city_or_add_on.to_i)
+      when String
+        @data.zip_codes.by_code_and_name(code.to_i, city_or_add_on)
+      else
+        raise ArgumentError, "Invalid second argument, must be nil, ZipCode#add_on or ZipCode#name"
+    end
+  end
+
+  # @param [String] name
+  #   The name for which to return matching zip codes
+  #
+  # @return [Array<SwissMatch::ZipCode>]
+  #   Zip codes whose name equals the given name
+  def self.city(name)
+    @data.zip_codes.by_name(name)
+  end
+
+  # @param [String, Integer] code
+  #   The 4 digit zip code
+  # @param [nil, Array<Integer>] only_types
+  #   An array of zip code types (see ZipCode#type) which the returned zip codes must match.
+  # @param [nil, Symbol] locale
+  #   Return the names in the given locale, defaults to nil/:native (nil and :native are
+  #   treated the same and will return the native names)
+  #
+  # @return [Array<String>]
+  #   A list of unique names matching the parameters (4 digit code, type, locale).
+  def self.cities_for_zip_code(code, only_types=nil, locale=nil)
+    codes = @data.zip_codes.by_code(code.to_i)
+    return [] unless codes
+    codes = codes.select { |code| only_types.include?(code.type) } if only_types
+    names = case locale
+      when :native,nil then codes.map(&:name)
+      when :de then codes.map(&:name_de)
+      when :fr then codes.map(&:name_fr)
+      when :it then codes.map(&:name_it)
+      when :rt then codes.map(&:name_rt)
+      else raise ArgumentError, "Invalid locale #{locale}"
+    end
+
+    names.uniq
+  end
+
+  # Loads the swissmatch data
+  #
+  # @param [DataFiles] data_source
+  #   A valid data-source.
+  #
+  # @return [self]
+  #   Returns self
+  def self.load(data_source=nil)
+    @data = data_source || DataFiles.new
+    @data.load!
+
+    self
+  end
+
+  # @private
+  # Used to transliterate city names
+  Transliteration1 = {
+    "à" => "a",
+    "â" => "a",
+    "ä" => "a",
+    "è" => "e",
+    "é" => "e",
+    "ê" => "e",
+    "ë" => "e",
+    "ì" => "i",
+    "î" => "i",
+    "ï" => "i",
+    "ô" => "o",
+    "ö" => "o",
+    "ù" => "u",
+    "ü" => "u",
+  }
+
+  # @private
+  # Used to transliterate city names
+  Transliteration2 = Transliteration1.merge({
+    "ä" => "ae",
+    "ö" => "oe",
+    "ü" => "ue",
+  })
+
+  # @private
+  # Used to transliterate city names
+  TransMatch1 = /#{Transliteration1.keys.map { |k| Regexp.escape(k) }.join("|")}/
+
+  # @private
+  # Used to transliterate city names
+  TransMatch2 = /#{Transliteration2.keys.map { |k| Regexp.escape(k) }.join("|")}/
+
+  # @private
+  # Used to transliterate city names
+  def self.transliterate1(word)
+    word.gsub(TransMatch1, Transliteration1).delete("^ A-Za-z").downcase
+  end
+
+  # @private
+  # Used to transliterate city names
+  def self.transliterate2(word)
+    word.gsub(TransMatch2, Transliteration2).delete("^ A-Za-z").downcase
+  end
+
+  # @private
+  # Transliterates a string into the unique transliterated (1 & 2) word list
+  def self.transliterated_words(string)
+    "#{transliterate1(string)} #{transliterate2(string)}".split(" ").uniq
+  end
+end

data/lib/swissmatch/name.rb

@@ -0,0 +1,47 @@
+# encoding: utf-8
+
+
+
+module SwissMatch
+
+  # Adds a couple of properties to the String class.
+  # These properties are relevant to the naming of Cantons, Communities and
+  # ZipCodes. They provide information about the language in which the name is,
+  # and which sequence number that name has.
+  class Name < ::String
+
+    # @return [Integer] The sequence number of this name
+    attr_reader :sequence_number
+
+    # @return [Symbol] The language of this name (:de, :fr, :it or :rt)
+    attr_reader :language
+
+    # @param [String] name
+    #   The name (self)
+    # @param [Symbol] language
+    #   The language this name is in (:de, :fr, :it or :rt)
+    # @param [Integer] sequence_number
+    #   The sequence number of this name
+    def initialize(name, language, sequence_number=0)
+      @language         = language
+      @sequence_number  = sequence_number
+      super(name.to_s)
+    end
+
+    # @return [Hash]
+    #   All properties of the name as a hash.
+    def to_hash
+      {
+        :name             => to_s,
+        :language         => @language,
+        :sequence_number  => @sequence_number,
+      }
+    end
+
+    # @private
+    # @see Object#inspect
+    def inspect
+      "#{super}(#{@language}, #{@sequence_number})"
+    end
+  end
+end

data/lib/swissmatch/zip.rb

@@ -0,0 +1,40 @@
+# As it seems, some zip files delivered by the post are corrupt as per rubyzips standard.
+# This file contains a patch to handle the corruption.
+# As it seems, the zipfiles don't report the "\n" in the zipfile-comment
+
+begin
+  require 'zip/zip'
+rescue LoadError
+  raise "To update the swissmatch datafiles, the rubyzip gem is required, `gem install rubyzip` or add it to your Gemfile."
+end
+
+# @private
+# Patching the rubyzip gem
+module Zip
+
+  # @private
+  # Patching the rubyzip gem
+  class ZipCentralDirectory
+
+    # @private
+    # Patching the rubyzip gem
+    def read_e_o_c_d(io) #:nodoc:
+      buf = get_e_o_c_d(io)
+      @numberOfThisDisk                     = ZipEntry::read_zip_short(buf)
+      @numberOfDiskWithStartOfCDir          = ZipEntry::read_zip_short(buf)
+      @totalNumberOfEntriesInCDirOnThisDisk = ZipEntry::read_zip_short(buf)
+      @size                                 = ZipEntry::read_zip_short(buf)
+      @sizeInBytes                          = ZipEntry::read_zip_long(buf)
+      @cdirOffset                           = ZipEntry::read_zip_long(buf)
+      commentLength                         = ZipEntry::read_zip_short(buf)
+      @comment                              = buf.read(commentLength)
+
+      # ORIGINAL
+      # raise ZipError, "Zip consistency problem while reading eocd structure" unless buf.size == 0
+
+      # PATCH, doing it in a similar fashion as Archive::Zip in perl does
+      raise ZipError, "Zip consistency problem while reading eocd structure" if @comment.bytesize != commentLength
+      # /PATCH
+    end
+  end
+end

data/lib/swissmatch/zipcode.rb

@@ -0,0 +1,303 @@
+# encoding: utf-8
+
+
+
+require 'swissmatch/name'
+
+
+
+module SwissMatch
+
+  # Represents an area, commonly identified by zip-code and city-name.
+  # A unique zip code is determined by any of these:
+  # * the postal ordering number
+  # * zip code + zip code add on
+  # * zip code + name (city)
+  class ZipCode
+
+    # @return [Integer]
+    #   The postal ordering number, also known as ONRP
+    attr_reader :ordering_number # onrp
+
+    # Described under "PLZ light", as field "PLZ-Typ"
+    # * 10 = Domizil- und Fachadressen
+    # * 20 = Nur Domiziladressen
+    # * 30 = Nur Fach-PLZ
+    # * 40 = Firmen-PLZ
+    # * 80 = Postinterne PLZ (Angabe Zustellpoststelle auf Bundzetteln oder auf Sackanschriften)
+    #
+    # @return [Integer]
+    #   The type of the zip code in a numeric code, one of the values 10, 20, 30, 40 or 80.
+    attr_reader :type
+
+    # Described under "PLZ light", as field "Postleitzahl"
+    #
+    # @return [Integer]
+    #   The 4 digit numeric zip code
+    attr_reader :code
+
+    # @return [Integer]
+    #   The 2 digit numeric code addition, to distinguish zip codes with the same 4 digit code.
+    attr_reader :add_on
+
+    # @return [Integer]
+    #   The 6 digit numeric zip code and add-on (first 4 digits are the code, last 2
+    #   digits the add-on).
+    attr_reader :full_code
+
+    # @return [SwissMatch::Canton]
+    #   The canton this zip code belongs to
+    attr_reader :canton
+
+    # @return [SwissMatch::Name]
+    #   The official name of this zip code (max. 27 characters)
+    attr_reader :name
+
+    # @return [SwissMatch::Name]
+    #   The official name of this zip code (max. 18 characters)
+    attr_reader :name_short
+
+    # @return [Symbol]
+    #   The main language in the area of this zip code. One of :de, :fr, :it or :rt.
+    attr_reader :language
+
+    # @return [SwissMatch::Canton]
+    #   The second most used language in the area of this zip code. One of :de, :fr, :it or :rt.
+    attr_reader :language_alternative
+
+    # @return [Boolean]
+    #   Whether this ZipCode instance is included in the MAT[CH]sort sortfile
+    attr_reader :sortfile_member
+
+    # @return [SwissMatch::ZipCode]
+    #   By which postal office delivery of letters is usually taken care of.
+    attr_reader :delivery_by
+
+    # @return [SwissMatch::Community]
+    #   The community this zip code belongs to.
+    attr_reader :community
+
+    # @return [Date, nil]
+    #   The date from which on this zip code starts to be in use
+    #
+    # @see #in_use?
+    attr_reader :valid_from
+
+    # @return [Date, nil]
+    #   The date until which on this zip code is in use
+    #
+    # @see #in_use?
+    attr_reader :valid_until
+
+    def initialize(
+      ordering_number,
+      type,
+      code,
+      add_on,
+      name,
+      names,
+      name_short,
+      names_short,
+      region_names,
+      region_names_short,
+      canton,
+      language,
+      language_alternative,
+      sortfile_member,
+      delivery_by,
+      community,
+      valid_from,
+      valid_until = nil
+    )
+      @ordering_number      = ordering_number
+      @type                 = type
+      @code                 = code
+      @add_on               = add_on
+      @full_code            = code*100 + add_on
+      @language             = language
+      @language_alternative = language_alternative
+      @name                 = name.is_a?(Name) ? name : Name.new(name, language)
+      @name_short           = name_short.is_a?(Name) ? name_short : Name.new(name_short, language)
+      @names                = (names || [@name]).sort_by(&:sequence_number)
+      @names_short          = (names_short || [@name_short]).sort_by(&:sequence_number)
+      @region_names         = region_names
+      @region_names_short   = region_names_short
+      @canton               = canton
+      @sortfile_member      = sortfile_member
+      @delivery_by          = delivery_by == :self ? self : delivery_by
+      @community            = community
+      @valid_from           = valid_from
+      @valid_until          = valid_until
+    end
+
+    # @return [Array<String>]
+    #   The name of this zip code in all languages and normalizations (only unique values)
+    def transliterated_names
+      names.flat_map { |name, ary|
+        name = name.to_s # convert from SwissMatch::Name
+        [
+          SwissMatch.transliterate1(name),
+          SwissMatch.transliterate2(name)  # TODO: use transliterate gem
+        ]
+      }.uniq
+    end
+
+    # Since a zip code can - for any given language - have no name, exactly one name,
+    # or even multiple names, it is sometimes difficult to write good code to
+    # automatically provide well localized addresses. This method helps with that, in that
+    # it guarantees a single name, as well chosen as possible.
+    # It returns the name for the given language, and with the lowest running number, if
+    # no name can be found for the given language, the primary name (@see #name) is
+    # returned.
+    #
+    # @param [Symbol, nil] language
+    #   One of nil, :de, :fr, :it or :rt
+    #
+    # @return [SwissMatch::Name]
+    #   A single name for the zip code, chosen by a 'best fit' algorithm.
+    def suggested_name(language=nil)
+      (language && @names.find { |name| name.language == language }) || @name
+    end
+
+
+    # Since a zip code can - for any given language - have no name, exactly one name,
+    # or even multiple names, it is sometimes difficult to write good code to
+    # automatically provide well localized addresses. This method helps with that, in that
+    # it guarantees a single name, as well chosen as possible.
+    # It returns the name for the given language, and with the lowest running number, if
+    # no name can be found for the given language, the primary name (@see #name) is
+    # returned.
+    #
+    # @param [Symbol, nil] language
+    #   One of nil, :de, :fr, :it or :rt
+    #
+    # @return [SwissMatch::Name]
+    #   A single short name for the zip code, chosen by a 'best fit' algorithm.
+    def suggested_short_name(language=nil)
+      (language && @short_name.find { |name| name.language == language }) || @short_name
+    end
+
+    # @param [Symbol, nil] language
+    #   One of nil, :de, :fr, :it or :rt
+    #
+    # @return [Array<SwissMatch::Name>]
+    #   All official names (max. 27 chars) of this zip code.
+    def names(language=nil)
+      language ? @names.select { |name| name.language == language } : @names
+    end
+
+    # @param [Symbol, nil] language
+    #   One of nil, :de, :fr, :it or :rt
+    #
+    # @return [Array<SwissMatch::Name>]
+    #   All official short names (max. 18 chars) of this zip code.
+    def names_short(language=nil)
+      language ? @names_short.select { |name| name.language == language } : @names_short
+    end
+
+    # A region name is a name that can be used along a zip code and city, but must not replace
+    # the city. For more information, read the section about the PLZ_P2 file, "Bezeichnungstyp"
+    # with value "3".
+    #
+    # @param [Symbol, nil] language
+    #   One of nil, :de, :fr, :it or :rt
+    #
+    # @return [Array<SwissMatch::Name>]
+    #   All official region names (max. 27 chars) of this zip code.
+    def region_names(language=nil)
+      language ? @region_names.select { |name| name.language == language } : @region_names
+    end
+
+    # A region name is a name that can be used along a zip code and city, but must not replace
+    # the city. For more information, read the section about the PLZ_P2 file, "Bezeichnungstyp"
+    # with value "3".
+    #
+    # @param [Symbol, nil] language
+    #   One of nil, :de, :fr, :it or :rt
+    #
+    # @return [Array<SwissMatch::Name>]
+    #   All official short region names (max. 18 chars) of this zip code.
+    def region_names_short(language=nil)
+      language ? @region_names_short.select { |name| name.language == language } : @region_names_short
+    end
+
+    # Compare two zip codes by their ordering number (ONRP)
+    #
+    # @return [Integer]
+    #   Returns -1, 0 or 1.
+    def <=>(other)
+      @ordering_number <=> other.ordering_number
+    end
+
+    # @param [Date] at
+    #   The date for which to check the 
+    #
+    # @return [Boolean]
+    #   Whether the zip code is in active use at the given date.
+    def in_use?(at=Date.today)
+      if @valid_from then
+        if @valid_until then
+          at.between?(@valid_from, @valid_until)
+        else
+          at >= @valid_from
+        end
+      elsif @valid_until
+        at <= @valid_until
+      else
+        true
+      end
+    end
+
+    # @param [Boolean] retain_references
+    #   If set to false, :delivery_by will be set to the ordering number,
+    #   :community to the community_number and :canton to the canton's license_tag.
+    #
+    # @return [Hash]
+    #   All properties of the zip code as a hash.
+    def to_hash(retain_references=false)
+      delivery_by = retain_references ? @delivery_by : (@delivery_by && @delivery_by.ordering_number)
+      community   = retain_references ? @community : (@community && @community.community_number)
+      canton      = retain_references ? @canton : (@canton && @canton.license_tag)
+      {
+        :ordering_number      => @ordering_number,
+        :type                 => @type,
+        :code                 => @code,
+        :add_on               => @add_on,
+        :name                 => @name,
+        :name_short           => @name_short,
+        :canton               => canton,
+        :language             => @language,
+        :language_alternative => @language_alternative,
+        :sortfile_member      => @sortfile_member,
+        :delivery_by          => delivery_by,
+        :community            => community,
+        :valid_from           => @valid_from,
+        :valid_until          => @valid_until,
+      }
+    end
+
+    # @private
+    # @see Object#hash
+    def hash
+      [self.class, @ordering_number].hash
+    end
+
+    # @private
+    # @see Object#eql?
+    def eql?(other)
+      self.class == other.class && @ordering_number == other.ordering_number
+    end
+
+    # @return [String]
+    #   The 4 digit code, followed by the name
+    def to_s
+      "#{@code} #{@name}"
+    end
+
+    # @return [String]
+    # @see Object#inspect
+    def inspect
+      sprintf "\#<%s:%014x %s>", self.class, object_id, self
+    end
+  end
+end