parliament-ruby 0.5.19 → 0.6.0

data/lib/parliament/utils.rb

@@ -1,35 +1,135 @@
 module Parliament
+  # Namespace for helper methods used with parliament-ruby.
+  #
+  # @since 0.6.0
   module Utils
+    # Sort an Array of Objects in ascending order. The major difference between this implementation of sort_by and the
+    # standard one is that our implementation includes objects that return nil for our parameter values.
+    #
+    # @see Parliament::Utils.reverse_sort_by
+    #
+    # @example Sorting a list of objects by date
+    #   response = parliament.people('123').get.filter('http://id.ukpds.org/schema/Person')
+    #
+    #   objects = response.first.incumbencies
+    #
+    #   args = {
+    #     list: objects,
+    #     parameters: [:endDate],
+    #     prepend_rejected: false
+    #   }
+    #
+    #   sorted_list = Parliament::Util.sort_by(args)
+    #
+    #   sorted_list.each { |incumbency| puts incumbency.respond_to?(:endDate) ? incumbency.endDate : 'Current' }
+    #   # http://id.ukpds.org/1121 - 1981-07-31
+    #   # http://id.ukpds.org/5678 - 1991-03-15
+    #   # http://id.ukpds.org/1234 - 1997-01-01
+    #   # http://id.ukpds.org/9101 - 2011-09-04
+    #   # http://id.ukpds.org/3141 - Current
+    #
+    # @param [Hash] args a hash of arguments.
+    # @option args [Array<Object>] :list the 'list' which we are sorting.
+    # @option args [Array<Symbol>] :parameters an array of parameters we are sorting by.
+    # @option args [Boolean] :prepend_rejected (true) should objects that do not respond to our parameters be prepended?
+    #
+    # @return [Array<Object>] a sorted array of objects using the args passed in.
     def self.sort_by(args)
       rejected = []
       args = sort_defaults.merge(args)
       list = args[:list].dup
       parameters = args[:parameters]
 
-      list.delete_if do |object|
-        rejected << object unless parameters.all? { |param| !object.send(param).nil? if object.respond_to?(param) }
-      end
+      list, rejected = prune_list(list, rejected, parameters)
 
-      list.sort_by! do |object|
-        parameters.map do |param|
-          object.send(param).is_a?(String) ? I18n.transliterate(object.send(param)).downcase : object.send(param)
-        end
-      end
+      list = sort_list(list, parameters)
 
       # Any rejected (nil) values will be added to the start of the result unless specified otherwise
       args[:prepend_rejected] ? rejected.concat(list) : list.concat(rejected)
     end
 
+    # Sort an Array of Objects in descending order. Largely, this implementation runs Parliament::Utils.sort_by and
+    # calls reverse! on the result.
+    #
+    # @see Parliament::Utils.sort_by
+    #
+    # @example Sorting a list of objects by date
+    #   response = parliament.people('123').get.filter('http://id.ukpds.org/schema/Person')
+    #
+    #   objects = response.first.incumbencies
+    #
+    #   args = {
+    #     list: objects,
+    #     parameters: [:endDate],
+    #     prepend_rejected: false
+    #   }
+    #
+    #   sorted_list = Parliament::Util.reverse_sort_by(args)
+    #
+    #   sorted_list.each { |incumbency| puts incumbency.respond_to?(:endDate) ? incumbency.endDate : 'Current' }
+    #   # http://id.ukpds.org/3141 - Current
+    #   # http://id.ukpds.org/9101 - 2011-09-04
+    #   # http://id.ukpds.org/1234 - 1997-01-01
+    #   # http://id.ukpds.org/5678 - 1991-03-15
+    #   # http://id.ukpds.org/1121 - 1981-07-31
+    #
+    # @param [Hash] args a hash of arguments.
+    # @option args [Array<Object>] :list the 'list' which we are sorting.
+    # @option args [Array<Symbol>] :parameters an array of parameters we are sorting by.
+    # @option args [Boolean] :prepend_rejected (true) should objects that do not respond to our parameters be prepended?
+    #
+    # @return [Array<Object>] a sorted array of objects using the args passed in.
     def self.reverse_sort_by(args)
       Parliament::Utils.sort_by(args).reverse!
     end
 
-    private_class_method
-
+    # Default arguments hash for #sort_by and #reverse_sort_by.
+    #
+    # @see Parliament::Utils.sort_by
+    # @see Parliament::Utils.reverse_sort_by
+    #
+    # @return [Hash] default arguments used in sorting methods.
     def self.sort_defaults
