representors 0.0.5

data/lib/representors/representor.rb

@@ -0,0 +1,161 @@
+require 'yaml'
+require 'enumerable/lazy' if RUBY_VERSION < '2.0'
+require 'representors/field'
+require 'representors/transition'
+require 'representors/serialization/serializer_factory'
+
+module Representors
+  ##
+  # Manages the respresentation of hypermedia messages for different media-types.
+  class Representor
+    DEFAULT_PROTOCOL = 'http'
+    PROTOCOL_TEMPLATE = "%s://%s"
+    UNKNOWN_PROTOCOL = 'ruby_id'
+    VALUE_KEY = :value
+    META_LINK_FIELDS = ['profile', 'help', 'type', 'self']
+
+    # @example
+    #  representor = Representors::Representor.new do |builder|
+    #    builder.add_attribute({ name: => 'Bob' })
+    #  end
+    #
+    # @param [Hash] hash the abstract representor hash defining a resource
+    def initialize(hash = {}, builder = nil)
+      builder ||= RepresentorBuilder.new(hash)
+      builder = yield builder if block_given?
+      @representor_hash = builder.to_representor_hash
+    end
+
+    # @param format to convert this representor to
+    # @return the representor serialized to a particular media-type like application/hal+json
+    def to_media_type(format, options={})
+      SerializerFactory.build(format, self).to_media_type(options)
+    end
+
+    def empty?
+      @representor_hash.empty?
+    end
+
+    def ==(other)
+      other.is_a?(Hash) ? to_hash == other : to_hash == other.to_hash
+    end
+
+    # Returns the document for the representor
+    #
+    # @return [String] the document for the representor
+    def doc
+      @doc ||= @representor_hash.doc || ''
+    end
+
+    # The URI for the object
+    #
+    # @note If the URI can't be made from the provided information it constructs one from the Ruby ID
+    # @return [String]
+    def identifier
+      @identifier ||= begin
+        uri = @representor_hash.href || self.object_id
+        protocol = @representor_hash.protocol || (uri == self.object_id ? UNKNOWN_PROTOCOL : DEFAULT_PROTOCOL)
+        PROTOCOL_TEMPLATE % [protocol, uri]
+      end
+    end
+
+    # @return [Hash] The hash representation of the object
+    def to_hash
+      @to_hash ||= @representor_hash.to_h
+    end
+
+    # @return [String] the yaml representation of the object
+    def to_yaml
+      @to_yaml ||= YAML.dump(to_hash)
+    end
+
+    # @return [String] so the user can 'puts' this object
+    def to_s
+      to_hash.inspect
+    end
+
+    # @return [Hash] the resource attributes inferred from representor[:semantics]
+    def properties
+      @properties ||= Hash[@representor_hash.attributes.map { |k, v| [ k, v[VALUE_KEY]] }]
+    end
+
+    # @return [Enumerable] who's elements are all <Representors:Representor> objects
+    def embedded
+      @embedded ||= begin
+        embedded_representors = @representor_hash.embedded.map do |name, values|
+          if values.is_a?(Array)
+            several_representors = values.map do |value|
+              Representor.new(value)
+            end
+            [name, several_representors]
+          else
+            [name, Representor.new(values)]
+          end
+        end
+        Hash[embedded_representors]
+      end
+    end
+
+    # @return [Array] who's elements are all <Representors:Transition> objects
+    def meta_links
+      @meta_links ||= begin
+        links_from_transitions = {}
+
+        transitions.each do |transition|
+          if META_LINK_FIELDS.include?(transition.rel)
+            links_from_transitions[transition.rel.to_sym] = transition.uri
+          end
+        end
+
+        @representor_hash.links.merge(links_from_transitions).map do |k, v|
+          Representors::Transition.new({rel: k, href: v})
+        end.uniq { |transition| [transition.rel, transition.uri] }
+      end
+    end
+    # @return [Array] who's elements are all <Representors:Transition> objects
+    def transitions
+      @transitions ||= begin
+        transition_hashes = (@representor_hash.transitions + embedded_transitions_hashes).uniq do |hash|
+          [hash[:rel], hash[:href]]
+        end
+        transition_hashes.map { |hash| Transition.new(hash) }
+      end
+    end
+
+   # @return [Array] who's elements are all <Representors:Transition> objects from the self links of
+   # embedded items, updating the rel to reflect the embedded items key
+    def embedded_transitions
+      embedded_transitions_hashes.map { |hash| Transition.new(hash) }
+    end
+
+    # @return [Array] who's elements are all <Representors:Option> objects
+    def datalists
+      @datalists ||= begin
+        attributes = transitions.map { |transition| transition.attributes }
+        parameters = transitions.map { |transition| transition.parameters }
+        fields = [attributes, parameters].flatten
+        options = fields.map { |field| field.options }
+        options.select { |o| o.datalist? }
+      end
+    end
+
+    private
+
+    def embedded_transitions_hashes
+      @representor_hash.embedded.flat_map do |k,*v|
+        v.flatten.map do |item|
+          trans_hash = item[:transitions].find { |t| t[:rel] == "self" }
+          if trans_hash
+            profile_href = item[:links]["profile"] if item[:links]
+            trans_hash = trans_hash.merge(profile: profile_href) if profile_href
+            trans_hash.merge(rel: k)
+          else
+            {}
+          end
+        end
+      end
+    end
+
+
+  end
+end

