parliament-ruby 0.5.19 → 0.6.0

data/lib/parliament/{decorators → decorator}/postal_address.rb

@@ -1,6 +1,10 @@
 module Parliament
-  module Decorators
+  module Decorator
+    # Decorator namespace for Grom::Node instances with type: http://id.ukpds.org/schema/PostalAddress
     module PostalAddress
+      # Builds a full address using the lines of the address and the postcode.
+      #
+      # @return [String, String] the full address of the Grom::Node or an empty string.
       def full_address
         address_array.join(', ')
       end

data/lib/parliament/decorator/seat_incumbency.rb

@@ -0,0 +1,64 @@
+module Parliament
+  module Decorator
+    # Decorator namespace for Grom::Node instances with type: http://id.ukpds.org/schema/SeatIncumbency
+    module SeatIncumbency
+      # Alias incumbencyStartDate with fallback.
+      #
+      # @return [DateTime, nil] the start date of the Grom::Node or nil.
+      def start_date
+        respond_to?(:incumbencyStartDate) ? DateTime.parse(incumbencyStartDate) : nil
+      end
+
+      # Alias incumbencyEndDate with fallback.
+      #
+      # @return [DateTime, nil] the end date of the Grom::Node or nil.
+      def end_date
+        respond_to?(:incumbencyEndDate) ? DateTime.parse(incumbencyEndDate) : nil
+      end
+
+      # Alias seatIncumbencyHasHouseSeat with fallback.
+      #
+      # @return [Grom::Node, nil] the seat of the Grom::Node or nil.
+      def seat
+        respond_to?(:seatIncumbencyHasHouseSeat) ? seatIncumbencyHasHouseSeat.first : nil
+      end
+
+      # Checks if Grom::Node has an end date.
+      #
+      # @return [Boolean] a boolean depending on whether or not the Grom::Node has an end date.
+      def current?
+        has_end_date = respond_to?(:incumbencyEndDate)
+
+        !has_end_date
+      end
+
+      # Alias houseSeatHasHouse with fallback.
+      #
+      # @return [Grom::Node, nil] the house of the Grom::Node or nil.
+      def house
+        seat.nil? ? nil : seat.house
+      end
+
+      # Alias houseSeatHasConstituencyGroup with fallback.
+      #
+      # @return [Grom::Node, nil] the constituency of the Grom::Node or nil.
+      def constituency
+        seat.nil? ? nil : seat.constituency
+      end
+
+      # Alias incumbencyHasContactPoint with fallback.
+      #
+      # @return [Array, Array] the contact points of the Grom::Node or an empty array.
+      def contact_points
+        respond_to?(:incumbencyHasContactPoint) ? incumbencyHasContactPoint : []
+      end
+
+      # Alias incumbencyHasMember with fallback.
+      #
+      # @return [Grom::Node, nil] the member connected to the Grom::Node or nil.
+      def member
+        respond_to?(:incumbencyHasMember) ? incumbencyHasMember.first : nil
+      end
+    end
+  end
+end

data/lib/parliament/decorator.rb

@@ -0,0 +1,7 @@
+module Parliament
+  # Decorator namespace
+  module Decorator
+    # require all the decorators
+    Dir[File.join(File.dirname(__FILE__), '../parliament/decorator', '*.rb')].each { |decorator| require decorator }
+  end
+end

data/lib/parliament/network_error.rb

@@ -0,0 +1,13 @@
+module Parliament
+  # A parent class that standardises the error message generated for network errors.
+  #
+  # @see Parliament::ClientError
+  # @see Parliament::ServerError
+  #
+  # @since 0.6.0
+  class NetworkError < StandardError
+    def initialize(url, response)
+      super("#{response.code} HTTP status code received from: #{url} - #{response.message}")
+    end
+  end
+end

data/lib/parliament/no_content_response_error.rb

@@ -0,0 +1,19 @@
+module Parliament
+  # An error raised when a 204 status code is returned by Net::HTTP inside of Parliament::Request.
+  #
+  # @since 0.6.0
+  class NoContentResponseError < Parliament::NetworkError
+    # @param [String] url the url that caused the Parliament::ClientError
+    # @param [Net::HTTPResponse] response the Net:HTTPResponse that caused the Parliament::NoContentResponseError
+    #
+    # @example Creating a Parliament::NoContentResponseError
+    #   url = 'http://localhost:3030/foo/bar'
+    #
+    #   response = Net::HTTP.get_response(URI(url))
+    #
+    #   raise Parliament::NoContentResponseError.new(url, response) if response.code == '204'
+    def initialize(url, response)
+      super
+    end
+  end
+end

