undata 0.0.1

data/.idea/encodings.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Encoding" useUTFGuessing="true" native2AsciiForPropertiesFiles="false" />
+</project>
+

data/.idea/misc.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="DependencyValidationManager">
+    <option name="SKIP_IMPORT_STATEMENTS" value="false" />
+  </component>
+  <component name="ProjectRootManager" version="2" project-jdk-name="Ruby SDK 1.8.7-p330" project-jdk-type="RUBY_SDK" />
+</project>
+

data/.idea/modules.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/undata.iml" filepath="$PROJECT_DIR$/.idea/undata.iml" />
+    </modules>
+  </component>
+</project>
+

data/.idea/undata.iml

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="RUBY_MODULE" version="4">
+  <component name="GemRequirementsHolder" version="3">
+    <requirement>
+      <requirement>
+        <dependency name="mocha" version="0" bound="GREATER_OR_EQUAL" git="false" path="false" doRequire="true" />
+      </requirement>
+      <source from="test/helper.rb" />
+    </requirement>
+  </component>
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$" />
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+    <orderEntry type="library" scope="PROVIDED" name="[gem] rake (v0.8.7, /Users/gcb/.gem/ruby/1.8/gems/rake-0.8.7)" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="[gem] mocha (v0.9.12, /opt/local/lib/ruby/gems/1.8/gems/mocha-0.9.12)" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="[gem] test-unit (v2.2.0, /opt/local/lib/ruby/gems/1.8/gems/test-unit-2.2.0)" level="application" />
+  </component>
+  <component name="RModuleSettingsStorage" number="2" string0="$MODULE_DIR$/lib" string1="$MODULE_DIR$/test" />
+</module>
+

data/.idea/vcs.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>
+

data/README.rdoc

@@ -0,0 +1,42 @@
+= toxic
+
+* http://github.com/grahambrooks/undata
+
+== DESCRIPTION:
+
+This gem provides a client side interface for accessing UN data provided by the http://www.undata-api.org/ service. A user registration key is required to access the data.
+
+== FEATURES/PROBLEMS:
+
+* None
+
+== SYNOPSIS:
+
+== REQUIREMENTS:
+
+* 
+
+== INSTALL:
+
+== LICENSE:
+
+Copyright (c) 2011 Graham Brooks
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,36 @@
+require 'rake/testtask'
+require 'metric_fu'
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = false
+end
+
+task :default => :test
+
+namespace :test do
+  desc 'Measures test coverage'
+  task :coverage do
+    rm_f "coverage"
+    rm_f "coverage.data"
+    system 'rcov --aggregate coverage.data --text-summary -Ilib:test test/unit/un/data/*.rb'
+    system 'rcov --aggregate coverage.data --text-summary -Ilib:test test/integration/un/data/*.rb'
+  end
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.version
+    gem.name        = "undata"
+    gem.summary     = %Q{undata - UN Data client library}
+    gem.description = %Q{The UN have a number of initiatives to make data readily accessible. This library is intended to help in consuming and using that data.}
+    gem.homepage    = "http://github.com/grahambrooks/undata"
+    gem.email       = ["graham@grahambrooks.com"]
+    gem.authors     = ["Graham Brooks"]
+    gem.add_development_dependency "mocha", ">= 0"
+  end
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/lib/un/data/client.rb

