contentful 0.8.0 → 0.9.0

data/lib/contentful/dynamic_entry.rb

@@ -3,7 +3,9 @@ require_relative 'resource/fields'
 require_relative 'location'
 
 module Contentful
+  # Wrapper for Entries with Cached Content Types
   class DynamicEntry < Entry
+    # Coercions from Contentful Types to Ruby native types
     KNOWN_TYPES = {
       'String'   => :string,
       'Text'     => :string,
@@ -15,6 +17,7 @@ module Contentful
       'Location' => Location
     }
 
+    # @private
     def self.create(content_type)
       unless content_type.is_a? ContentType
         content_type = ContentType.new(content_type)

data/lib/contentful/entry.rb

@@ -3,10 +3,49 @@ require_relative 'resource/fields'
 
 module Contentful
   # Resource class for Entry.
-  # https://www.contentful.com/developers/documentation/content-delivery-api/#entries
+  # @see _ https://www.contentful.com/developers/documentation/content-delivery-api/#entries
   class Entry
     include Contentful::Resource
     include Contentful::Resource::SystemProperties
     include Contentful::Resource::Fields
+
+    # @private
+    def marshal_dump
+      raw_with_links
+    end
+
+    # @private
+    def marshal_load(raw_object)
+      @properties = extract_from_object(raw_object, :property, self.class.property_coercions.keys)
+      @sys = raw_object.key?('sys') ? extract_from_object(raw_object['sys'], :sys) : {}
+      extract_fields_from_object!(raw_object)
+    end
+
+    # @private
+    def raw_with_links
+      links = properties.keys.select { |property| known_link?(property) }
+      processed_raw = Marshal.load(Marshal.dump(raw)) # Deep Copy
+      raw['fields'].each do |k, v|
+        processed_raw['fields'][k] = links.include?(k.to_sym) ? send(snakify(k)) : v
+      end
+
+      processed_raw
+    end
+
+    private
+
+    def known_link?(name)
+      field_name = name.to_sym
+      return true if known_contentful_object?(fields[field_name])
+      fields[field_name].is_a?(Enumerable) && known_contentful_object?(fields[field_name].first)
+    end
+
+    def known_contentful_object?(object)
+      (object.is_a?(Contentful::Entry) || object.is_a?(Contentful::Asset))
+    end
+
+    def snakify(name)
+      Contentful::Support.snakify(name).to_sym
+    end
   end
 end

data/lib/contentful/request.rb

@@ -8,11 +8,8 @@ module Contentful
     def initialize(client, endpoint, query = {}, id = nil)
       @client = client
       @endpoint = endpoint
-      @absolute = true if @endpoint.start_with?('http')
 
-      @query = if query && !query.empty?
-                 normalize_query(query)
-      end
+      @query = (normalize_query(query) if query && !query.empty?)
 
       if id
         @type = :single
@@ -25,7 +22,7 @@ module Contentful
 
     # Returns the final URL, relative to a contentful space
     def url
-      "#{@endpoint}#{ @type == :single ? "/#{id}" : '' }"
+      "#{@endpoint}#{@type == :single ? "/#{id}" : ''}"
     end
 
     # Delegates the actual HTTP work to the client
@@ -35,7 +32,7 @@ module Contentful
 
     # Returns true if endpoint is an absolute url
     def absolute?
-      !! @absolute
+      @endpoint.start_with?('http')
     end
 
     # Returns a new Request object with the same data

data/lib/contentful/resource.rb

@@ -9,9 +9,14 @@ module Contentful
   # 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
+  # Take a look at examples/resource_mapping.rb on how to register them to be returned
+  # by the client by default
+  #
+  # @see _ examples/custom_classes.rb Custom Class as Resource
+  # @see _ examples/resource_mapping.rb Mapping a Custom Class
   module Resource