data/lib/representors/representor_builder.rb

@@ -0,0 +1,64 @@
+require 'representor_support/utilities'
+require 'representors/representor_hash'
+
+module Representors
+
+  ##
+  # Builder has methods to abstract the construction of Representor objects
+  # In the present implementation it will create a hash of a specific format to
+  # Initialize the Representor with, this will create classess with it.
+  class RepresentorBuilder
+    include RepresentorSupport::Utilities
+
+    HREF_KEY = :href
+    DATA_KEY = :data
+
+    def initialize(representor_hash = {})
+      @representor_hash = RepresentorHash.new(representor_hash)
+    end
+
+    # Returns a hash usable by the representor class
+    def to_representor_hash
+      @representor_hash
+    end
+
+    # Adds an attribute to the Representor. We are creating a hash where the keys are the
+    # names of the attributes
+    def add_attribute(name, value, options={})
+      new_representor_hash = RepresentorHash.new(deep_dup(@representor_hash.to_h))
+      new_representor_hash.attributes[name] = options.merge({value: value})
+      RepresentorBuilder.new(new_representor_hash)
+    end
+
+    # Adds a transition to the Representor, each transition is a hash of values
+    # The transition collection is an Array
+    def add_transition(rel, href, options={})
+      new_representor_hash = RepresentorHash.new(deep_dup(@representor_hash.to_h))
+      options = symbolize_keys(options)
+      options.delete(:method) if options[:method] == Transition::DEFAULT_METHOD
+      link_values = options.merge({href: href, rel: rel})
+
+      if options[DATA_KEY]
+        link_values[Transition::DESCRIPTORS_KEY] = link_values.delete(DATA_KEY)
+      end
+
+      new_representor_hash.transitions.push(link_values)
+      RepresentorBuilder.new(new_representor_hash)
+    end
+
+    # Adds directly an array to our array of transitions
+    def add_transition_array(rel, array_of_hashes)
+      array_of_hashes.reduce(RepresentorBuilder.new(@representor_hash)) do |memo, transition|
+        transition = symbolize_keys(transition)
+        href = transition.delete(:href)
+        memo = memo.add_transition(rel, href, transition)
+      end
+    end
+
+    def add_embedded(name, embedded_resource)
+      new_representor_hash = RepresentorHash.new(deep_dup(@representor_hash.to_h))
+      new_representor_hash.embedded[name] = embedded_resource
+      RepresentorBuilder.new(new_representor_hash)
+    end
+  end
+end

data/lib/representors/representor_hash.rb