@@ -0,0 +1,60 @@
+require 'un/data/host_adaptor'
+
+module UN
+  module Data
+    UNDATA_USER_KEY_NAME = 'UNDATA_USER_KEY'
+    HOST_NAME            = 'undata-api.appspot.com'
+
+    class Client
+      def initialize(options = {})
+        @host_adpator    = options[:host_adpator] || UN::Data::HostAdaptor.new
+        @response_parser = options[:response_parser] || UN::Data::ResponseParser.new
+
+        configure_user_key(options)
+      end
+
+      def configure_user_key(options)
+        @user_key = ENV[UNDATA_USER_KEY_NAME]
+
+        @user_key = options[:user_key] || @user_key || raise("User key (#{@user_key}) not specified")
+      end
+
+      def user_key
+        @user_key
+      end
+
+      def data_sets
+        uri = user_uri :path => '/data/index'
+
+        response = @host_adpator.get(uri)
+
+        @response_parser.parse_data_sets response
+      end
+
+      def general_query(name)
+        uri = user_uri :path => "/data/query/#{URI.escape(name, Regexp.new('[^#{URI::PATTERN::UNRESERVED}]'))}"
+
+        response = @host_adpator.get(uri)
+
+        @response_parser.parse_query_results response
+      end
+
+      def filtered_query(parameters = {})
+        path = '/data/query/'
+        path << URI.escape(parameters[:name], Regexp.new('[^#{URI::PATTERN::UNRESERVED}]')) || raise('Dataset parameter required for general queries')
+        path << '/' << URI.escape(parameters[:year]) unless parameters[:year].nil?
+        path << '/' << URI.escape(parameters[:country]) unless parameters[:country].nil?
+
+        uri = user_uri :path => path
+
+        response = @host_adpator.get(uri)
+
+        @response_parser.parse_filter_query response
+      end
+
+      def user_uri(options = {})
+        URI::HTTP.build :host => HOST_NAME, :path => options[:path], :query => "user_key=#{@user_key}"
+      end
+    end
+  end
+end

data/lib/un/data/host_adaptor.rb

@@ -0,0 +1,16 @@
+require 'net/http'
+
+
+module UN
+  module Data
+    class HostAdaptor
+      def get(uri)
+        result = Net::HTTP.start(uri.host, uri.port) do |http|
+          http.get "#{uri.path}?#{uri.query}"
+        end
+
+        result.body
+      end
+    end
+  end
+end

data/lib/un/data/response_parser.rb

@@ -0,0 +1,100 @@
+require 'rexml/document'
+require 'ostruct'
+
+module UN
+  module Data
+    class QueryResult
+      def initialize(values)
+        @data = {}
+        values.each do |key, value|
+          @data[key] = value
+        end
+      end
+
+      def [](key)
+        @data[key]
+      end
+
+      def length
+        @data.length
+      end
+
+      def to_s
+        result = ""
+        @data.each do |key, value|
+          result << "#{key} = #{value}\n"
+        end
+        result
+      end
+    end
+
+    class ResponseParser
+      def initialize(options={})
+      end
+
+      def check_for_errors(document)
+        document.elements.each("/error") do |element|
+          raise element.text
+        end
+      end
+
+      def parse_data_sets(data)
+        document = REXML::Document.new data
+
+        check_for_errors document
+
+        result = []
+        document.elements.each("/datasets/dataset") do |element|
+          result << OpenStruct.new(:organisation => element.attributes['organisation'],
+                                   :category => element.attributes['category'],
+                                   :name => element.attributes['name'])
+        end
+
+        result
+      end
+
+
+      def parse_query_results(data)
+        document = REXML::Document.new data
+
+        check_for_errors document
+
+        result = []
+
+        document.elements.each("/data/record") do |element|
+
+          fields ={}
+
+          element.elements.each do |e|
+            fields[e.attributes['name']] = e.text
+          end
+
+          result << QueryResult.new(fields)
+        end
+
+        result
+      end
+
+      def parse_filter_query(data)
+        document = REXML::Document.new data
+
+        check_for_errors document
+
+        result = []
+
+        document.elements.each("/data/record") do |element|
+
+          fields ={}
+
+          element.elements.each do |e|
+            fields[e.attributes['name']] = e.text
+          end
+
+          result << QueryResult.new(fields)
+        end
+
+        result
+      end
+    end
+  end
+end

data/test/helper.rb

