contentful 0.1.0

data/lib/contentful/resource.rb

@@ -0,0 +1,146 @@
+require_relative 'resource/system_properties'
+require 'date'
+
+module Contentful
+  # Include this module to declare a class to be a contentful resource.
+  # This is done by the default in the existing resource classes
+  #
+  # You can define your own classes that behave like contentful resources:
+  # See examples/custom_classes.rb to see how.
+  #
+  # Take a look at examples/resource_mapping.rb on how to register them to be returned
+  # by the client by default
+  module Resource
+    COERCIONS = {
+      string:  ->(v){ v.to_s },
+      integer: ->(v){ v.to_i },
+      float:   ->(v){ v.to_f },
+      boolean: ->(v){ !!v },
+      date:    ->(v){ DateTime.parse(v) },
+    }
+
+    attr_reader :properties, :request, :client
+
+    def initialize(object, request = nil, client = nil)
+      self.class.update_coercions!
+
+      @properties = extract_from_object object, :property, self.class.property_coercions.keys
+      @request = request
+      @client = client
+    end
+
+    def inspect(info = nil)
+      properties_info = properties.empty? ? "" : " @properties=#{properties.inspect}"
+      "#<#{self.class}:#{properties_info}#{info}>"
+    end
+
+    # Returns true for resources that behave like an array
+    def array?
+      false
+    end
+
+    # Resources that don't include SystemProperties return nil for #sys
+    def sys
+      nil
+    end
+
+    # Resources that don't include Fields or AssetFields return nil for #fields
+    def fields
+      nil
+    end
+
+    # Issues the request that was made to fetch this response again.
+    # Only works for top-level resources
+    def reload
+      if request
+        request.get
+      else
+        false
+      end
+    end
+
+
+    private
+
+    def extract_from_object(object, namespace, keys = nil)
+      if object
+        keys ||= object.keys
+        keys.each.with_object({}){ |name, res|
+          res[name.to_sym] = coerce_value_or_array(
+            object.is_a?(::Array) ? object : object[name.to_s],
+            self.class.public_send(:"#{namespace}_coercions")[name.to_sym],
+          )
+        }
+      else
+        {}
+      end
+    end
+
+    def coerce_value_or_array(value, what = nil)
+      if value.is_a? ::Array
+        value.map{ |v| coerce_or_create_class(v, what) }
+      else
+        coerce_or_create_class(value, what)
+      end
+    end
+
+    def coerce_or_create_class(value, what)
+      case what
+      when Symbol
+        COERCIONS[what] ? COERCIONS[what][value] : value
+      when Class
+        what.new(value, client)
+      else
+        value
+      end
+    end
+
+    # Register the resources properties on class level by using the #property method
+    module ClassMethods
+      def property_coercions
+        @property_coercions ||= {}
+      end
+
+      # Defines which properties of a resource your class expects
+      # Define them in :camelCase, they will be available as #snake_cased methods
+      #
+      # You can pass in a second "type" argument:
+      # - If it is a class, it will be initialized for the property
+      # - Symbols are looked up in the COERCION constant for a lambda that
+      #   defines a type conversion to apply
+      #
+      # Note: This second argument is not meant for contentful sub-resources,
+      # but for structured objects (like locales in a space)
+      # Sub-resources are handled by the resource builder
+      def property(name, property_class = nil)
+        property_coercions[name.to_sym] = property_class
+        define_method Contentful::Support.snakify(name) do
+          properties[name.to_sym]
+        end
+      end
+
+      # Ensure inherited classes pick up coercions
+      def update_coercions!
+        return if @coercions_updated
+
+        if superclass.respond_to? :property_coercions
+          @property_coercions = superclass.property_coercions.dup.merge(@property_coercions || {})
+        end
+
+        if superclass.respond_to? :sys_coercions
+          @sys_coercions = superclass.sys_coercions.dup.merge(@sys_coercions || {})
+        end
+
+        if superclass.respond_to? :fields_coercions
+          @fields_coercions = superclass.fields_coercions.dup.merge(@fields_coercions || {})
+        end
+
+        @coercions_updated = true
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+  end
+end

data/lib/contentful/resource/asset_fields.rb