@@ -0,0 +1,59 @@
+require 'representor_support/utilities'
+
+module Representors
+  # This is the structure shared between the builder and the representor.
+  # This class allows to pass all the data to the representor without polluting it with methods
+  # It is supposed to be a fast class (Struct is implemented in C)
+  # The structure looks like this:
+  # id: [string]
+  # doc: [string]
+  # href: [string]
+  # protocol: [string]
+  # attributes: [hash]  { key => value }
+  # links: [array of hashes]
+  # transitions: [array of hashes]
+  # embedded: [hash] where each value can be recursively defined by this same structure
+  RepresentorHash  = Struct.new(:id, :doc, :href, :protocol, :attributes, :embedded, :links, :transitions) do
+    include RepresentorSupport::Utilities
+
+    DEFAULT_HASH_VALUES = {
+      id: nil,
+      doc: nil,
+      href: nil,
+      #TODO protocol doesnt belong in representors, remove it
+      protocol: nil,
+      #TODO fix this, make it the same interface as transitions
+      links: {},
+      attributes: {},
+      transitions: [],
+      embedded: {}
+    }.each_value(&:freeze).freeze
+
+
+    # be able to create from a hash
+    def initialize(hash = {})
+      DEFAULT_HASH_VALUES.each { |k, v| self[k] = dup_or_self(hash[k] || v) }
+    end
+
+    # Be able to generate a new structure with myself and a hash
+    def merge(hash)
+      new_representor_hash = RepresentorHash.new(to_h)
+      hash.each_pair { |k, v| new_representor_hash[k] = v }
+      new_representor_hash
+    end
+
+    # to_h does not exists in Ruby < 2.0
+    def to_h
+      members.each_with_object({}) { |member, hash| hash[member] = self[member] }
+    end
+
+    def empty?
+      members.all? { |k| self[k].nil? || self[k].empty? }
+    end
+
+    def ==(other)
+      members.all? { |k| self[k] == other[k] }
+    end
+
+  end
+end

data/lib/representors/serialization.rb

@@ -0,0 +1,4 @@
+require 'representors/serialization/hal_deserializer'
+require 'representors/serialization/hale_deserializer'
+require 'representors/serialization/hal_serializer'
+require 'representors/serialization/hale_serializer'

data/lib/representors/serialization/deserializer_base.rb

@@ -0,0 +1,29 @@
+require 'representors/serialization/serialization_base'
+require 'representors/serialization/deserializer_factory'
+
+module Representors
+  class DeserializerBase < SerializationBase
+
+    def initialize(target)
+      @target = target.empty? ? {} : target
+    end
+
+    def self.inherited(subclass)
+      DeserializerFactory.register_deserializers(subclass)
+    end
+
+    # Returns back a class with all the information of the document and with convenience methods
+    # to access it.
+    # TODO: Yield builder to factor out builder dependency.
+    def to_representor
+      Representor.new(to_representor_hash)
+    end
+
+    # Returns a hash representation of the data. This is useful to merge with new data which may
+    # be built by different builders. In this class we use it to support embedded resources.
+    def to_representor_hash(options = {})
+      raise "Abstract method #to_representor_hash not implemented in #{self.name} deserializer class."
+    end
+
+  end
+end

data/lib/representors/serialization/deserializer_factory.rb

@@ -0,0 +1,13 @@
+require 'representors/serialization/serialization_factory_base'
+
+module Representors
+  class DeserializerFactory < SerializationFactoryBase
+    def self.register_deserializers(*serializers)
+      register_serialization_classes(*serializers)
+    end
+
+    def self.registered_deserializers
+      registered_serialization_classes
+    end
+  end
+end

data/lib/representors/serialization/hal_deserializer.rb

@@ -0,0 +1,44 @@
+
+require 'representors/serialization/hale_deserializer'
+
+module Representors 
+  ##
+  # Deserializes the HAL format as specified in http://stateless.co/hal_specification.html
+  # For examples of how this format looks like check the files under spec/fixtures/hal
+  # TODO: support Curies http://www.w3.org/TR/2010/NOTE-curie-20101216/
+  class HalDeserializer < HaleDeserializer
+    media_symbol :hal
+    media_type 'application/hal+json', 'application/json'
+    
+    HAL_LINK_KEYS = %w(href templated type deprecation name profile title hreflang)
+    @reserved_keys = [LINKS_KEY, EMBEDDED_KEY]
+    
+    private
+    
+    def builder_add_from_deserialized(builder, media)
+      builder = deserialize_properties(builder, media)
+      builder = deserialize_links(builder, media)
+      builder = deserialize_embedded(builder, media)
+    end
+    
+    def deserialize_links(builder, media)
+      (media[LINKS_KEY] || {}).each do |link_rel, link_values|
+        link_values = [link_values] unless link_values.is_a?(Array)
+        link_values = link_values.map do |hash| 
+          hash.select { |k,_| HAL_LINK_KEYS.include?(k) }
+        end
+        ensure_valid_links!(link_rel, link_values)
+        builder = builder.add_transition_array(link_rel, link_values)
+      end
+      builder
+    end
+    
+    def deserialize_properties(builder, media)
+      media.each do |k,v|
+        builder = builder.add_attribute(k, v) unless (self.class.reserved_keys.include?(k))
+      end
+      builder
+    end
+    
+  end
+end