data/lib/parliament/request.rb

@@ -1,26 +1,109 @@
 module Parliament
+  # API request object, allowing the user to build a request to a graph-based API, download n-triple data and create
+  # ruby objects from that data.
+  #
+  # @since 0.1.0
+  #
+  # @attr_reader [String] base_url the base url of our api. (expected: http://example.com - without the trailing slash).
   class Request
     attr_reader :base_url
 
+    # Creates a new instance of Parliament::Request.
+    #
+    # An interesting note for #initialize is that setting base_url on the class, or using the environment variable
+    # PARLIAMENT_BASE_URL means you don't need to pass in a base_url. You can pass one anyway to override the
+    # environment variable or class parameter.
+    #
+    # @example Setting the base_url on the class
+    #   Parliament::Request.base_url = 'http://example.com'
+    #
+    #   Parliament::Request.new.base_url #=> 'http://example.com'
+    #
+    # @example Setting the base_url via environment variable
+    #   ENV['PARLIAMENT_BASE_URL'] #=> 'http://test.com'
+    #
+    #   Parliament::Request.new.base_url #=> 'http://test.com'
+    #
+    # @example Setting the base_url via a parameter
+    #   Parliament::Request.base_url #=> nil
+    #   ENV['PARLIAMENT_BASE_URL'] #=> nil
+    #
+    #   Parliament::Request.new(base_url: 'http://example.com').base_url #=> 'http://example.com'
+    #
+    # @example Overriding the base_url via a parameter
+    #   ENV['PARLIAMENT_BASE_URL'] #=> 'http://test.com'
+    #
+    #   Parliament::Request.new(base_url: 'http://example.com').base_url #=> 'http://example.com'
+    #
+    # @param [String] base_url the base url of our api. (expected: http://example.com - without the trailing slash).
     def initialize(base_url: nil)
       @endpoint_parts = []
       @base_url = base_url || self.class.base_url || ENV['PARLIAMENT_BASE_URL']
     end
 
+    # Overrides ruby's method_missing to allow creation of URLs through method calls.
+    #
+    # @example Adding a simple URL part
+    #   request = Parliament::Request.new(base_url: 'http://example.com')
+    #
+    #   # url: http://example.com/people
+    #   request.people
+    #
+    # @example Adding a simple URL part with parameters
+    #   request = Parliament::Request.new(base_url: 'http://example.com')
+    #
+    #   # url: http://example.com/people/123456
+    #   request.people('123456')
+    #
+    # @example Chaining URL parts and using hyphens
+    #   request = Parliament::Request.new(base_url: 'http://example.com')
+    #
+    #   # url: http://example.com/people/123456/foo/bar/hello-world/7890
+    #   request.people('123456').foo.bar('hello-world', '7890')
+    #
+    # @param [Symbol] method the 'method' (url part) we are processing.
+    # @param [Array<Object>] params parameters passed to the specified method (url part).
+    # @param [Block] block additional block (kept for compatibility with method_missing API).
+    #
+    # @return [Parliament::Request] self.
     def method_missing(method, *params, &block)
-      # TODO: Fix this smell
-      super if method == :base_url=
-
       @endpoint_parts << method.to_s
       @endpoint_parts << params
       @endpoint_parts = @endpoint_parts.flatten!
-      self
+
+      block&.call
+
+      self || super
     end
 
-    def respond_to_missing?(method, include_private = false)
-      (method != :base_url=) || super
+    # This class always responds to method calls, even those missing. Therefore, respond_to_missing? always returns true.
+    #
+    # @return [Boolean] always returns true.
+    def respond_to_missing?(_, _ = false)
+      true # responds to everything, always
     end
 