+    # @private
+    # rubocop:disable Style/DoubleNegation
     COERCIONS = {
       string:  ->(v) { v.to_s },
       integer: ->(v) { v.to_i },
@@ -19,20 +24,33 @@ module Contentful
       boolean: ->(v) { !!v },
       date:    ->(v) { DateTime.parse(v) }
     }
+    # rubocop:enable Style/DoubleNegation
 
-    attr_reader :properties, :request, :client, :default_locale
+    attr_reader :properties, :request, :client, :default_locale, :raw
 
-    def initialize(object = nil, request = nil, client = nil, default_locale = Contentful::Client::DEFAULT_CONFIGURATION[:default_locale])
+    # @private
+    def initialize(object = nil,
+                   request = nil,
+                   client = nil,
+                   default_locale = Contentful::Client::DEFAULT_CONFIGURATION[:default_locale])
       self.class.update_coercions!
       @default_locale = default_locale
 
-      @properties = extract_from_object(object, :property,
-                                        self.class.property_coercions.keys)
+      @properties = {}
+      self.class.property_coercions.keys.each do |property_name|
+        @properties[property_name] = nil
+      end
+
+      @properties = @properties.merge(
+        extract_from_object(object, :property,
+                            self.class.property_coercions.keys)
+      )
       @request = request
       @client = client
-      @api_object = object
+      @raw = object
     end
 
+    # @private
     def inspect(info = nil)
       properties_info = properties.empty? ? '' : " @properties=#{properties.inspect}"
       "#<#{self.class}:#{properties_info}#{info}>"
@@ -43,6 +61,9 @@ module Contentful
       false
     end
 
+    # Returns true if resource is localized
+    #
+    # @return [Boolean]
     def localized?(value)
       return false unless value.is_a? ::Hash
       value.keys.any? { |possible_locale| Contentful::Constants::KNOWN_LOCALES.include?(possible_locale) }
@@ -68,6 +89,57 @@ module Contentful
       end
     end
 
+    # Register the resources properties on class level by using the #property method
+    # @private
+    module ClassMethods
+      # By default, fields come flattened in the current locale. This is different for sync
+      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
+
+    # @private
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
     private
 
     def initialize_fields_for_localized_resource(object)
@@ -107,11 +179,11 @@ module Contentful
       elsif value.is_a? ::Array
         value.map { |v| coerce_or_create_class(v, what) }
       elsif should_coerce_hash?(value)
-        ::Hash[value.map { |k, v|
+        ::Hash[value.map do |k, v|
           to_coerce = v.is_a?(Hash) ? v : v.to_s
           coercion = v.is_a?(Numeric) ? v : coerce_or_create_class(to_coerce, what)
           [k.to_sym, coercion]
-        }]
+        end]
       else
         coerce_or_create_class(value, what)
       end
@@ -119,23 +191,23 @@ module Contentful
 
     def should_coerce_hash?(value)
       value.is_a?(::Hash) &&
-        !self.is_a?(Asset) &&
-        !self.is_a?(Field) &&
-        !is_location?(value) &&
-        !is_link?(value) &&
-        !is_image?(value)
+        !is_a?(Asset) &&
+        !is_a?(Field) &&
+        !location?(value) &&
+        !link?(value) &&
+        !image?(value)
     end
 
-    def is_location?(value)
-      value.has_key?("lat") || value.has_key?("lon")
+    def location?(value)
+      value.key?('lat') || value.key?('lon')
     end
 
-    def is_link?(value)
-      value.has_key?("sys") && value["sys"]["type"] == "Link"
+    def link?(value)
+      value.key?('sys') && value['sys']['type'] == 'Link'
     end
 
-    def is_image?(value)
-      value.has_key?("image")
+    def image?(value)
+      value.key?('image')
     end
 
     def coerce_or_create_class(value, what)
@@ -148,54 +220,5 @@ module Contentful
         value
       end
     end
-
-    # Register the resources properties on class level by using the #property method
-    module ClassMethods
-      # By default, fields come flattened in the current locale. This is different for sync
-      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/array_like.rb

@@ -6,26 +6,34 @@ module Contentful
       include Enumerable
 
       # Returns true for array-like resources
+      #
+      # @return [true]
       def array?
         true
       end
 
       # Delegates to items#each
+      #
+      # @yield [Contentful::Entry, Contentful::Asset]
       def each_item(&block)
         items.each(&block)
       end
-      alias_method :each, :each_item
+      alias each each_item
 
       # Delegates to items#empty?
+      #
+      # @return [Boolean]
       def empty?
         items.empty?
       end
 
       # Delegetes to items#size
+      #
+      # @return [Number]
       def size
         items.size
       end
-      alias_method :length, :size
+      alias length size
     end
   end
 end

data/lib/contentful/resource/asset_fields.rb

@@ -6,6 +6,7 @@ module Contentful
     #
     # It depends on system properties being available
     module AssetFields
+      # Special field coercions for Asset.
       FIELDS_COERCIONS = {
         title: :string,
         description: :string,
@@ -13,16 +14,20 @@ module Contentful
       }
 
       # Returns all fields of the asset
+      #
+      # @return [Hash] localized fields
       def fields(wanted_locale = default_locale)
         @fields[locale || wanted_locale]
       end
 
+      # @private
       def initialize(object, *)
         super
 
         initialize_fields_for_localized_resource(object)
       end
 
+      # @private
       def inspect(info = nil)
         if fields.empty?
           super(info)
@@ -31,12 +36,14 @@ module Contentful
         end
       end
 
+      # @private
       module ClassMethods
         def fields_coercions
           FIELDS_COERCIONS
         end
       end
 
+      # @private
       def self.included(base)
         base.extend(ClassMethods)
 

data/lib/contentful/resource/custom_resource.rb

@@ -0,0 +1,29 @@
+module Contentful
+  module Resource
+    # Module for simplifying Custom Resource Creation
+    # Allows auto-mapping of fields to properties and properties to fields
+    module CustomResource
+      # @private
+      def initialize(*)
+        super
+
+        update_mappings!
+      end
+
+      # @private
+      def update_mappings!
+        properties.keys.each do |name|
+          define_singleton_method Contentful::Support.snakify(name).to_sym do |wanted_locale = default_locale|
+            properties[name] ||= fields(wanted_locale)[name]
+          end
+        end
+      end
+
+      # @private
+      def marshal_load(raw_object)
+        super raw_object
+        update_mappings!
+      end
+    end
+  end
+end

data/lib/contentful/resource/fields.rb

@@ -8,12 +8,16 @@ module Contentful
     # It depends on system properties being available
     module Fields
       # Returns all fields of the asset
+      #
+      # @return [Hash] fields for Resource on selected locale
       def fields(wanted_locale = default_locale)
         wanted_locale = wanted_locale.to_s
-        @fields.has_key?(wanted_locale) ? @fields[wanted_locale] : @fields[locale]
+        @fields.key?(wanted_locale) ? @fields[wanted_locale] : @fields[locale]
       end
 
       # Returns all fields of the asset with locales nested by field
+      #
+      # @return [Hash] fields for Resource grouped by field name
       def fields_with_locales
         remapped_fields = {}
         locales.each do |locale|
@@ -26,11 +30,26 @@ module Contentful
         remapped_fields
       end
 
+      # @private
+      module ClassMethods
+        # No coercions, since no content type available
+        def fields_coercions
+          {}
+        end
+      end
+
+      # @private
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # @private
       def initialize(object = nil, *)
         super
         extract_fields_from_object! object if object
       end
 
+      # @private
       def inspect(info = nil)
         if fields.empty?
           super(info)
@@ -48,17 +67,6 @@ module Contentful
       def extract_fields_from_object!(object)
         initialize_fields_for_localized_resource(object)
       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