swissmatch-directories 0.0.1

data/LICENSE.txt

@@ -0,0 +1,8 @@
+Copyright (c) 2012, Stefan Rusterholz <stefan.rusterholz@gmail.com>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.markdown

@@ -0,0 +1,58 @@
+README
+======
+
+
+Summary
+-------
+Query address data from swiss directory providers.
+
+
+Installation
+------------
+Install the gem: `gem install swissmatch-directories`  
+Depending on how you installed rubygems, you have to use `sudo`:
+`sudo gem install swissmatch-directories`  
+In Ruby: `require 'swissmatch/directories'`
+
+
+Usage
+-----
+    require 'swissmatch/directories'
+    directories = SwissMatch::Directories.create(:telsearch, api_token: your_token)
+    params      = {first_name: 'Stefan', last_name: 'Rusterholz'}
+    directories.addresses(params).each do |address|
+      puts address,""
+    end
+
+
+Relevant Classes and Modules
+----------------------------
+* __{SwissMatch::Directories}__
+  Convenience methods to create and access directory services
+* __{SwissMatch::Directories::Service}__
+  The basic API to use directory services
+
+
+Links
+-----
+
+* [Main Project](https://github.com/apeiros/swissmatch)
+* [Online API Documentation](http://rdoc.info/github/apeiros/swissmatch-directories/)
+* [Public Repository](https://github.com/apeiros/swissmatch-directories)
+* [Bug Reporting](https://github.com/apeiros/swissmatch-directories/issues)
+* [RubyGems Site](https://rubygems.org/gems/swissmatch-directories)
+* [Swiss Posts MAT[CH]](http://www.post.ch/match)
+
+
+License
+-------
+
+You can use this code under the {file:LICENSE.txt BSD-2-Clause License}, free of charge.
+If you need a different license, please ask the author.
+
+
+Credits
+-------
+
+* [Simon Hürlimann](https://github.com/huerlisi) for contributions
+* [AWD Switzerland](http://www.awd.ch/) for donating time to work on this gem.

data/Rakefile

@@ -0,0 +1,10 @@
+$LOAD_PATH.unshift(File.expand_path('../rake/lib', __FILE__))
+Dir.glob(File.expand_path('../rake/tasks/**/*.{rake,task,rb}', __FILE__)) do |task_file|
+  begin
+    import task_file
+  rescue LoadError => e
+    warn "Failed to load task file #{task_file}"
+    warn "  #{e.class} #{e.message}"
+    warn "  #{e.backtrace.first}"
+  end
+end

data/lib/swissmatch/directories.rb

@@ -0,0 +1,66 @@
+# encoding: utf-8
+
+
+
+require 'swissmatch/directories/service'
+require 'swissmatch/directories/version'
+
+
+
+# __{SwissMatch::Directories}__
+# Query address data from swiss online directory providers.
+#
+# @note
+#   All strings passed to SwissMatch are expected to be utf-8. All strings
+#   returned by SwissMatch are also in utf-8.
+#
+module SwissMatch
+
+  # Query address data from swiss online directory providers.
+  #
+  # @example Usage
+  #   require 'swissmatch/directories'
+  #   directories = SwissMatch::Directories.create(:telsearch, api_token: your_token)
+  #   params      = {first_name: 'Stefan', last_name: 'Rusterholz'}
+  #   directories.addresses(params).each do |address|
+  #     puts address,""
+  #   end
+  module Directories
+    @services = Hash.new { |hash, key|
+      if key.respond_to?(:from_configuration)
+        key
+      else
+        raise ArgumentError, "Unknown service: #{key.inspect}"
+      end
+    }.merge(
+      telsearch: SwissMatch::Directories::TelSearch
+    )
+
+    class <<self
+
+      # @return [Hash] The available back-ends.
+      attr_reader :services
+    end
+
+    # @return [Class] A SwissMatch::Directories::Service compatible service class.
+    def self.service(name)
+      services[name]
+    end
+
+    # @return [SwissMatch::Directories::Service] A directory service
+    def self.create(name, options)
+      Service.new(name, options)
+    end
+  end
+
+  @directory_service  = nil
+
+  class <<self
+
+    # @return [SwissMatch::Directories::Service, nil]
+    # The directory service used to search for addresses
+    # You have to set this one yourself. It exists to provide a standard way to
+    # 
+    attr_accessor :directory_service
+  end
+end

data/lib/swissmatch/directories/address.rb

@@ -0,0 +1,41 @@
+# encoding: utf-8
+
+
+
+module SwissMatch
+  module Directories
+
+    # Represents a swiss address. Used by directory service interfaces to return search
+    # results.
+    Address = Struct.new(:gender, :first_name, :last_name, :maiden_name, :street_name, :street_number, :zip_code, :city) do
+
+      # @return [String]
+      #   The street and street number
+      def street
+        [street_name, street_number].compact.join(" ")
+      end
+
+      # @return [String]
+      #   The full name, consisting of first_name and family_name.
+      def full_name
+        "#{first_name} #{family_name}"
+      end
+
+      # @return [String]
+      #   The full family name, including the maiden name.
+      #
+      # @note
+      #   I (stefan.rusterholz@gmail.com) am not sure whether "last_name (-maiden_name)"
+      #   is the proper form. The output might be changed in a future version
+      #   The current output is based on how tel.search.ch displays the name.
+      def family_name
+        maiden_name ? "#{last_name} (-#{maiden_name})" : last_name
+      end
+
+      # @return [String] A halfway readable textual representation
+      def to_s
+        "#{full_name}\n#{street}\n#{zip_code} #{city}"
+      end
+    end
+  end
+end

data/lib/swissmatch/directories/service.rb

@@ -0,0 +1,52 @@
+# encoding: utf-8
+
+
+
+require 'swissmatch/directories/address'
+require 'swissmatch/directories/telsearch'
+
+
+
+module SwissMatch
+  module Directories
+
+    # Common directory service API.
+    #
+    # @see SwissMatch::Directories Usage examples
+    class Service
+
+      # @param [Class, Symbol, #from_configuration] back_end
+      #   A valid back-end. Valid in vanilla swissmatch-directories:
+      #   * :telsearch
+      #   * SwissMatch::Directories::TelSearch (same as :telsearch)
+      # @param [Object] config
+      #   A back-end specific configuration object.
+      def initialize(back_end, config=nil)
+        @service = SwissMatch::Directories.service(back_end).from_config(config)
+      end
+
+      # Query for addresses matching a set of given search parameters
+      #
+      # Note that not all back-ends will treat these parameters with the same strictness.
+      # The tel.search.ch back-end for example will search for a last name anywhere in the name.
+      #
+      # @param [Hash] params
+      #   The abstract API search parameters.
+      #   Valid parameters:
+      #   * :first_name
+      #   * :family_name
+      #   * :last_name
+      #   * :maiden_name
+      #   * :name
+      #   * :phone
+      #   * :street
+      #   * :street_name
+      #   * :street_number
+      #   * :zip_code
+      #   * :city
+      def addresses(params, options={})
+        @service.addresses(params, options)
+      end
+    end
+  end
+end

data/lib/swissmatch/directories/telsearch.rb

@@ -0,0 +1,105 @@
+# encoding: utf-8
+
+
+
+require 'swissmatch/directories/service'
+require 'uri'
+require 'open-uri'
+require 'nokogiri'
+
+
+
+module SwissMatch
+  module Directories
+
+    # A Directory service, using tel.search.ch's API.
+    # Also see http://tel.search.ch/api/help
+    #
+    # You need an API key in order to use this library. You can get one on
+    # http://admin.tel.search.ch/api/getkey
+    #
+    # @see SwissMatch::Directories Usage examples
+    class TelSearch
+
+      # Create a TelSearch instance from the common interface.
+      # TelSearch requires the :api_token option to be set.
+      def self.from_config(config)
+        new(config.fetch(:api_token))
+      end
+
+      # @private
+      # XML Namespaces, used to parse the data returned by tel.search.ch
+      NS      = {'t' => 'http://tel.search.ch/api/spec/result/1.0/'}
+
+      # @private
+      # The url of the API of tel.search.ch
+      API_URI = URI.parse('http://tel.search.ch/api')
+
+      # @param [String] key
+      #   The API key for the telsearch service.
+      #   You can get one on http://admin.tel.search.ch/api/getkey
+      def initialize(key)
+        @key = key
+        @uri = API_URI
+      end
+
+      # @private
+      # Convert the abstracted APIs options to tel.search.ch's search params
+      #
+      # @param [Hash] params
+      #   The abstract API search parameters
+      def search_ch_mapping(params)
+        {
+          :was => params.values_at(:first_name, :family_name, :last_name, :maiden_name, :phone).compact.join(' '),
+          :wo  => params.values_at(:street, :street_name, :street_number, :zip_code, :city).compact.join(' '),
+        }.reject { |k,v| v.empty? }
+      end
+
+      # @see SwissMatch::Directories#addresses
+      def addresses(params, options = {})
+        return [] if params.empty? # short-cut
+
+        # tel.search.ch parameters
+        search_params = {'key' => @key}
+
+        # Handle pagination parameters
+        per_page = options[:per_page] || 10
+        search_params['maxnum'] = per_page
+
+        page = options[:page] || 1
+        pos = (page - 1) * per_page + 1
+        search_params['pos'] = pos
+
+        # Request
+        uri       = @uri.dup
+        uri.query = URI.encode_www_form(search_ch_mapping(params).merge(search_params))
+        feed      = Nokogiri.XML(open(uri, &:read))
+
+        # Parse result
+        feed.css('entry').map { |entry|
+          Address.new(
+            nil,
+            extract(entry, 't|firstname'),
+            extract(entry, 't|name'),
+            extract(entry, 't|maidenname'),
+            extract(entry, 't|street'),
+            extract(entry, 't|streetno'),
+            extract(entry, 't|zip', &:to_i),
+            extract(entry, 't|city'),
+          )
+        }
+      end
+
+    private
+
+      # @private
+      # Get the text from a node with the given selector
+      def extract(node, selector)
+        subnode = node.at_css(selector, NS)
+        text    = subnode && subnode.text
+
+        block_given? ? yield(text) : text
+      end
+    end
+  end
+end

data/lib/swissmatch/directories/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 Directories
+
+    # The version of the swissmatch-directories gem.
+    Version = Gem::Version.new("0.0.1")
+  end
+end

data/swissmatch-directories.gemspec

@@ -0,0 +1,41 @@
+# encoding: utf-8
+
+Gem::Specification.new do |s|
+  s.name                      = "swissmatch-directories"
+  s.version                   = "0.0.1"
+  s.authors                   = "Stefan Rusterholz"
+  s.email                     = "stefan.rusterholz@gmail.com"
+  s.homepage                  = "http://github.com/apeiros/swissmatch-directories"
+
+  s.description               = <<-DESCRIPTION.gsub(/^    /, '').chomp
+    Query address data from swiss directory providers.
+  DESCRIPTION
+
+  s.summary                   = <<-SUMMARY.gsub(/^    /, '').chomp
+    Query address data from swiss directory providers.
+  SUMMARY
+
+  s.files                     =
+    Dir['bin/**/*'] +
+    Dir['data/**/*'] +
+    Dir['lib/**/*'] +
+    Dir['rake/**/*'] +
+    Dir['test/**/*'] +
+    Dir['*.gemspec'] +
+    %w[
+      LICENSE.txt
+      Rakefile
+      README.markdown
+    ]
+
+  if File.directory?('bin') then
+    executables = Dir.chdir('bin') { Dir.glob('**/*').select { |f| File.executable?(f) } }
+    s.executables = executables unless executables.empty?
+  end
+
+  s.add_dependency "nokogiri", ">= 1.5.0"
+
+  s.required_rubygems_version = Gem::Requirement.new("> 1.3.1")
+  s.rubygems_version          = "1.3.1"
+  s.specification_version     = 3
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: swissmatch-directories
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Stefan Rusterholz
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-08-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.5.0
+description: Query address data from swiss directory providers.
+email: stefan.rusterholz@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/swissmatch/directories/address.rb
+- lib/swissmatch/directories/service.rb
+- lib/swissmatch/directories/telsearch.rb
+- lib/swissmatch/directories/version.rb
+- lib/swissmatch/directories.rb
+- swissmatch-directories.gemspec
+- LICENSE.txt
+- Rakefile
+- README.markdown
+homepage: http://github.com/apeiros/swissmatch-directories
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>'
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Query address data from swiss directory providers.
+test_files: []
+has_rdoc: