subjoin 0.2.1

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:no_inheritance) do |t|
+  t.exclude_pattern = "**/inheritable*_spec.rb"
+end
+
+RSpec::Core::RakeTask.new(:inheritance) do |t|
+  t.pattern = "**/inheritable*_spec.rb"
+end
+task :default => :spec
+task :spec => [:no_inheritance, :inheritance]

data/lib/subjoin.rb

@@ -0,0 +1,85 @@
+require "faraday"
+require "json"
+require "subjoin/attributable"
+require "subjoin/errors"
+require "subjoin/meta"
+require "subjoin/metable"
+require "subjoin/jsonapi"
+require "subjoin/link"
+require "subjoin/linkable"
+require "subjoin/resource"
+require "subjoin/identifier"
+require "subjoin/inclusions"
+require "subjoin/inheritable"
+require "subjoin/relationship"
+require "subjoin/document"
+require "subjoin/version"
+
+module Subjoin
+
+  # Connection used for all HTTP resquests
+  @@conn = Faraday.new
+
+  private
+  # Fetch and parse data from a URI
+  # @param [URI] uri The endpoint to get
+  # @return [Hash] Parsed JSON data
+  # @raise [ResponseError] if the endpoint returns an error response
+  def self.get(uri, params={})
+    params = {} if params.nil?
+    uri_params = uri.query.nil? ? {} : param_flatten(CGI::parse(uri.query))
+    final_params = uri_params.merge(stringify_params(params))
+    response = @@conn.get(uri,
+                          final_params,
+                          {"Accept" => "application/vnd.api+json"}
+                         )
+    data = JSON.parse response.body
+
+    if data.has_key?("errors")
+      raise ResponseError.new
+    end
+
+    return data
+  end
+
+  # CGI::parse creates a hash whose values are arrays which is
+  # incompatible with Faraday.get, so flatten the values
+  def self.param_flatten(p)
+    Hash[p.map{|k,v| [k, v.join(',')]}]
+  end
+
+  # If param value is an Array, join elements into a string. `field` parameters
+  # passed as a Hash will be converted to key value pairs like
+  # "field[type]"="fields1,field2"
+  # @param p [Hash] parameters
+  # @return [Hash] with arrays joined into strings
+  def self.stringify_params(p)
+    fieldify(Hash[p.map{|k, v| [k, stringify_value(v, k) ]}])
+  end
+
+  # Turn parameter values into Strings if they are Hashes or Arrays
+  # @param v The value to check
+  # @param k The key corresponding to the value passed in
+  # @return [String,Hash] If a Hash is returned it will be taken care of by
+  #   {fieldify}
+  def self.stringify_value(v, k=nil)
+    return v if v.is_a?(String)
+    return v.join(",") if v.is_a?(Array)
+    if v.is_a?(Hash)
+      return Hash[v.map{|key, val| ["#{k}[#{key}]", stringify_value(val)]}]
+    end
+    raise ArgumentError.new
+  end
+
+  # If a field paramter has been passed as a Hash it will still be a Hash and
+  # and we want to replace `field` with it's value
+  # @param h [Hash]
+  def self.fieldify(h)
+    if h.has_key? "fields"
+      f = h.delete("fields")
+      return h.merge(f)
+    end
+
+    return h
+  end
+end

data/lib/subjoin/attributable.rb

@@ -0,0 +1,28 @@
+module Subjoin
+  # Generically handle arbitrary object attributes
+  # @see http://jsonapi.org/format/#document-resource-object-attributes
+  module Attributable
+
+    # The object's attributes
+    # @return [Hash]
+    attr_reader :attributes
+
+    # Load the object's attributes
+    # @param data [Hash] The object's parsed JSON `attribute` member
+    def load_attributes(data)
+      @attributes = data
+    end
+
+
+    # Access an attribute by property name
+    # @param name [String] the property name
+    # @return The property value, or nil if no such property exists
+    def [](name)
+      name = name.to_s
+      if @attributes.has_key?(name)
+        return @attributes[name]
+      end
+      return nil
+    end
+  end
+end

data/lib/subjoin/document.rb