@@ -0,0 +1,64 @@
+begin
+  require 'rubygems'
+  gem 'mocha'
+rescue LoadError
+end
+require 'rubygems'
+require 'stringio'
+require 'test/unit'
+require 'mocha'
+
+module DeclarativeTestMethods
+  def self.extended(klass)
+    klass.class_eval do
+
+      unless method_defined?(:describe)
+        def self.describe(text)
+          class_eval <<-RUBY_EVAL, __FILE__, __LINE__ + 1
+                def self.name
+                  "#{text}"
+                end
+          RUBY_EVAL
+        end
+      end
+
+    end
+  end
+
+  unless defined?(Spec)
+    # test "verify something" do
+    #   ...
+    # end
+    def test(name, &block)
+      test_name = "test_#{name.gsub(/\s+/, '_')}".to_sym
+      defined = instance_method(test_name) rescue false
+      raise "#{test_name} is already defined in #{self}" if defined
+      if block_given?
+        define_method(test_name, &block)
+      else
+        define_method(test_name) do
+          fail "No implementation provided for #{name}"
+        end
+      end
+    end
+  end
+end
+
+class TestCase < Test::Unit::TestCase
+  extend DeclarativeTestMethods
+
+  def default_test
+  end
+end
+
+module StdioHelper
+  def capture_stdout
+    s = StringIO.new
+    old_stdout = $stdout
+    $stdout = s
+    yield
+    s.string
+  ensure
+    $stdout = old_stdout
+  end
+end

data/test/integration/un/data/test_client_integration.rb

@@ -0,0 +1,39 @@
+require 'helper'
+require 'un/data/client'
+
+class TestClient < TestCase
+  test "user key read from environment" do
+    client = UN::Data::Client.new
+
+    assert_equal 32, client.user_key.length
+  end
+
+  test 'retrieve datasets' do
+    client = UN::Data::Client.new
+
+    assert client.data_sets.length > 1
+  end
+
+  test 'query data' do
+    client = UN::Data::Client.new
+
+    data_sets = client.data_sets
+
+    result = client.general_query data_sets.first.name
+
+    assert result.length > 0
+  end
+
+  test 'filtered query' do
+    client = UN::Data::Client.new
+
+    data_sets = client.data_sets
+    general = client.general_query data_sets.first.name
+
+    result = client.filtered_query(:name => data_sets[0].name,
+                                   :country => general[0]['Country or Area'],
+                                   :year => general[0]['Year(s)'])
+
+    assert result.length > 0
+  end
+end

data/test/unit/un/data/test_client.rb

@@ -0,0 +1,65 @@
+require 'helper'
+require 'un/data/client'
+
+class TestClient < TestCase
+  test 'can instanciate a client' do
+    UN::Data::Client.new :user_key => ''
+  end
+
+  def using_environment(options, &block)
+    original = {}
+    options.each do |key, value|
+      original[key] = ENV[key]
+      ENV[key]      = value
+    end
+    yield
+    original.each do |key, value|
+      ENV[key] = value
+    end
+  end
+
+  test 'client requires a user key' do
+    using_environment UN::Data::UNDATA_USER_KEY_NAME => nil do
+      assert_raises RuntimeError do
+        UN::Data::Client.new
+      end
+    end
+  end
+
+  test 'client reads user key from environment if not specified' do
+
+    using_environment UN::Data::UNDATA_USER_KEY_NAME => 'foo' do
+      client = UN::Data::Client.new
+
+      assert_equal 'foo', client.user_key
+    end
+  end
+
+  test 'client requests appropriate URL' do
+    mock_host_adaptor = mock('host adaptor')
+      
+    mock_host_adaptor.expects(:get).with(any_parameters)
+      
+    client = UN::Data::Client.new :user_key => 'foo', :host_adpator => mock_host_adaptor
+
+    client.data_sets
+  end
+
+  test 'user uri include the user key' do
+    client = UN::Data::Client.new :user_key => 'foo'
+
+    uri = client.user_uri :path => '/'
+
+    assert_equal 'undata-api.appspot.com', uri.host
+    assert_equal '/', uri.path
+  end
+
+  test 'client parses response' do
+    mock_parser = mock('response parser')
+    mock_parser.expects(:parse_data_sets).with('some xml')
+    
+    client = UN::Data::Client.new :user_key => 'foo', :host_adpator => stub(:get => "some xml"), :response_parser => mock_parser
+
+    client.data_sets
+  end
+end

data/test/unit/un/data/test_host_adaptor.rb

@@ -0,0 +1,8 @@
+require 'helper'
+
+
+class TestHostAdaptor < TestCase
+  test 'can instantiate a host adaptor' do
+    UN::Data::HostAdaptor.new
+  end
+end