@@ -0,0 +1,50 @@
+require_relative '../file'
+
+module Contentful
+  module Resource
+    # Special fields for Asset. Don't include together wit Contentful::Resource::Fields
+    #
+    # It depends on system properties being available
+    module AssetFields
+      FIELDS_COERCIONS = {
+        title: :string,
+        description: :string,
+        file: File,
+      }
+
+      def fields
+        @fields[locale]
+      end
+
+      def initialize(object, *)
+        super
+        @fields = {}
+        @fields[locale] = extract_from_object object["fields"], :fields
+      end
+
+      def inspect(info = nil)
+        if fields.empty?
+          super(info)
+        else
+          super("#{info} @fields=#{fields.inspect}")
+        end
+      end
+
+      module ClassMethods
+        def fields_coercions
+          FIELDS_COERCIONS
+        end
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+
+        base.fields_coercions.keys.each{ |name|
+          base.send :define_method, Contentful::Support.snakify(name) do
+            fields[name.to_sym]
+          end
+        }
+      end
+    end
+  end
+end

data/lib/contentful/resource/fields.rb

@@ -0,0 +1,39 @@
+module Contentful
+  module Resource
+    # Include this module into your Resource class to enable it
+    # to deal with entry fields (but not asset fields)
+    #
+    # It depends on system properties being available
+    module Fields
+      # Returns all fields of the asset
+      def fields
+        @fields[locale]
+      end
+
+      def initialize(object, *)
+        super
+        @fields = {}
+        @fields[locale] = extract_from_object object["fields"], :fields
+      end
+
+      def inspect(info = nil)
+        if fields.empty?
+          super(info)
+        else
+          super("#{info} @fields=#{fields.inspect}")
+        end
+      end
+
+      module ClassMethods
+        # No coercions, since no content type available
+        def fields_coercions
+          {}
+        end
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+    end
+  end
+end

data/lib/contentful/resource/system_properties.rb

@@ -0,0 +1,48 @@
+module Contentful
+  module Resource
+    # Adds the feature to have system properties to a Resource.
+    module SystemProperties
+      SYS_COERCIONS = {
+        type: :string,
+        id: :string,
+        space: nil,
+        contentType: nil,
+        linkType: :string,
+        revision: :integer,
+        createdAt: :date,
+        updatedAt: :date,
+        locale: :string,
+      }
+      attr_reader :sys
+
+      def initialize(object, *)
+        super
+        @sys = extract_from_object object["sys"], :sys
+      end
+
+      def inspect(info = nil)
+        if sys.empty?
+          super(info)
+        else
+          super("#{info} @sys=#{sys.inspect}")
+        end
+      end
+
+      module ClassMethods
+        def sys_coercions
+          SYS_COERCIONS
+        end
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+
+        base.sys_coercions.keys.each{ |name|
+          base.send :define_method, Contentful::Support.snakify(name) do
+            sys[name.to_sym]
+          end
+        }
+      end
+    end
+  end
+end

data/lib/contentful/resource_builder.rb

@@ -0,0 +1,197 @@
+require_relative 'error'
+require_relative 'resource'
+require_relative 'space'
+require_relative 'content_type'
+require_relative 'entry'
+require_relative 'dynamic_entry'
+require_relative 'asset'
+require_relative 'array'
+require_relative 'link'
+
+module Contentful
+  # Transforms a Contentful::Response into a Contentful::Resource or a Contentful::Error
+  # See example/resource_mapping.rb for avanced usage
+  class ResourceBuilder
+    DEFAULT_RESOURCE_MAPPING = {
+      'Space' => Space,
+      'ContentType' => ContentType,
+      'Entry' => :try_dynamic_entry,
+      'Asset' => Asset,
+      'Array' => Array,
+      'Link' => Link,
+    }
+
+    attr_reader :client, :response, :resource_mapping
+
+
+    def initialize(client, response, resource_mapping = {})
+      @response = response
+      @client = client
+      @included_resources = {}
+      @resource_mapping = default_resource_mapping.merge(resource_mapping)
+    end
+
+    # Starts the parsing process.
+    # Either returns an Error, or the parsed Resource
+    def run
+      case response.status
+      when :contentful_error
+        Error[response.raw.response.status].new(response)
+      when :unparsable_json
+        UnparsableJson.new(response)
+      when :not_contentful
+        Error.new(response)
+      else
+        begin
+          create_all_resources!
+        rescue UnparsableResource => error
+          error
+        end
+      end
+    end
+
+    # PARSING MECHANISM
+    # - raise error if response not valid
+    # - look for included objects and parse them to resources
+    # - parse main object to resource
+    # - replace links in included resources with included resources
+    # - replace links in main resource with included resources
+    # - return main resource
+    def create_all_resources!
+      create_included_resources! response.object["includes"]
+      res = create_resource(response.object)
+
+      unless @included_resources.empty?
+        replace_links_in_included_resources_with_included_resources
+        replace_links_with_included_resources(res)
+      end
+
+      res
+    end
+
+    # Creates a single resource from the
+    def create_resource(object)
+      res = detect_resource_class(object).new(object, response.request, client)
+      replace_children res, object
+      replace_children_array(res, :items) if res.array?
+
+      res
+    end
+
+    # When using Dynamic Entry Mode: Automatically converts Entry to DynamicEntry
+    def try_dynamic_entry(object)
+      get_dynamic_entry(object) || Entry
+    end
+
+    # Finds the proper DynamicEntry class for an entry
+    def get_dynamic_entry(object)
+      if id = object["sys"] &&
+          object["sys"]["contentType"] &&
+          object["sys"]["contentType"]["sys"] &&
+          object["sys"]["contentType"]["sys"]["id"]
+        client.dynamic_entry_cache[id.to_sym]
+      end
+    end
+
+    # Uses the resource mapping to find the proper Resource class to initialize
+    # for this Response object type
+    #
+    # The mapping value can be a
+    # - Class
+    # - Proc: Will be called, expected to return the proper Class
+    # - Symbol: Will be called as method of the ResourceBuilder itself
+    def detect_resource_class(object)
+      type = object["sys"] && object["sys"]["type"]
+      case res_class = resource_mapping[type]
+      when Symbol
+        public_send(res_class, object)
+      when Proc
+        res_class[object]
+      when nil
+        raise UnsparsableResource.new(response)
+      else
+        res_class
+      end
+    end
+
+    # The default mapping for #detect_resource_class
+    def default_resource_mapping
+      DEFAULT_RESOURCE_MAPPING
+    end
+
+
+    private
+
+    def detect_child_objects(object)
+      if object.is_a?(Hash)
+        object.select{ |k,v| v.is_a?(Hash) && v.has_key?("sys") }
+      else
+        {}
+      end
+    end
+
+    def replace_children(res, object)
+      object.each{ |name, potential_objects|
+        detect_child_objects(potential_objects).each{ |child_name, child_object|
+          res.public_send(name)[child_name.to_sym] = create_resource(child_object)
+        }
+      }
+    end
+
+    def replace_children_array(res, array_field)
+      items = res.public_send(array_field)
+      items.map!{ |resource_object| create_resource(resource_object) }
+    end
+
+    def create_included_resources!(included_objects)
+      if included_objects
+        included_objects.each{ |type, objects|
+          @included_resources[type] = Hash[
+            objects.map{ |object|
+              res = create_resource(object)
+              [res.id, res]
+            }
+          ]
+        }
+      end
+    end
+
+    def replace_links_with_included_resources(res)
+      [:properties, :sys, :fields].each{ |_what|
+        if what = res.public_send(_what)
+          what.each{ |name, child_res|
+            replace_link_or_check_recursively child_res, what, name, res
+          }
+        end
+      }
+      if res.array?
+        res.each.with_index{ |child_res, index|
+          replace_link_or_check_recursively child_res, res.items, index, child_res
+        }
+      end
+    end
+
+    def replace_link_or_check_recursively(res, what, name, resource_to_replace)
+      if res.is_a? Link
+        maybe_replace_link(res, what, name)
+      elsif res.is_a?(Resource) && res.sys
+        replace_links_with_included_resources(resource_to_replace)
+      end
+    end
+
+    def replace_links_in_included_resources_with_included_resources
+      @included_resources.each{ |_, for_type|
+        for_type.each{ |_, res|
+          replace_links_with_included_resources(res)
+        }
+      }
+    end
+
+    def maybe_replace_link(resource, parent, index)
+      if  @included_resources[resource.link_type] &&
+          @included_resources[resource.link_type].has_key?(resource.id)
+        parent[index] = @included_resources[resource.link_type][resource.id]
+      end
+    end
+  end
+end