yaks 0.4.4 → 0.5.0

data/lib/yaks/default_policy.rb

@@ -8,23 +8,19 @@ module Yaks
       namespace: Kernel
     }
 
-    # @!attribute [r] options
+    # @!attribute [r]
     #   @return [Hash]
     attr_reader :options
 
-    # @param [Hash] options
-    # @return [Yaks::DefaultPolicy]
+    # @param options [Hash] options
     def initialize(options = {})
       @options = DEFAULTS.merge(options)
     end
 
-    # @param [Object] model
-    # @return [Yaks::CollectionMapper, Yaks::Mapper]
-    #   or a subclass of Yaks::Mapper of some sort.
-    #
-    # @raise [NameError] only occurs when the model
-    #   is anything but a collection.
+    # @param model [Object]
+    # @return [Class] A mapper, typically a subclass of Yaks::Mapper
     #
+    # @raise [NameError] only occurs when the model is anything but a collection.
     def derive_mapper_from_object(model)
       if model.respond_to? :to_ary
         if m = model.first
@@ -45,14 +41,28 @@ module Yaks
       end
     end
 
-    # @param [Class] mapper_class
+    # Derive the a mapper type name
+    #
+    # This returns the 'system name' for a mapper,
+    # e.g. ShowEventMapper => show_event.
+    #
+    # @param [Class]  mapper_class
+    #
     # @return [String]
     def derive_type_from_mapper_class(mapper_class)
       underscore(mapper_class.name.split('::').last.sub(/Mapper$/, ''))
     end
 
-    # @param [Yaks::Mapper::Association] association
-    # @return [Class] of subclass Yaks::Mapper
+    # Derive the mapper type name from a collection
+    #
+    # This inspects the first element of the collection, so it
+    # requires a non-empty collection. Will return nil if the
+    # collection is empty.
+    #
+    # @param [#first] collection
+    #
+    # @return [String|nil]
+    #
     # @raise [NameError]
     def derive_type_from_collection(collection)
       if collection.any?
@@ -66,16 +76,24 @@ module Yaks
       @options[:namespace].const_get("#{camelize(association.singular_name)}Mapper")
     end
 
-    # @param [Yaks::Mapper::Association] association
+    # @param association [Yaks::Mapper::Association]
     # @return [String]
     def derive_rel_from_association(association)
       expand_rel( association.name )
     end
 
-    # @param [String] relname
+    # @param relname [String]
     # @return [String]
     def expand_rel(relname)
       URITemplate.new(@options[:rel_template]).expand(rel: relname)
     end
+
+    # @param format_class [Class]
+    # @return [#call] format_class
+    def serializer_for_format(format_class)
+      {
+        json: JSON.method(:pretty_generate)
+      }.fetch(format_class.serializer)
+    end
   end
 end

data/lib/yaks/format/collection_json.rb

@@ -1,11 +1,11 @@
 module Yaks
   class Format
     class CollectionJson < self
-      Format.register self, :collection_json, 'application/vnd.collection+json'
+      register :collection_json, :json, 'application/vnd.collection+json'
 
       include FP
 