data/test/unit/un/data/test_query_result.rb

@@ -0,0 +1,16 @@
+require 'helper'
+require 'un/data/response_parser'
+
+class TestQueryResult < TestCase
+  test 'results contain value' do
+    result = UN::Data::QueryResult.new 'key' => 'value'
+
+    assert_equal 'value', result['key']
+  end
+
+  test 'results can be represented as text' do
+    result = UN::Data::QueryResult.new 'key' => 'value'
+
+    assert_equal "key = value\n", result.to_s
+  end
+end

data/test/unit/un/data/test_response_parser.rb

@@ -0,0 +1,84 @@
+require 'helper'
+require 'un/data/response_parser'
+
+class TestResponseParser < TestCase
+
+  test 'can instantiate a parser' do
+    UN::Data::ResponseParser.new
+  end
+
+  test 'parses basic datasets' do
+    single_entry = <<EOD
+<datasets>
+  <dataset organisation='IMF' category='International Financial statistics' name='BOP: capital account credit, US$'  />
+</datasets>
+EOD
+    parser = UN::Data::ResponseParser.new
+
+    data = parser.parse_data_sets single_entry
+
+    assert_equal 1, data.length
+    assert_equal 'IMF', data[0].organisation
+    assert_equal 'International Financial statistics', data[0].category
+    assert_equal 'BOP: capital account credit, US$', data[0].name
+  end
+
+  test "parses general query results" do
+    query_result = <<EOD
+<data>
+   <record>
+     <field name="Country or Area">Afghanistan</field>
+     <field name="Year(s)">2001</field>
+     <field name="Value">151</field>
+   </record>
+</data>
+EOD
+    parser = UN::Data::ResponseParser.new
+
+    data = parser.parse_query_results query_result
+
+    assert_equal 1, data.length
+    assert_equal 3, data[0].length
+    assert_equal 'Afghanistan', data[0]["Country or Area"]
+    assert_equal '2001', data[0]['Year(s)']
+    assert_equal '151', data[0]['Value']
+  end
+
+  test "handles error elements as exceptions" do
+    error_data = <<EOD
+<?xml version="1.0" encoding="utf-8"?><error id="user.invalid_key">user_key is invalid</error>
+EOD
+    
+    parser = UN::Data::ResponseParser.new
+    
+    assert_raises RuntimeError do
+      parser.parse_data_sets error_data
+    end
+
+    assert_raises RuntimeError do
+      parser.parse_query_results error_data
+    end
+  end
+
+  test 'handles filtered query results' do
+    query_result = <<EOD
+<data organisation="WHO" 
+      category="Demographic and socioeconomic statistics" 
+      name="Adolescent fertility rate">
+	<record>
+		<field name="Country or Area">Albania</field>
+		<field name="Year(s)">2001</field>
+	<field name="Value">98.7</field>
+	</record>
+</data>
+EOD
+    parser = UN::Data::ResponseParser.new
+
+    data = parser.parse_filter_query query_result
+
+    assert_equal 1, data.length
+    assert_equal 'Albania', data[0]['Country or Area']
+    assert_equal '2001', data[0]['Year(s)']
+    assert_equal '98.7', data[0]['Value']
+  end
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification 
+name: undata
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Graham Brooks
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-05-15 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id001
+description: The UN have a number of initiatives to make data readily accessible. This library is intended to help in consuming and using that data.
+email: 
+- graham@grahambrooks.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- .idea/encodings.xml
+- .idea/misc.xml
+- .idea/modules.xml
+- .idea/undata.iml
+- .idea/vcs.xml
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/un/data/client.rb
+- lib/un/data/host_adaptor.rb
+- lib/un/data/response_parser.rb
+- test/helper.rb
+- test/integration/un/data/test_client_integration.rb
+- test/unit/un/data/test_client.rb
+- test/unit/un/data/test_host_adaptor.rb
+- test/unit/un/data/test_query_result.rb
+- test/unit/un/data/test_response_parser.rb
+homepage: http://github.com/grahambrooks/undata
+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: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.7.2
+signing_key: 
+specification_version: 3
+summary: undata - UN Data client library
+test_files: []
+