-      {
-        prepend_rejected: true
-      }
+      { prepend_rejected: true }
+    end
+
+    # @!method self.prune_list(list, rejected, parameters)
+    # Prune all objects that do not respond to a given array of parameters.
+    #
+    # @private
+    # @!scope class
+    # @!visibility private
+    #
+    # @param [Array<Object>] list the 'list' of objects we are pruning from.
+    # @param [Array<Object>] rejected the objects we have pruned from list.
+    # @param [Array<Symbol>] parameters an array of parameters we are checking.
+    #
+    # @return [Array<Array<Object>, Array<Object>>] an array containing first, the pruned list and secondly, the rejected list.
+    private_class_method def self.prune_list(list, rejected, parameters)
+      list.delete_if do |object|
+        rejected << object unless parameters.all? { |param| !object.send(param).nil? if object.respond_to?(param) }
+      end
+
+      [list, rejected]
+    end
+
+    # @!method self.sort_list(list, parameters)
+    # Sort a given list of objects by a list of parameters.
+    #
+    # @private
+    # @!scope class
+    # @!visibility private
+    #
+    # @param [Array<Object>] list the 'list' of objects we are pruning from.
+    # @param [Array<Symbol>] parameters an array of parameters we are checking.
+    #
+    # @return [Array<Object>] our sorted list.
+    private_class_method def self.sort_list(list, parameters)
+      list.sort_by! do |object|
+        parameters.map do |param|
+          object.send(param).is_a?(String) ? I18n.transliterate(object.send(param)).downcase : object.send(param)
+        end
+      end
     end
   end
 end

data/lib/parliament/version.rb

@@ -1,3 +1,3 @@
 module Parliament
-  VERSION = '0.5.19'.freeze
+  VERSION = '0.6.0'.freeze
 end

data/lib/parliament.rb

@@ -5,11 +5,15 @@ require 'parliament/version'
 require 'parliament/request'
 require 'parliament/response'
 require 'parliament/utils'
-require 'parliament/no_content_error'
+require 'parliament/decorator'
 
-# require all the decorators
-Dir[File.join(File.dirname(__FILE__), 'parliament/decorators', '*.rb')].each { |decorator| require decorator }
+require 'parliament/network_error'
+require 'parliament/client_error'
+require 'parliament/server_error'
+require 'parliament/no_content_response_error'
 
+# Namespace for classes and modules that handle connections to, and processing of data from the parliamentary API.
+# @since 0.0.1
 module Parliament
-  # Your code goes here...
+  # Currently just a namespace definition
 end

data/parliament-ruby.gemspec

@@ -8,10 +8,10 @@ Gem::Specification.new do |spec|
   spec.version       = Parliament::VERSION
   spec.authors       = ['Matt Rayner']
   spec.email         = ['mattrayner1@gmail.com']
-  spec.summary       = %q{Internal parliamentary data API wrapper for ruby}
+  spec.summary       = %q{Internal parliamentary API wrapper}
   spec.description   = %q{Internal parliamentary data API wrapper for ruby}
   spec.homepage      = 'http://github.com/ukparliament/parliament_ruby'
-  spec.license       = 'Open Parliament License'
+  spec.license       = 'Nonstandard'
 
 
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|
@@ -26,8 +26,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'bundler', '~> 1.13'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
-  spec.add_development_dependency 'rubocop', '~> 0.47.1'
-  spec.add_development_dependency 'simplecov', '~> 0.12.0'
-  spec.add_development_dependency 'vcr', '~> 3.0.3'
-  spec.add_development_dependency 'webmock', '~> 2.3.2'
+  spec.add_development_dependency 'rubocop', '~> 0.47'
+  spec.add_development_dependency 'simplecov', '~> 0.12'
+  spec.add_development_dependency 'vcr', '~> 3.0'
+  spec.add_development_dependency 'webmock', '~> 2.3'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: parliament-ruby
 version: !ruby/object:Gem::Version
-  version: 0.5.19
+  version: 0.6.0
 platform: ruby
 authors:
 - Matt Rayner
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-03-14 00:00:00.000000000 Z
+date: 2017-03-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grom
@@ -72,56 +72,56 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.47.1
+        version: '0.47'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.47.1
+        version: '0.47'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.12.0
+        version: '0.12'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.12.0
+        version: '0.12'
 - !ruby/object:Gem::Dependency
   name: vcr
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.0.3
+        version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.0.3
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.3.2
+        version: '2.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.3.2
+        version: '2.3'
 description: Internal parliamentary data API wrapper for ruby
 email:
 - mattrayner1@gmail.com
@@ -144,29 +144,33 @@ files:
 - bin/console
 - bin/setup
 - lib/parliament.rb
-- lib/parliament/decorators/constituency_area.rb
-- lib/parliament/decorators/constituency_group.rb
-- lib/parliament/decorators/contact_point.rb
-- lib/parliament/decorators/gender.rb
-- lib/parliament/decorators/gender_identity.rb
-- lib/parliament/decorators/house.rb
-- lib/parliament/decorators/house_incumbency.rb
-- lib/parliament/decorators/house_seat.rb
-- lib/parliament/decorators/incumbency.rb
-- lib/parliament/decorators/party.rb
-- lib/parliament/decorators/party_membership.rb
-- lib/parliament/decorators/person.rb
-- lib/parliament/decorators/postal_address.rb
-- lib/parliament/decorators/seat_incumbency.rb
-- lib/parliament/no_content_error.rb
+- lib/parliament/client_error.rb
+- lib/parliament/decorator.rb
+- lib/parliament/decorator/constituency_area.rb
+- lib/parliament/decorator/constituency_group.rb
+- lib/parliament/decorator/contact_point.rb
+- lib/parliament/decorator/gender.rb
+- lib/parliament/decorator/gender_identity.rb
+- lib/parliament/decorator/house.rb
+- lib/parliament/decorator/house_incumbency.rb
+- lib/parliament/decorator/house_seat.rb
+- lib/parliament/decorator/incumbency.rb
+- lib/parliament/decorator/party.rb
+- lib/parliament/decorator/party_membership.rb
+- lib/parliament/decorator/person.rb
+- lib/parliament/decorator/postal_address.rb
+- lib/parliament/decorator/seat_incumbency.rb
+- lib/parliament/network_error.rb
+- lib/parliament/no_content_response_error.rb
 - lib/parliament/request.rb
 - lib/parliament/response.rb