data/lib/representors/serialization/hal_serializer.rb

@@ -0,0 +1,91 @@
+require 'representors/serialization/serializer_base'
+
+module Representors
+  module Serialization
+    class HalSerializer < SerializerBase
+      LINKS_KEY = "_links"
+      EMBEDDED_KEY = "_embedded"
+      LINKS_ONLY_OPTION = :embed_links_only
+
+      media_symbol :hal_json
+      media_type 'application/hal+json'
+
+      # This is public and returning a hash to be able to implement embedded resources
+      # serialization
+      # TODO: make this private and merge with to_media_type
+      # The name is quite misleading,
+      def to_hash(options = {})
+        base_hash, links, embedded_hals = common_serialization(@target)
+        base_hash.merge!(links.merge(embedded_hals.(options)))
+        base_hash
+      end
+
+      # This is the main entry of this class. It returns a serialization of the data
+      # in a given media type.
+      def to_media_type(options = {})
+        to_hash.to_json
+      end
+
+      private
+
+      def common_serialization(representor)
+        base_hash = get_semantics(representor)
+        embedded_hals = ->(options) { get_embedded_objects(representor, options) }
+        # we want to group by rel name because it is possible to have several transitions with the same
+        # rel name. This will become an array in the output. For instance an items array
+        # with links to each item
+        grouped_transitions = (representor.transitions + representor.meta_links).group_by { |transition| transition[:rel] }
+        links = build_links(grouped_transitions)
+        links = links.empty? ? {} : { LINKS_KEY => links.reduce({}, :merge) }
+        [base_hash, links, embedded_hals]
+      end
+
+      def get_semantics(representor)
+        representor.properties
+      end
+
+      def get_embedded_objects(representor, options)
+        @get_embedded_objects ||= if representor.embedded.empty? || options.has_key?(LINKS_ONLY_OPTION)
+          {}
+        else
+          embedded_elements = representor.embedded.map { |k, v| build_embedded_objects(k, v) }
+          { EMBEDDED_KEY => embedded_elements.reduce({}, :merge) }
+        end
+      end
+
+      # Lambda used in this case to DRY code.  Allows 'is array' functionality to be handled elsewhere
+      def build_embedded_objects(key, embedded)
+        make_media_type = ->(obj) { self.class.new(obj).to_hash }
+        embed = map_or_apply(make_media_type, embedded)
+        { key =>  embed}
+      end
+
+      # @param [Hash] transitions. A hash on the shape "rel_name" => [Transition]
+      # The value for the rel_name usually will have only one transition but when we are building an
+      # array of transitions will have many.
+      # @return [Array] Array of hashes with the format [ { rel_name => {link_info1}}, {rel_name2 => ... }]
+      def build_links(transitions)
+        transitions.map do |rel_name, transition_array|
+          links = transition_array.map{|transition| build_links_for_this_media_type(transition)}
+          if links.size > 1
+            {rel_name => links}
+          else
+            {rel_name => links.first}
+          end
+        end
+      end
+
+      # This method can be overriden by other classes
+      # @param transition , a single tansition
+      def build_links_for_this_media_type(transition)
+        link = if transition.templated?
+          { href:  transition.templated_uri, templated: true }
+        else
+          { href: transition.uri }
+        end
+        [:name, :profile].each { |key| link[key] = transition[key] if transition.has_key?(key) }
+        link
+      end
+    end
+  end
+end