-      # @param [Yaks:Resource] resource
+      # @param [Yaks::Resource] resource
       # @return [Hash]
       def serialize_resource(resource)
         result = {
@@ -29,10 +29,10 @@ module Yaks
           result = { data: attrs }
           result[:href] = item.self_link.uri if item.self_link
           item.links.each do |link|
-            next if link.rel == :self
+            next if link.rel.equal? :self
             result[:links] = [] unless result.key?(:links)
             result[:links] << {rel: link.rel, href: link.uri}
-            result[:links].last[:name] = link.name if link.name
+            result[:links].last[:name] = link.title if link.title
           end
           result
         end

data/lib/yaks/format/hal.rb

@@ -2,8 +2,26 @@
 
 module Yaks
   class Format
+    # Hypertext Application Language (http://stateless.co/hal_specification.html)
+    #
+    # A lightweight JSON Hypermedia message format.
+    #
+    # Options: +:plural_links+ In HAL, a single rel can correspond to
+    # a single link, or to a list of links. Which rels are singular
+    # and which are plural is application-dependant. Yaks assumes all
+    # links are singular. If your resource might contain multiple
+    # links for the same rel, then configure that rel to be plural. In
+    # that case it will always be rendered as a collection, even when
+    # the resource only contains a single link.
+    #
+    # @example
+    #
+    #   yaks = Yaks.new do
+    #     format_options :hal, {plural_links: [:related_content]}
+    #   end
+    #
     class Hal < self
-      Format.register self, :hal, 'application/hal+json'
+      register :hal, :json, 'application/hal+json'
 
       protected
 
@@ -14,7 +32,6 @@ module Yaks
         # looking at client behavior (Hyperagent) it seems safer to return an empty
         # resource.
         #
-        # return nil if resource.is_a? NullResource
         result = resource.attributes
         result = result.merge(:_links => serialize_links(resource.links)) unless resource.links.empty?
         result = result.merge(:_embedded => serialize_embedded(resource.subresources)) unless resource.subresources.empty?
@@ -37,7 +54,7 @@ module Yaks
         memo[link.rel] = if singular?(link.rel)
                            hal_link
                          else
-                           Array(memo[link.rel]) + [hal_link]
+                           (memo[link.rel] || []) + [hal_link]
                          end
         memo
       end

data/lib/yaks/format/json_api.rb

@@ -2,8 +2,8 @@
 
 module Yaks
   class Format
-    class JsonApi < self
-      Format.register self, :json_api, 'application/vnd.api+json'
+    class JsonAPI < self
+      register :json_api, :json, 'application/vnd.api+json'
 
       include FP
 
@@ -40,7 +40,7 @@ module Yaks
       # @return [Hash]
       def serialize_links(subresources)
         subresources.each_with_object({}) do |(_name, resource), hsh|
-          next if resource.is_a? NullResource
+          next if resource.instance_of? NullResource
           key = resource.collection? ? pluralize(resource.type) : resource.type
           hsh[key] = serialize_link(resource)
         end

data/lib/yaks/format.rb

@@ -2,40 +2,85 @@ module Yaks
   class Format
     extend Forwardable
     include Util
+    include FP::Callable
 
+    # @!attribute [r] options
+    #   @return [Hash]
     attr_reader :options
+
     def_delegators :resource, :links, :attributes, :subresources
 
     protected :links, :attributes, :subresources, :options
 
+    # @param [Hash] options
+    # @return [Hash]
     def initialize(options = {})
       @options = options
     end
 
+    # @param [Yaks::Resource] resource
+    # @return [Hash]
     def call(resource)
       serialize_resource(resource)
     end
     alias serialize call
 
     class << self
-      def register(klass, name, mime_type)
-        @formats ||= {}
-        @formats[name] = klass
+      attr_reader :format_name, :serializer, :mime_type
+
+      def all
+        @formats ||= []
+      end
 
-        @mime_types  ||= {}
-        @mime_types[mime_type] = [name, klass]
+      # @param [Constant] klass
+      # @param [Symbol] format_name
+      # @param [String] mime_type
+      # @return [Array]
+      def register(format_name, serializer, mime_type)
+        @format_name = format_name
+        @serializer = serializer
+        @mime_type = mime_type
+
+        Format.all << self
       end
 
-      def by_name(name)
-        @formats.fetch(name)
+      # @param [Symbol] format_name
+      # @return [Constant]
+      # @raise [KeyError]
+      def by_name(format_name)
+        find(:format_name, format_name)
       end
 
+      # @param [Symbol] mime_type
+      # @return [Constant]
+      # @raise [KeyError]
       def by_mime_type(mime_type)
-        @mime_types.fetch(mime_type)[1]
+        find(:mime_type, mime_type)
+      end
+
+      def by_accept_header(accept_header)
+        mime_type = Rack::Accept::Charset.new(accept_header).best_of(mime_types.values)
+        if mime_type
+          by_mime_type(mime_type)
+        else
+          yield if block_given?
+        end
       end
 
       def mime_types
-        @mime_types.inject({}) {|memo, (mime_type, (name, _))| memo[name] = mime_type ; memo }
+        Format.all.each_with_object({}) do
+          |format, memo| memo[format.format_name] = format.mime_type
+        end
+      end
+
+      def names
+        mime_types.keys
+      end
+
+      private
+
+      def find(key, cond)
+        Format.all.detect {|format| format.send(key) == cond }
       end
     end
   end

data/lib/yaks/fp/callable.rb

@@ -0,0 +1,9 @@
+module Yaks
+  module FP
+    module Callable
+      def to_proc
+        method(:call).to_proc
+      end
+    end
+  end
+end

data/lib/yaks/fp/hash_updatable.rb

@@ -2,6 +2,8 @@ module Yaks
   module FP
 
     class HashUpdatable < Module
+      # @param [Array] attributes
+      # @return [Symbol]
       def initialize(*attributes)
         define_method :update do |updates|
           self.class.new(

data/lib/yaks/fp/updatable.rb

@@ -2,6 +2,8 @@ module Yaks
   module FP
 
     class Updatable < Module
+      # @param [Array] attributes
+      # @return [Symbol]
       def initialize(*attributes)
         define_method :update do |updates|
           self.class.new(

data/lib/yaks/fp.rb

@@ -2,15 +2,23 @@ module Yaks
   module FP
     extend self
 
+    # @param [Symbol, String] name
+    # @return [Proc]
     def curry_method(name)
       method(name).to_proc.curry
     end
 
+
+    # @return [Proc]
     def identity_function
       ->(x) {x}
     end
     I = identity_function
 
+    # @param [Symbol] symbol
+    # @param [Array] args
+    # @param [Proc] blk
+    # @return [Proc]
     def send_with_args(symbol, *args, &blk)
       ->(obj) { obj.method(symbol).(*args, &blk) }
     end

data/lib/yaks/mapper/link.rb

@@ -57,7 +57,7 @@ module Yaks
       end
 
       def expansion_mapping(lookup)
-        template_variables.map.with_object({}) do |name, hsh|
+        template_variables.each_with_object({}) do |name, hsh|
           hsh[name] = lookup[name]
         end
       end
@@ -74,7 +74,7 @@ module Yaks
       end
 
       def expand_with(lookup)
-        return lookup[template] if template.is_a? Symbol
+        return lookup[template] if template.instance_of? Symbol
 
         expand_partial(expansion_mapping(lookup)).to_s
       end

data/lib/yaks/mapper.rb

@@ -55,20 +55,20 @@ module Yaks
     private
 
     def map_attributes(resource)
-      attributes.inject(resource) do |resource, attribute|
-        attribute.add_to_resource(resource, self, context)
+      attributes.inject(resource) do |res, attribute|
+        attribute.add_to_resource(res, self, context)
       end
     end
 
     def map_links(resource)
-      links.inject(resource) do |resource, mapper_link|
-        mapper_link.add_to_resource(resource, self, context)
+      links.inject(resource) do |res, mapper_link|
+        mapper_link.add_to_resource(res, self, context)
       end
     end
 
     def map_subresources(resource)
-      associations.inject(resource) do |resource, association|
-        association.add_to_resource( resource, self, context)
+      associations.inject(resource) do |res, association|
+        association.add_to_resource(res, self, context)
       end
     end
   end

data/lib/yaks/primitivize.rb

@@ -22,7 +22,7 @@ module Yaks
 
     def self.create
       new.tap do |p|
-        p.map String, TrueClass, FalseClass, NilClass, Numeric do |object|
+        p.map String, Numeric, true, false, nil do |object|
           object
         end
 
@@ -31,7 +31,7 @@ module Yaks
         end
 
         p.map Hash do |object|
-          object.to_enum(:each).with_object({}) do |(key, value), output|
+          object.to_enum.with_object({}) do |(key, value), output|
             output[call(key)] = call(value)
           end
         end

data/lib/yaks/resource/link.rb

@@ -9,10 +9,6 @@ module Yaks
         @rel, @uri, @options = rel, uri, options
       end
 
-      def name
-        options[:name]
-      end
-
       def title
         options[:title]
       end

data/lib/yaks/runner.rb

@@ -0,0 +1,90 @@
+module Yaks
+  class Runner
+    include Util
+    include Anima.new(:object, :config, :options)
+    include Adamantium::Flat
+    extend Forwardable
+
+    def_delegators :config, :policy, :default_format, :format_options, :primitivize, :serializers, :hooks
+
+    def call
+      steps.inject(object) {|memo, (_, step)| step.call(memo) }
+    end
+
+    def context
+      {
+        policy: policy,
+        env: env,
+        mapper_stack: []
+      }.merge(slice_hash(options, :item_mapper))
+    end
+    memoize :context, freezer: :flat
+
+    def env
+      options.fetch(:env, {})
+    end
+    memoize :env, freezer: :noop
+
+    # @return [Class]
+    def format_class
+      Format.by_accept_header(env['HTTP_ACCEPT']) {
+        Format.by_name(options.fetch(:format) { default_format })
+      }
+    end
+    memoize :format_class
+
+    def steps
+      insert_hooks(
+        [[ :map, mapper ],
+         [ :format, formatter ],
+         [ :primitivize, primitivize], # really a JSON-preprocessor, should be pulled out
+         [ :serialize, serializer ]])
+    end
+    memoize :steps
+
+    def mapper
+      options.fetch(:mapper) do
+        policy.derive_mapper_from_object(object)
+      end.new(context)
+    end
+    memoize :mapper, freezer: :noop
+
+    def formatter
+      format_class.new(format_options[format_name])
+    end
+    memoize :formatter
+
+    # @param [Hash] opts
+    # @return [String]
+    def format_name
+      options.fetch(:format) { default_format }
+    end
+    memoize :format_name
+
+    def serializer
+      serializers.fetch(format_class.serializer) do
+        policy.serializer_for_format(format_class)
+      end
+    end
+    memoize :serializer
+
+    def insert_hooks(steps)
+      hooks.inject(steps) do |steps, (type, target_step, name, hook)|
+        steps.flat_map do |step_name, callable|
+          if step_name.eql? target_step
+            case type
+            when :before
+              [[name, hook], [step_name, callable]]
+            when :after
+              [[step_name, callable], [name, hook]]
+            when :around
+              [[step_name, ->(x) { hook.call(x, &callable) }]]
+            when :skip
+              []
+            end
+          end || [[step_name, callable]]
+        end
+      end
+    end
+  end
+end

data/lib/yaks/util.rb

@@ -18,6 +18,10 @@ module Yaks
         .gsub!(/(?:^|_)(.)/) { $1.upcase          }
     end
 
+    def slice_hash(hash, *keys)
+      keys.each_with_object({}) {|k,dest| dest[k] = hash[k] if hash.key?(k) }
+    end
+
     # Turn what is maybe a Proc into its result (or itself)
     #
     # When input can be either a value or a proc that returns a value,

data/lib/yaks/version.rb

@@ -1,3 +1,3 @@
 module Yaks
-  VERSION = '0.4.4'
+  VERSION = '0.5.0'
 end

data/lib/yaks.rb

@@ -4,6 +4,7 @@ require 'forwardable'
 require 'set'
 require 'pathname'
 
+require 'anima'
 require 'concord'
 require 'inflection'
 require 'uri_template'
@@ -13,6 +14,7 @@ require 'yaks/util'
 require 'yaks/fp'
 require 'yaks/fp/updatable'
 require 'yaks/fp/hash_updatable'
+require 'yaks/fp/callable'
 require 'yaks/primitivize'
 
 require 'yaks/default_policy'
@@ -57,3 +59,4 @@ require 'yaks/format/collection_json'
 
 require 'yaks/config/dsl'
 require 'yaks/config'
+require 'yaks/runner'

data/spec/acceptance/acceptance_spec.rb

@@ -7,6 +7,7 @@ RSpec.describe Yaks::Format::Hal do
   yaks_rel_template = Yaks.new do
     format_options :hal, plural_links: ['http://literature.example.com/rels/quotes']
     rel_template "http://literature.example.com/rel/{association_name}"
+    skip :serialize
   end
 
   yaks_policy_dsl = Yaks.new do
@@ -14,15 +15,17 @@ RSpec.describe Yaks::Format::Hal do
     derive_rel_from_association do |association|
       "http://literature.example.com/rel/#{association.name}"
     end
+    skip :serialize
   end
 
   include_examples 'JSON output format' , yaks_rel_template , :hal , 'confucius'
   include_examples 'JSON output format' , yaks_policy_dsl   , :hal , 'confucius'
 end
 
-RSpec.describe Yaks::Format::JsonApi do
+RSpec.describe Yaks::Format::JsonAPI do
   config = Yaks.new do
     default_format :json_api
+    skip :serialize
   end
 
   include_examples 'JSON output format' , config , :json_api , 'confucius'
@@ -32,10 +35,12 @@ RSpec.describe Yaks::Format::CollectionJson do
   youtypeit_yaks = Yaks.new do
     default_format :collection_json
     namespace Youtypeitwepostit
+    skip :serialize
   end
 
   confucius_yaks = Yaks.new do
     default_format :collection_json
+    skip :serialize
   end
 
   include_examples 'JSON output format', youtypeit_yaks, :collection, 'youtypeitwepostit'

data/spec/json/confucius.collection.json

@@ -6,22 +6,10 @@
       {
         "href": "http://literature.example.com/authors/kongzi",
         "data": [
-          {
-            "name": "id",
-            "value": 9
-          },
-          {
-            "name": "name",
-            "value": "孔子"
-          },
-          {
-            "name": "pinyin",
-            "value": "Kongzi"
-          },
-          {
-            "name": "latinized",
-            "value": "Confucius"
-          }
+          { "name": "id",         "value": 9           },
+          { "name": "name",       "value": "孔子"      },
+          { "name": "pinyin",     "value": "Kongzi"    },
+          { "name": "latinized",  "value": "Confucius" }
         ],
         "links": [
           {
@@ -29,6 +17,7 @@
             "href": "http://literature.example.com/profiles/scholar"
           },
           {
+            "name": "Search for quotes",
             "rel": "http://literature.example.com/rels/quotes",
             "href": "http://literature.example.com/quotes/?author=kongzi&q={query}"
           }

data/spec/json/plant_collection.collection.json

@@ -0,0 +1,32 @@
+{
+  "collection": {
+    "version": "1.0",
+    "href": "http://api.example.com/plants",
+    "items": [
+      {
+        "href": "http://api.example.com/plants/7/plain_grass",
+        "data": [ { "name": "name", "value": "Plain grass" },
+                  { "name": "type", "value": "grass" } ],
+        "links": [
+          { "rel": "profile", "href": "http://api.example.com/doc/plant" }
+        ]
+      },
+      {
+        "href": "http://api.example.com/plants/15/oak",
+        "data": [ { "name": "name", "value": "Oak" },
+                  { "name": "type", "value": "tree" } ],
+        "links": [
+          { "rel": "profile", "href": "http://api.example.com/doc/plant" }
+        ]
+      },
+      {
+        "href": "http://api.example.com/plants/33/passiflora",
+        "data": [ { "name": "name", "value": "Passiflora" },
+                  { "name": "type", "value": "flower" } ],
+        "links": [
+          { "rel": "profile", "href": "http://api.example.com/doc/plant" }
+        ]
+      }
+    ]
+  }
+}

data/spec/spec_helper.rb

@@ -20,10 +20,11 @@ require_relative 'support/classes_for_policy_testing'
 RSpec.configure do |rspec|
   rspec.include FixtureHelpers
   rspec.backtrace_exclusion_patterns = [] if ENV['FULLSTACK']
-  #rspec.disable_monkey_patching!
+  rspec.disable_monkey_patching!
   rspec.raise_errors_for_deprecations!
 end
 
 Bogus.configure do |bogus|
   bogus.search_modules << Yaks
+  bogus.search_modules << Yaks::Mapper
 end