+- lib/parliament/server_error.rb
 - lib/parliament/utils.rb
 - lib/parliament/version.rb
 - parliament-ruby.gemspec
 homepage: http://github.com/ukparliament/parliament_ruby
 licenses:
-- Open Parliament License
+- Nonstandard
 metadata: {}
 post_install_message: 
 rdoc_options: []
@@ -184,8 +188,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.6
+rubygems_version: 2.6.10
 signing_key: 
 specification_version: 4
-summary: Internal parliamentary data API wrapper for ruby
+summary: Internal parliamentary API wrapper
 test_files: []

data/lib/parliament/decorators/constituency_area.rb

@@ -1,17 +0,0 @@
-module Parliament
-  module Decorators
-    module ConstituencyArea
-      def latitude
-        respond_to?(:constituencyAreaLatitude) ? constituencyAreaLatitude : ''
-      end
-
-      def longitude
-        respond_to?(:constituencyAreaLongitude) ? constituencyAreaLongitude : ''
-      end
-
-      def polygon
-        respond_to?(:constituencyAreaExtent) ? constituencyAreaExtent : ''
-      end
-    end
-  end
-end

data/lib/parliament/decorators/contact_point.rb

@@ -1,29 +0,0 @@
-module Parliament
-  module Decorators
-    module ContactPoint
-      def postal_addresses
-        respond_to?(:contactPointHasPostalAddress) ? contactPointHasPostalAddress : []
-      end
-
-      def email
-        instance_variable_get('@email'.to_sym).nil? ? '' : instance_variable_get('@email'.to_sym)
-      end
-
-      def phone_number
-        respond_to?(:phoneNumber) ? phoneNumber : ''
-      end
-
-      def fax_number
-        respond_to?(:faxNumber) ? faxNumber : ''
-      end
-
-      def person
-        respond_to?(:contactPointHasPerson) ? contactPointHasPerson : []
-      end
-
-      def incumbency
-        respond_to?(:contactPointHasIncumbency) ? contactPointHasIncumbency.first : nil
-      end
-    end
-  end
-end

data/lib/parliament/decorators/gender.rb

@@ -1,9 +0,0 @@
-module Parliament
-  module Decorators
-    module Gender
-      def name
-        respond_to?(:genderName) ? genderName : ''
-      end
-    end
-  end
-end

data/lib/parliament/decorators/gender_identity.rb

@@ -1,9 +0,0 @@
-module Parliament
-  module Decorators
-    module GenderIdentity
-      def gender
-        respond_to?(:genderIdentityHasGender) ? genderIdentityHasGender.first : nil
-      end
-    end
-  end
-end

data/lib/parliament/decorators/house.rb

@@ -1,28 +0,0 @@
-module Parliament
-  module Decorators
-    module House
-      def name
-        respond_to?(:houseName) ? houseName : ''
-      end
-
-      def seat_incumbencies
-        return @seat_incumbencies unless @seat_incumbencies.nil?
-
-        seat_incumbencies = []
-        seats.each do |seat|
-          seat_incumbencies << seat.seat_incumbencies
-        end
-
-        @seat_incumbencies = seat_incumbencies.flatten.uniq
-      end
-
-      def seats
-        respond_to?(:houseHasHouseSeat) ? houseHasHouseSeat : []
-      end
-
-      def house_incumbencies
-        respond_to?(:houseHasHouseIncumbency) ? houseHasHouseIncumbency : []
-      end
-    end
-  end
-end

data/lib/parliament/decorators/house_incumbency.rb

@@ -1,31 +0,0 @@
-module Parliament
-  module Decorators
-    module HouseIncumbency
-      def start_date
-        respond_to?(:incumbencyStartDate) ? DateTime.parse(incumbencyStartDate) : nil
-      end
-
-      def end_date
-        respond_to?(:incumbencyEndDate) ? DateTime.parse(incumbencyEndDate) : nil
-      end
-
-      def current?
-        has_end_date = respond_to?(:incumbencyEndDate)
-
-        !has_end_date
-      end
-
-      def house
-        respond_to?(:houseIncumbencyHasHouse) ? houseIncumbencyHasHouse.first : nil
-      end
-
-      def member
-        respond_to?(:incumbencyHasMember) ? incumbencyHasMember.first : nil
-      end
-
-      def contact_points
-        respond_to?(:incumbencyHasContactPoint) ? incumbencyHasContactPoint : []
-      end
-    end
-  end
-end