@@ -0,0 +1,136 @@
+module Subjoin
+  # A JSON-API top level document
+  class Document
+    include Metable
+    include Linkable
+
+    # The document's primary data
+    attr_reader :data
+
+    # Resources included in a compound document"
+    attr_reader :included
+
+    # JSON-API version information
+    attr_reader :jsonapi
+
+
+    # Create a document. Parameters can take several forms:
+    # 1. A URI object: Document will be created from the URI
+    # 2. A Hash: The Hash is assumed to be a parsed JSON response and the
+    #    Document will be created from that
+    # 3. One string: Assumed to be a JSON-API object type. An attempt will be
+    #    made to map this type to a class that inherits from
+    #    {InheritableResource} and to load the create the Document from a URL
+    #    provided by that class. There is also the assumption that this URL
+    #    returns all objects of that type.
+    # 4. Two strings: Assumed to be a JSON-API object type and id. The same
+    #    mapping is attempted as before, and the second parameter is added to
+    #    the URL
+    # @param [Array] args
+    def initialize(*args)
+      if args.count < 1
+        raise ArgumentError.new
+      end
+
+      contents = load_by_type(args[0], args[1..-1])
+
+      @meta = load_meta(contents['meta'])
+      @links = load_links(contents['links'])
+      @included = load_included(contents)
+      @data = load_data(contents)
+      @jsonapi = load_jsonapi(contents)
+    end
+
+    # @return [Boolean] true if there is primary data
+    def has_data?
+      return ! @data.nil?
+    end
+
+    # @return [Boolean] true if there are included resources
+    def has_included?
+      return ! @included.nil?
+    end
+
+    # @return [Boolean] true if there is version information
+    def has_jsonapi?
+      return ! @jsonapi.nil?
+    end
+
+    private
+
+    def load_by_type(firstArg, restArgs)
+      # We were passed a URI. Load it
+      return Subjoin::get(firstArg, restArgs[0]) if firstArg.is_a?(URI)
+
+      # We were passed a Hash. Just use it
+      return firstArg if firstArg.is_a?(Hash)
+
+      # We were passed a type, and maybe an id.
+      return load_by_id(firstArg, restArgs) if firstArg.is_a?(String)
+
+      # None of the above
+      raise ArgumentError.new
+    end
+
+    def load_by_id(firstArg, restArgs)
+      type = firstArg
+      id = restArgs.first
+
+      return Subjoin::get(mapped_type(type)::type_url) if id.nil?
+
+      Subjoin::get(URI([mapped_type(type)::type_url, id].join('/')))
+    end
+      
+    
+    # Take the data element and make an Array of instantiated Resource
+    # objects. Turn single objects into a single item Array to be consistent.
+    # @param c [Hash] Parsed JSON
+    # @return [Array, nil]
+    def load_data(c)
+      return nil unless c.has_key?("data")
+
+      #single resource, but instantiate it and stick it in an Array
+      return [mapped_type(c["data"]["type"]).new(c["data"], self)] if c["data"].is_a? Hash
+
+      # Instantiate Resources for each array element
+      return c["data"].map{|d| mapped_type(d["type"]).new(d, self)}
+    end
+
+    # Instantiate a {Subjoin::Inclusions object if the included property is
+    # present
+    # @param c [Hash] Parsed JSON
+    # @return [Subjoin::Inclusions, nil]
+    def load_included(c)
+      return nil unless c.has_key? "included"
+
+      Inclusions.new(c['included'].map{|o| mapped_type(o["type"]).new(o, self)})
+    end
+
+    # Load jsonapi property if present
+    # @param c [Hash] Parsed JSON
+    # @return [Subjoin::JsonApi, nil]
+    def load_jsonapi(c)
+      return nil unless c.has_key?("jsonapi")
+      @jsonapi = JsonApi.new(c["jsonapi"])
+    end
+
+    def mapped_type(t)
+      type_map.fetch(t, Resource)
+    end
+      
+    def type_map
+      @type_map ||= create_type_map
+    end
+    
+    def create_type_map
+      d_types = Subjoin.constants.
+                map{|c| Subjoin.const_get(c)}.
+                select{|c| c.is_a?(Class) and c < Subjoin::Inheritable}
+      Hash[d_types.map{|c| [c::type_id, c]}]
+    end
+  end
+end
+                   
+
+      
+      

data/lib/subjoin/errors.rb

@@ -0,0 +1,15 @@
+module Subjoin
+  class Error < StandardError; end
+
+  class NoOverriddenRootError < Error
+    def message
+      "You must derive a class from Subjoin::Resource and override Resource#Root to return the root URL of the API you are using. This derived class should, in turn be used as the base class for your other custom classes."
+    end
+  end
+
+  class ResponseError < Error; end
+
+  class UnexpectedTypeError < Error; end
+
+  class SubclassError < Error; end
+end

data/lib/subjoin/identifier.rb

@@ -0,0 +1,23 @@
+module Subjoin
+  # A resource identifier object
+  # @see http://jsonapi.org/format/#document-resource-identifier-objects
+  class Identifier
+    include Metable
+
+    attr_reader :type
+    attr_reader :id
+    
+    def initialize(type, id, meta=nil)
+      #load_key(data)
+      @type = type
+      @id = id
+      @meta = load_meta(meta)
+    end
+
+    # Test for equality. Two Ideintifers are considered equal if they
+    # have the same type and id
+    def ==(other)
+      return @type == other.type && @id == other.id
+    end
+  end
+end

data/lib/subjoin/inclusions.rb