+    # Using our url built via #method_missing, make a HTTP GET request and process results into a response.
+    #
+    # @example HTTP GET request
+    #   request = Parliament::Request.new(base_url: 'http://example.com')
+    #
+    #   # url: http://example.com/people/123456
+    #   response = request.people('123456').get #=> #<Parliament::Response ...>
+    #
+    # @example HTTP GET request with URI encoded form values
+    #   request = Parliament::Request.new(base_url: 'http://example.com')
+    #
+    #   # url: http://example.com/people/current?limit=10&page=4&lang=en-gb
+    #   response = request.people.current.get({ limit: 10, page: 4, lang: 'en-gb' }) #=> #<Parliament::Response ...>
+    #
+    # @raise [Parliament::ServerError] when the server responds with a 5xx status code.
+    # @raise [Parliament::ClientError] when the server responds with a 4xx status code.
+    # @raise [Parliament::NoContentResponseError] when the server responds with a 204 status code.
+    #
+    # @param [Hash] params (optional) additional URI encoded form values to be added to the URI.
+    #
+    # @return [Parliament::Response] a Parliament::Response object containing all of the nodes returned from the URL.
     def get(params: nil)
       endpoint_uri = URI.parse(api_endpoint)
       endpoint_uri.query = URI.encode_www_form(params.to_a) unless params.nil?
@@ -32,29 +115,35 @@ module Parliament
       build_parliament_response(net_response)
     end
 
-    def build_parliament_response(response)
-      objects = Grom::Reader.new(response.body).objects
-      objects.map { |object| assign_decorator(object) }
+    private
 
-      Parliament::Response.new(objects)
+    # @attr [String] base_url the base url of our api. (expected: http://example.com - without the trailing slash).
+    class << self
+      attr_accessor :base_url
     end
 
-    def handle_errors(response)
-      handle_not_found_error(response)
-      handle_server_error(response)
-      handle_no_content_error(response)
+    def api_endpoint
+      [@base_url, @endpoint_parts].join('/')
     end
 
-    def handle_server_error(response)
-      raise StandardError, 'This is a HTTPServerError' if response.is_a?(Net::HTTPServerError)
+    def handle_errors(response)
+      case response
+      when Net::HTTPSuccess # 2xx Status
+        exception_class = Parliament::NoContentResponseError if response.code == '204'
+      when Net::HTTPClientError # 4xx Status
+        exception_class = Parliament::ClientError
+      when Net::HTTPServerError # 5xx Status
+        exception_class = Parliament::ServerError
+      end
+
+      raise exception_class.new(api_endpoint, response) if exception_class
     end
 
-    def handle_not_found_error(response)
-      raise StandardError, 'This is a HTTPClientError' if response.is_a?(Net::HTTPClientError)
-    end
+    def build_parliament_response(response)
+      objects = Grom::Reader.new(response.body).objects
+      objects.map { |object| assign_decorator(object) }
 
-    def handle_no_content_error(response)
-      raise Parliament::NoContentError if response.code == '204'
+      Parliament::Response.new(objects)
     end
 
     def assign_decorator(object)
@@ -62,20 +151,10 @@ module Parliament
 
       object_type = Grom::Helper.get_id(object.type)
 
-      return object unless Parliament::Decorators.constants.include?(object_type.to_sym)
+      return object unless Parliament::Decorator.constants.include?(object_type.to_sym)
 
-      decorator_module = Object.const_get("Parliament::Decorators::#{object_type}")
+      decorator_module = Object.const_get("Parliament::Decorator::#{object_type}")
       object.extend(decorator_module)
     end
-
-    private
-
-    class << self
-      attr_accessor :base_url
-    end
-
-    def api_endpoint
-      [@base_url, @endpoint_parts].join('/')
-    end
   end
 end

data/lib/parliament/response.rb

@@ -1,16 +1,65 @@
 require 'forwardable'
 
 module Parliament
+  # API response object that wraps an Array of Grom::Node objects with common helper methods.
+  #
+  # Delegates a number of common methods to the array of Grom::Nodes including, but not limited to, :size, :each, :map, :count etc.
+  #
+  # @since 0.1.0
+  #
+  # @attr_reader [Array<Grom::Node>] nodes Graph nodes.
   class Response
     include Enumerable
     extend Forwardable
     attr_reader :nodes
     def_delegators :@nodes, :size, :each, :select, :map, :select!, :map!, :count, :length, :[], :empty?
 
+    # @param [Array<Grom::Node>] nodes An array of nodes the response should wrap
     def initialize(nodes)
       @nodes = nodes
     end
 