@@ -0,0 +1,39 @@
+module Subjoin
+  # Container for related resources included in a compounf
+  # document. Alllows Hash-like access by {Identifier}, type/id pair,
+  # or Array-like access bu index
+  class Inclusions
+    def initialize(data)
+      @inc = data
+    end
+
+    # @return [Array<Subjoin::Resource>] all included resources
+    def all
+      @inc
+    end
+
+    # @return [Subjoin::Resource] first included resource
+    def first
+      @inc.first
+    end
+
+    # Access a particular resource by id
+    # @param id Either a {Subjoin::Identifier}, an Array of two strings
+    #   taken as a type and an id, or an integer
+    # @return [Subjoin::Resource]
+    def [](id)
+      if id.is_a?(Identifier)
+        return @inc.select{|i| i.identifier == id}.first
+      end
+
+      if id.is_a?(Array) && id.count == 2
+        idd = Identifier.new(id[0], id[1])
+        return @inc.select{|i| i.identifier == idd}.first
+      end
+
+      if id.is_a?(Fixnum)
+        return @inc[id]
+      end
+    end
+  end
+end

data/lib/subjoin/inheritable.rb

@@ -0,0 +1,80 @@
+# coding: utf-8
+module Subjoin
+  # Mixin providing methods necessary for using custom classes derived
+  # from {Resource}.
+  #
+  # Using this approach you create your own classes to represent
+  # JSON-API resource types of a specific JSON-API server
+  # implementation. These classes must be sub-classes of {Resource}
+  # and must include {Inheritable}. Next you must override a class
+  # variable, `ROOT_URI`, which should be the root of all URIs of the
+  # API.
+  #
+  # By default, Subjoin will use the lower-cased name of the class as
+  # the type in URIs. If the class name does not match the type, you
+  # can further override `TYPE_PATH` to indicate the name (or longer URI
+  # fragment) that should be used in URIs to request the resource
+  # type. Your custom classes must also be part of the Subjoin
+  # module. You should probably create one sub-class of
+  # Subjoin::Resource that overrides `ROOT_URI`, and then create other
+  # classes as sub-classes of this:
+  #
+  #    module Subjoin
+  #      # Use this class as the parent of further subclasses.
+  #      # They will inherit the ROOT_URI defined here
+  #      class ExampleResource < Subjoin::Resource
+  #        include Inheritable
+  #        ROOT_URI="http://example.com"
+  #      end
+  #
+  #      # Subjoin will make requests to http://example.com/articles
+  #      class Articles < ExampleResource
+  #      end
+  #
+  #      # Use TYPE_PATH if you don't want to name the class the same thing as
+  #      # the type
+  #      class ArticleComments < ExampleResource
+  #        TYPE_PATH="comments"
+  #      end
+  #    end
+  module Inheritable
+    # Root URI for all API requests
+    ROOT_URI = nil
+
+    # JSON-API type corresponding to this class, and presumably string
+    # to be used in requests for resources of this type. If not
+    # provided, the lower-cased name of the class will be used
+    TYPE_PATH = nil
+
+    # Callback invoked whenever module is included in another module
+    # or class.
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Class methods for objects that include this mixin
+    module ClassMethods
+      # @return [String] JSON-API type corresponding to this
+      # class. Lower-cased name of the class unless TYPE_PATH is
+      # specified
+      def type_id
+        return self.to_s.downcase.gsub(/^.*::/, '') if self::TYPE_PATH.nil?
+        return self::TYPE_PATH
+      end
+    
+      # @return [URI] URI for requesting an object of this type, based
+      # of ROOT_URI and {#type_id}
+      def type_url
+        if self.class == Resource
+          raise Subjoin::SubclassError.new "Class must be a subclass of Resource to use this method"
+        end
+
+        if self::ROOT_URI.nil?
+          raise Subjoin::SubclassError.new "#{self.class} or a parent of #{self.class} derived from Subjoin::Resource must override ROOT_URI to use this method"
+        end
+
+        return URI([self::ROOT_URI, self::type_id].join('/'))
+      end
+    end
+  end
+end

data/lib/subjoin/jsonapi.rb

@@ -0,0 +1,13 @@
+module Subjoin
+  # JSON-API version information
+  class JsonApi
+    include Metable
+    attr_reader :version
+    def initialize(data)
+      @version = data['version']
+      load_meta(data['version'])
+    end
+  end
+end
+      
+    

data/lib/subjoin/link.rb

@@ -0,0 +1,30 @@
+module Subjoin
+  # A link object
+  class Link
+    include Metable
+
+    # The URL for this link
+    # @return String
+    attr_reader :href
+
+    def initialize(data)
+      if data.is_a? String
+        @href = URI(data)
+      else
+        @href = URI(data['href'])
+        @meta = load_meta(data['meta'])
+      end
+    end
+
+    # Returns the {#href} attribute
+    def to_s
+      @href.to_s
+    end
+
+    # Get the resource identified by the URL
+    # @return [Document]
+    def get
+      Document.new(@href)
+    end
+  end
+end