+    # Given our array of Grom::Nodes, filter them into arrays of 'types' of nodes.
+    #
+    # Note: this method assumes all of your nodes include a #type attribute.
+    #
+    # @since 0.2.0
+    #
+    # @example Filtering for a single type
+    #    node_1 = Grom::Node.new
+    #    node_1.instance_variable_set(:type, 'type_1')
+    #    node_2 = Grom::Node.new
+    #    node_2.instance_variable_set(:type, 'type_3')
+    #    node_3 = Grom::Node.new
+    #    node_3.instance_variable_set(:type, 'type_1')
+    #    node_4 = Grom::Node.new
+    #    node_4.instance_variable_set(:type, 'type_2')
+    #    nodes = [node_1, node_2, node_3, node_4]
+    #
+    #    response = Parliament::Response.new(nodes)
+    #    response.filter('type_2') #=> [#<Grom::Node @type='type_2'>]
+    #
+    # @example Filtering for multiple types
+    #    node_1 = Grom::Node.new
+    #    node_1.instance_variable_set(:type, 'type_1')
+    #    node_2 = Grom::Node.new
+    #    node_2.instance_variable_set(:type, 'type_3')
+    #    node_3 = Grom::Node.new
+    #    node_3.instance_variable_set(:type, 'type_1')
+    #    node_4 = Grom::Node.new
+    #    node_4.instance_variable_set(:type, 'type_2')
+    #    nodes = [node_1, node_2, node_3, node_4]
+    #
+    #    response = Parliament::Response.new(nodes)
+    #    response.filter('type_2', 'type_1') #=> [[#<Grom::Node @type='type_2'>], [#<Grom::Node @type='type_1'>, #<Grom::Node @type='type_1'>]]
+    #
+    #    # Also consider
+    #    type_2, type_1 = response.filter('type_2', 'type_1')
+    #    type_2 #=> [#<Grom::Node @type='type_2'>]
+    #    type_1 #=> [#<Grom::Node @type='type_1'>, #<Grom::Node @type='type_1'>]
+    #
+    # @param [Array<String>] types An array of type strings that you are looking for.
+    # @return [Array<Grom::Node> || Array<*Array<Grom::Node>>] If you pass one type, this returns an Array of Grom::Node objects. If you pass multiple, it returns an array, of arrays of Grom::Node objects.
     def filter(*types)
       filtered_objects = Array.new(types.size) { [] }
 
@@ -26,15 +75,14 @@ module Parliament
       types.size == 1 ? result.first : result
     end
 
-    def build_responses(filtered_objects)
-      result = []
-
-      filtered_objects.each do |objects|
-        result << Parliament::Response.new(objects)
-      end
-      result
-    end
-
+    # Sort the Parliament::Response nodes in ascending order by a set of attributes on each node.
+    #
+    # @see Parliament::Utils.sort_by
+    #
+    # @since 0.5.0
+    #
+    # @param [Array<Symbol>] parameters Attributes to sort on - left to right.
+    # @return [Array<Grom::Node>] A sorted array of nodes.
     def sort_by(*parameters)
       Parliament::Utils.sort_by({
         list:       @nodes,
@@ -42,11 +90,30 @@ module Parliament
       })
     end
 
+    # Sort the Parliament::Response nodes in descending order by a set of attributes on each node.
+    #
+    # @see Parliament::Utils.reverse_sort_by
+    #
+    # @since 0.5.0
+    #
+    # @param [Array<Symbol>] parameters Attributes to sort on - left to right.
+    # @return [Array<Grom::Node>] A sorted array of nodes.
     def reverse_sort_by(*parameters)
       Parliament::Utils.reverse_sort_by({
         list:       @nodes,
         parameters: parameters
       })
     end
+
+    private
+
+    def build_responses(filtered_objects)
+      result = []
+
+      filtered_objects.each do |objects|
+        result << Parliament::Response.new(objects)
+      end
+      result
+    end
   end
 end

data/lib/parliament/server_error.rb

@@ -0,0 +1,21 @@
+module Parliament
+  # An error raised when a 5xx status code is returned by Net::HTTP inside of Parliament::Request.
+  #
+  # @see Parliament::ClientError
+  #
+  # @since 0.6.0
+  class ServerError < Parliament::NetworkError
+    # @param [String] url the url that caused the Parliament::ServerError
+    # @param [Net::HTTPServerError] response the Net:HTTPServerError that caused the Parliament::ServerError
+    #
+    # @example Creating a Parliament::ServerError
+    #   url = 'http://localhost:3030/foo/bar'
+    #
+    #   response = Net::HTTP.get_response(URI(url))
+    #
+    #   raise Parliament::ServerError.new(url, response) if response.is_a?(Net::HTTPServerError)
+    def initialize(url, response)
+      super
+    end
+  end
+end