yaks 0.4.1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 40c42f259955a15a723d0782ab4378201bf511b3
-  data.tar.gz: 360a9de28a43b27cf820c26aec19c6627a7dac2b
+  metadata.gz: 0b888259337e9fa643458e613fda2f50e561a72e
+  data.tar.gz: e6ff86a9a5d402b857041f1a676b81f6324078d7
 SHA512:
-  metadata.gz: 5fb54a5b204c60f385aa4b8e4915c6fce1c89dcb1340b48323242c4ade3a4265d44a5ff37f5d587302cab90ad6e05003e160e290fe69b36f19285934d94f3faf
-  data.tar.gz: 5d4462422ddd28e6106846a8663fbdb43bf2ad33b302c24bdcc0f424edae60d1774455d0f70cd3041422aafdd6d0d6ee697558942026ac1bd84d66f149816748
+  metadata.gz: edfa665288d44ed62d397beeb2419092b7220129475c77f5cbce4413a981f1d57f44578faf27e3a77da3c6a818a3b5bc0f5bbeaeaa966aeab82d55f6b1960694
+  data.tar.gz: 7391bc4fab6497ce52c6353db032786df91ab01730cd8486aed53179321ebd3c9baf49a54509edbcddd14796b1daefecc98903b0bfd8b9fe94753cb4fe2f1490

data/.travis.yml

@@ -1,16 +1,25 @@
 language: ruby
-script: "bundle exec rspec"
+script: bundle exec $RUN
 rvm:
   - 1.9.3
   - 2.0.0
-  - 2.1.1
-  - rbx
-  - jruby
+  - 2.1.2
   - ruby-head
+  - rbx-2
+  - jruby
   - jruby-head
+env:
+  - RUN=rspec
+  - RUN=rake
 matrix:
   allow_failures:
-    - rvm: rbx
-    - rvm: jruby
     - rvm: ruby-head
     - rvm: jruby-head
+    - env: RUN=rake
+  exclude:
+    - rvm: jruby
+      env: RUN=rake
+    - rvm: jruby-head
+      env: RUN=rake
+    - rvm: rbx-2
+      env: RUN=rake

data/ADDING_FORMATS.md

@@ -0,0 +1,13 @@
+# Adding Extra Output Formats to Yaks
+
+Individual output formats are each handled by a dedicated `Yaks::Serializer` class. These take a `Yaks::Resource` as input, and turn it into the requested output format.
+
+A `Yaks::Resource` is created by "mapping" domain models by a `Yaks::Mapper`. In a `Yaks::Mapper` subclass a DSL is available to specify how to extract different types of information, for example attributes or links, and store them in a generalized way in a `Resource`.
+
+Different formats have different features. Simple formats might just represent attributes, links, and subresources, other formats have queries, forms, or RDF identifiers. If a format represents data of a different nature, then the first step is to decide on a good and straightforward syntax to specify how to derive this data. This can then be stored in a `Yaks::Resource`, and formats that support it can use it, other formats can ignore it.
+
+This is already the case, JSON-API ignores links for example.
+
+So adding an output format is generally straightforward, as long as the information that the output format supports is already available in `Yaks::Resource`. In that case adding a `Yaks::Serializer::YourFormat` is all that is needed.
+
+If the format has features that are not yet available then syntax needs to be added for those features. The guiding idea there is to try and find more than one format with the given feature, to make sure the intermediate abstraction is general and not tied to the specifics and vocabulary of a single format.

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+### Development
+[full changelog](http://github.com/plexus/yaks/compare/v0.4.2...master)
+
+### v0.4.2
+
+* JSON-API: render self links as href attributes
+* HAL: render has_one returning nil as null, not as {}
+* Keep track of the mapper stack, useful for figuring out if mapping the top level response or not, or for accessing parent
+* Change Serializer.new(resource, options).serialize to Serializer.new(options).call(resource) for cosistency of "pipeline" interface
+* Make Yaks::CollectionMapper#collection overridable for pagination
+* Don't render links from custom link methods (link :foo, :method_that_generates_url) that return nil
+
 # v0.4.1
 
 * Change how env is passed to yaks.serialize to match docs

data/IDENTIFIERS.md

@@ -0,0 +1,113 @@
+# Identifiers
+
+In Yaks, and Hypermedia message formats in general, a number of different types of identifiers are used. Some are full URIs and correspond with well defined specs. Some are just short identifers that are easy to program with.
+
+Understanding these types of identifiers is key to creating a unifying model of a "Resource" that can be shared across output formats. We want to unify as much as possible across formats, without conflating things that are really not the same.
+
+This document reflects my current limited understanding of things, based on possibly incorrect assumptions. Feedback is more than welcome.
+
+## rels
+
+As used in HTML and Atom, these identifiers say what the relationship is between a resource and another resource it links to. There is a [registry of names](http://www.iana.org/assignments/link-relations/link-relations.xhtml), e.g. self, next, profile, stylesheet. Custom rels need to be fully qualified URLs. Keep in mind that these are simply opaque identifiers, but by using a known protocol like http they can be used to point at documentation.
+
+Some examples
+
+```
+copyright
+stylesheet
+http://api.example.com/rel/author
+http://api.example.com/api-docs/relationships#comment
+custom_scheme:foo
+/order
+```
+
+The last example is a relative URL, which would have to be expanded against the source URL of the document it is mentioned in.
+
+In Yaks both links and subresources are specified with their rel(ationship).
+
+```ruby
+class PersonMapper < Yaks::Mapper
+  link :self, '/people/{id}'
+  link 'http://api.example.com/rels#friends', '/people/{id}/friends'
+
+  has_one :address, rel: 'http://api.example.com/rels#address'
+end
+```
+
+For subresources the rel can be omitted, in which case it will be inferred based on the rel_template:
+
+```ruby
+$yaks = Yaks.new do
+  rel_template 'http://api.example.com/rels/{dest}'
+end
+```
+
+Links and subresources are rendered keyed by rel in HAL and Collection+JSON. JSON-API renders `self` links as the `href` of a resource.
+
+## profiles
+
+A specific IANA registered rel type is profile.
+
+> Profile: Identifying that a resource representation conforms to a certain profile, without affecting the non-profile semantics of the resource representation.
+
+Profile basically adds a layer of semantics on top of the hypermedia message format (e.g. HAL, Collection+JSON), which in turns defines semantics on top of a serialization format (JSON, XML, EDN). Loosely speaking it could be seen as the "type" or "class". For example if you know the profile of a resource, you might know you can expect to find a "name", "date_of_birth", or "post_body" field.
+
+## "type"
+
+Despite the appealing rigor of having fully qualified URIs to identify things, sometimes you just want to call a person a `person`. In Yaks we call these short identifier the *type* for lack of a better word. In some cases, notably JSON-API, they are used literally in the output. More often they are used to derive full URIs based on a template.
+
+The type of a mapper is inferred from its class name, but can be set explicitly as well.
+
+```ruby
+class CatMapper < Yaks::Mapper
+end
+
+# type = "cat"
+```
+
+```ruby
+class CatMapper < Yaks::Mapper
+  type 'feline'
+end
+
+# type => "feline"
+```
+
+## rdf class
+
+RDF (Resource Description Framework) is a set of specifications for use in "semantic web" applications. RDF is based on "ontologies" that precisely define a "vocabulary" of "classes" and "predicates". An example class identifier for all Merlot wines could be
+
+> http://www.w3.org/TR/2004/REC-owl-guide-20040210/wine#Merlot
+
+(source [wikipedia](http://en.wikipedia.org/wiki/Resource_Description_Framework))
+
+Not currently used by Yaks, but might become important when implementing support for JSON-LD or other RDF serialization formats.
+
+## CURIES
+
+CURIES are "compact uris". The HAL format uses this so it can have the rigor of fully specified rels, with the ease of use of short-name "type" identifiers. The mechanism is similar to how one specifies and uses XML namespaces.
+
+From the HAL spec:
+
+```json
+{
+    "_links": {
+        "self": { "href": "/orders" },
+        "curies": [{ "name": "ea", "href": "http://example.com/docs/rels/{rel}", "templated": true }],
+        "next": { "href": "/orders?page=2" },
+        "ea:find": {
+            "href": "/orders{?id}",
+            "templated": true
+        },
+        "ea:admin": [{
+            "href": "/admins/2",
+            "title": "Fred"
+        }, {
+            "href": "/admins/5",
+            "title": "Kate"
+        }]
+    }
+}
+```
+
+In this case "ea:find" is just a shorthand for "http://example.com/docs/rels/find".

data/lib/yaks/collection_mapper.rb

@@ -2,7 +2,6 @@
 
 module Yaks
   class CollectionMapper < Mapper
-    attr_reader :collection
     alias collection object
 
     def initialize(context)
@@ -24,7 +23,7 @@ module Yaks
         type: collection_type,
         links: map_links,
         attributes: map_attributes,
-        members: collection.map do |obj|
+        members: collection().map do |obj|
           mapper_for_model(obj).new(context).call(obj)
         end
       }

data/lib/yaks/collection_resource.rb

@@ -44,7 +44,7 @@ module Yaks
     #
     # :(
     def subresources
-      if members.any?
+      if any?
         { members_rel => self }
       else
         {}

data/lib/yaks/config.rb

@@ -70,10 +70,10 @@ module Yaks
     def serializer_class(opts, env)
       if env.key? 'HTTP_ACCEPT'
         accept = Rack::Accept::Charset.new(env['HTTP_ACCEPT'])
-        mime_type = accept.best_of(Yaks::Serializer.mime_types.values)
-        return Yaks::Serializer.by_mime_type(mime_type) if mime_type
+        mime_type = accept.best_of(Serializer.mime_types.values)
+        return Serializer.by_mime_type(mime_type) if mime_type
       end
-      Yaks::Serializer.by_name(opts.fetch(:format) { @default_format })
+      Serializer.by_name(opts.fetch(:format) { @default_format })
     end
 
     def format_name(opts)
@@ -92,12 +92,14 @@ module Yaks
       env = opts.fetch(:env, {})
       context = {
         policy: policy,
-        env: env
+        env: env,
+        mapper_stack: []
       }
-      mapper     = opts.fetch(:mapper) { policy.derive_mapper_from_object(object) }
-      resource   = mapper.new(context).call(object)
-      serialized = serializer_class(opts, env).new(resource, format_options[format_name(opts)]).call
-      steps.inject(serialized) {|memo, step| step.call(memo) }
+
+      mapper     = opts.fetch(:mapper) { policy.derive_mapper_from_object(object) }.new(context)
+      serializer = serializer_class(opts, env).new(format_options[format_name(opts)])
+
+      [ mapper, serializer, *steps ].inject(object) {|memo, step| step.call(memo) }
     end
     alias serialize call
   end

data/lib/yaks/mapper/link.rb

@@ -63,11 +63,10 @@ module Yaks
       end
 
       def map_to_resource_link(mapper)
-        Resource::Link.new(
-          rel,
-          expand_with(mapper.method(:load_attribute)),
-          resource_link_options(mapper)
-        )
+        uri = expand_with(mapper.method(:load_attribute))
+        return if uri.nil?
+
+        Resource::Link.new(rel, uri, resource_link_options(mapper))
       end
 
       def expand_with(lookup)

data/lib/yaks/mapper.rb

@@ -22,6 +22,10 @@ module Yaks
       context.fetch(:env)
     end
 
+    def mapper_stack
+      context.fetch(:mapper_stack)
+    end
+
     def call(object)
       @object = object
 
@@ -42,7 +46,7 @@ module Yaks
     end
 
     def map_links
-      links.map &send_with_args(:map_to_resource_link, self)
+      links.map(&send_with_args(:map_to_resource_link, self)).compact
     end
 
     def map_subresources
@@ -52,7 +56,7 @@ module Yaks
         rel, subresource = association.create_subresource(
           self,
           method(:load_association),
-          context
+          context.merge(mapper_stack: mapper_stack + [self])
         )
         memo[rel] = subresource
       end

data/lib/yaks/null_resource.rb

@@ -3,11 +3,11 @@ module Yaks
     include Enumerable
 
     def initialize(opts = {})
-      @collection = opts.fetch(:collection, false)
+      @collection = opts.fetch(:collection) { false }
     end
 
     def each
-      return to_enum unless block_given?
+      to_enum
     end
 
     def attributes
@@ -31,5 +31,9 @@ module Yaks
     def collection?
       @collection
     end
+
+    def null_resource?
+      true
+    end
   end
 end

data/lib/yaks/primitivize.rb

@@ -37,7 +37,7 @@ module Yaks
         end
 
         p.map Enumerable do |object|
-          object.map(&method(:call)).to_a
+          object.map(&method(:call))
         end
       end
     end

data/lib/yaks/resource.rb

@@ -24,15 +24,18 @@ module Yaks
       yield self
     end
 
-    def collection?
-      false
-    end
-
     def self_link
       links.find do |link|
-        link.rel == :self
+        link.rel.equal? :self
       end
     end
 
+    def collection?
+      false
+    end
+
+    def null_resource?
+      false
+    end
   end
 end

data/lib/yaks/serializer/hal.rb

@@ -45,7 +45,7 @@ module Yaks
           memo[rel] = if resources.collection?
                         resources.map( &method(:serialize_resource) )
                       else
-                        serialize_resource(resources)
+                        serialize_resource(resources) unless resources.null_resource?
                       end
         end
       end

data/lib/yaks/serializer/json_api.rb

@@ -7,23 +7,28 @@ module Yaks
 
       include FP
 
-      def call
-        serialized = {
-          pluralize(resource.type) => resource.map(&method(:serialize_resource))
-        }
+      def call(resource)
+        main_collection = resource.map(&method(:serialize_resource))
 
-        linked = resource.each_with_object({}) do |res, hsh|
-          serialize_linked_subresources(res.subresources, hsh)
+        { pluralize(resource.type) => main_collection }.tap do |serialized|
+          linked = resource.each_with_object({}) do |res, hsh|
+            serialize_linked_subresources(res.subresources, hsh)
+          end
+          serialized.merge!(linked: linked) unless linked.empty?
         end
-        serialized = serialized.merge('linked' => linked)
-
-        serialized
       end
-      alias serialize call
 
       def serialize_resource(resource)
         result = resource.attributes
-        result = result.merge(:links => serialize_links(resource.subresources)) unless resource.subresources.empty?
+
+        unless resource.subresources.empty?
+          result[:links] = serialize_links(resource.subresources)
+        end
+
+        if resource.self_link && !result.key?(:href)
+          result[:href]  = resource.self_link.uri
+        end
+
         result
       end
 

data/lib/yaks/serializer.rb

@@ -3,17 +3,16 @@ module Yaks
     extend Forwardable
     include Util
 
-    attr_reader :resource, :options
+    attr_reader :options
     def_delegators :resource, :links, :attributes, :subresources
 
-    protected :resource, :links, :attributes, :subresources, :options
+    protected :links, :attributes, :subresources, :options
 
-    def initialize(resource, options = {})
-      @resource = resource
+    def initialize(options = {})
       @options  = YAKS_DEFAULT_OPTIONS.merge(options)
     end
 
-    def call
+    def call(resource)
       serialize_resource(resource)
     end
     alias serialize call

data/lib/yaks/version.rb

@@ -1,3 +1,3 @@
 module Yaks
-  VERSION = '0.4.1'
+  VERSION = '0.4.2'
 end

data/spec/acceptance/acceptance_spec.rb

@@ -4,7 +4,7 @@ require_relative './models'
 
 RSpec.shared_examples_for 'JSON output format' do |yaks, format, name|
   let(:input)  { load_yaml_fixture(name) }
-  let(:output) { load_json_fixture "#{name}.#{format}" }
+  let(:output) { load_json_fixture("#{name}.#{format}") }
 
   subject { yaks.serialize(input) }
 

data/spec/acceptance/models.rb

@@ -24,7 +24,9 @@ end
 class ScholarMapper < LiteratureBaseMapper
   attributes :id, :name, :pinyin, :latinized
   has_many :works
-  link :self, "http://literature.example.com/authors/{downcased_pinyin}"
+
+  link 'http://literature.example.com/rels/quotes', 'http://literature.example.com/quotes/?author={downcased_pinyin}&q={query}', expand: [:downcased_pinyin]
+  link :self, 'http://literature.example.com/authors/{downcased_pinyin}'
 
   def downcased_pinyin
     object.pinyin.downcase

data/spec/integration/map_to_resource_spec.rb

@@ -2,9 +2,10 @@ require 'spec_helper'
 
 RSpec.describe 'Mapping domain models to Resource objects' do
   include_context 'fixtures'
+  include_context 'yaks context'
 
   subject { mapper.call(john) }
-  let(:mapper) { FriendMapper.new(policy: Yaks::DefaultPolicy.new, env: {}) }
+  let(:mapper) { FriendMapper.new(yaks_context) }
 
   it { should be_a Yaks::Resource }
   its(:type)         { should eql 'friend' }

data/spec/json/confucius.hal.json

@@ -5,7 +5,11 @@
   "latinized": "Confucius",
   "_links": {
     "self":    { "href": "http://literature.example.com/authors/kongzi"  },
-    "profile": { "href": "http://literature.example.com/profiles/scholar" }
+    "profile": { "href": "http://literature.example.com/profiles/scholar" },
+    "http://literature.example.com/rels/quotes": {
+        "href": "http://literature.example.com/quotes/?author=kongzi&q={query}",
+        "templated": true
+    }
   },
   "_embedded": {
     "http://literature.example.com/rel/works": [

data/spec/json/confucius.json_api.json

@@ -2,6 +2,7 @@
   "scholars": [
     {
       "id": 9,
+      "href": "http://literature.example.com/scholar/9",
       "name": "孔子",
       "pinyin": "Kongzi",
       "latinized": "Confucius",
@@ -14,6 +15,7 @@
     "works": [
       {
         "id": 11,
+        "href": "http://literature.example.com/work/11",
         "chinese_name": "論語",
         "english_name": "Analects",
         "links": {
@@ -23,6 +25,7 @@
       },
       {
         "id": 12,
+        "href": "http://literature.example.com/work/12",
         "chinese_name": "易經",
         "english_name": "Commentaries to the Yi-jing",
         "links": {}

data/spec/support/deep_eql.rb

@@ -45,6 +45,7 @@ module Matchers
     end
 
     def compare(key)
+#require 'pry' ; binding.pry
       push key
       if target[key] != expectation[key]
         if [Hash, Array].any?{|klz| target[key].is_a? klz }
@@ -88,6 +89,11 @@ module Matchers
         else
           failure_message("expected Array got #{@target.inspect}")
         end
+
+      else
+        if target != expectation
+          failure_message("expected #{expectation.inspect}, got #{@target.inspect}")
+        end
       end
 
       result

data/spec/support/shared_contexts.rb

@@ -1,4 +1,4 @@
-shared_context 'collection resource' do
+RSpec.shared_context 'collection resource' do
   let(:resource) do
     Yaks::CollectionResource.new(
       links: links,
@@ -10,7 +10,14 @@ shared_context 'collection resource' do
   let(:members)  { [] }
 end
 
-shared_context 'plant collection resource' do
+RSpec.shared_context 'yaks context' do
+  let(:policy)            { Yaks::DefaultPolicy.new }
+  let(:rack_env)          { {} }
+  let(:mapper_stack)      { [] }
+  let(:yaks_context)      { { policy: policy, env: rack_env, mapper_stack: mapper_stack } }
+end
+
+RSpec.shared_context 'plant collection resource' do
   include_context 'collection resource'
 
   let(:links)   { [ plants_self_link, plants_profile_link ] }

data/spec/unit/yaks/collection_mapper_spec.rb

@@ -3,11 +3,14 @@ require 'spec_helper'
 RSpec.describe Yaks::CollectionMapper do
   include_context 'fixtures'
 
-  subject(:mapper) { described_class.new(context) }
+  subject(:mapper) { mapper_class.new(context) }
+  let(:mapper_class) { described_class }
+
   let(:context) {
     { member_mapper: member_mapper,
       policy: policy,
-      env: {}
+      env: {},
+      mapper_stack: []
     }
   }
   let(:collection) { [] }
@@ -29,8 +32,6 @@ RSpec.describe Yaks::CollectionMapper do
     let(:member_mapper) { PetMapper }
 
     it 'should map the members' do
-      mapper.call(collection)
-
       expect(mapper.call(collection)).to eql Yaks::CollectionResource.new(
         type: 'pet',
         links: [],
@@ -87,4 +88,31 @@ RSpec.describe Yaks::CollectionMapper do
     end
   end
 
+  describe 'overriding #collection' do
+    let(:mapper_class) do
+      Class.new(described_class) do
+        type 'pet'
+
+        def collection
+          super.drop(1)
+        end
+      end
+    end
+
+    let(:collection) { [boingboing, wassup]}
+    let(:member_mapper) { PetMapper }
+
+    it 'should use the redefined collection method' do
+      expect(mapper.call(collection)).to eql Yaks::CollectionResource.new(
+        type: 'pet',
+        links: [],
+        attributes: {},
+        members: [
+          Yaks::Resource.new(type: 'pet', attributes: {:id => 3, :species => "cat", :name => "wassup"})
+        ],
+        members_rel: 'rel:src=collection&dest=pets'
+      )
+    end
+  end
+
 end

data/spec/unit/yaks/collection_resource_spec.rb

@@ -4,7 +4,8 @@ RSpec.describe Yaks::CollectionResource do
   subject(:collection) { described_class.new(init_opts) }
   let(:init_opts) { {} }
 
-  its(:collection?) { should equal true }
+  its(:collection?)    { should be true }
+  its(:null_resource?) { should be false }
 
   context 'with nothing passed in the contstructor' do
     its(:type)         { should be_nil  }
@@ -12,6 +13,7 @@ RSpec.describe Yaks::CollectionResource do
     its(:attributes)   { should eql({}) }
     its(:members)      { should eql []  }
     its(:subresources) { should eql({}) }
+    its(:members_rel)  { should eql('members') }
   end
 
   context 'with a full constructor' do
@@ -29,7 +31,8 @@ RSpec.describe Yaks::CollectionResource do
             links: [Yaks::Resource::Link.new(:self, 'http://order/10', {})],
             attributes: { customer: 'John Doe', price: 10.00 }
           )
-        ]
+        ],
+        members_rel: 'http://api.example.org/rels/orders'
       }
     }
 
@@ -48,9 +51,10 @@ RSpec.describe Yaks::CollectionResource do
         )
       ]
     }
+    its(:members_rel) { should eq 'http://api.example.org/rels/orders'}
 
     its(:subresources) { should eql(
-        'members' => Yaks::CollectionResource.new(
+        'http://api.example.org/rels/orders' => Yaks::CollectionResource.new(
           type: 'order',
           attributes: { total: 10.00 },
           links: [
@@ -64,6 +68,7 @@ RSpec.describe Yaks::CollectionResource do
               attributes: { customer: 'John Doe', price: 10.00 }
             )
           ],
+          members_rel: 'http://api.example.org/rels/orders'
         )
       )
     }

data/spec/unit/yaks/mapper/has_many_spec.rb

@@ -1,7 +1,11 @@
 require 'spec_helper'
 
 RSpec.describe Yaks::Mapper::HasMany do
-  let(:closet_mapper) do
+  include_context 'yaks context'
+
+  let(:closet_mapper) { closet_mapper_class.new(yaks_context) }
+
+  let(:closet_mapper_class) do
     Class.new(Yaks::Mapper) do
       type 'closet'
       has_many :shoes,
@@ -10,6 +14,10 @@ RSpec.describe Yaks::Mapper::HasMany do
     end
   end
 
+  subject(:shoe_association) { closet_mapper.associations.first }
+
+  its(:singular_name) { should eq 'shoe' }
+
   let(:closet) {
     double(
       :shoes => [
@@ -20,7 +28,7 @@ RSpec.describe Yaks::Mapper::HasMany do
   }
 
   it 'should map the subresources' do
-    expect(closet_mapper.new(policy: Yaks::DefaultPolicy.new, env: {}).call(closet).subresources).to eql(
+    expect(closet_mapper.call(closet).subresources).to eql(
       "http://foo/shoes" => Yaks::CollectionResource.new(
         type: 'shoe',
         members: [

data/spec/unit/yaks/mapper/has_one_spec.rb

@@ -3,9 +3,9 @@ require 'spec_helper'
 RSpec.describe Yaks::Mapper::HasOne do
   AuthorMapper = Class.new(Yaks::Mapper) { attributes :name }
 
+  subject(:has_one)  { described_class.new(:author, mapper, 'http://rel', Yaks::Undefined) }
   let(:name)     { 'William S. Burroughs' }
   let(:mapper)   { AuthorMapper }
-  let(:has_one)  { described_class.new(:author, mapper, 'http://rel', Yaks::Undefined) }
   let(:author)   { double(:name => name) }
   let(:policy)   {
     double(
@@ -16,6 +16,8 @@ RSpec.describe Yaks::Mapper::HasOne do
   }
   let(:context) {{policy: policy, env: {}}}
 
+  its(:singular_name) { should eq 'author' }
+
   it 'should map to a single Resource' do
     expect(has_one.map_resource(author, context)).to eq Yaks::Resource.new(type: 'author', attributes: {name: name})
   end

data/spec/unit/yaks/mapper/link_spec.rb

@@ -1,6 +1,8 @@
 require 'spec_helper'
 
 RSpec.describe Yaks::Mapper::Link do
+  include_context 'yaks context'
+
   subject(:link) { described_class.new(rel, template, options) }
 
   let(:rel)      { :next }
@@ -11,8 +13,6 @@ RSpec.describe Yaks::Mapper::Link do
   its(:uri_template) { should eq URITemplate.new(template) }
   its(:expand?) { should be true }
 
-  let(:policy)            { Yaks::DefaultPolicy.new }
-  let(:context)           { { policy: policy, env: {} } }
 
   describe '#rel?' do
     it 'should return true if the relation matches' do
@@ -81,11 +81,11 @@ RSpec.describe Yaks::Mapper::Link do
 
     its(:rel) { should eq :next }
 
-    let(:object) { Struct.new(:x,:y).new(3,4) }
+    let(:object) { Struct.new(:x, :y, :returns_nil).new(3, 4, nil) }
 
     let(:mapper) do
-      Yaks::Mapper.new(context).tap do |mapper|
-        mapper.call(object)
+      Yaks::Mapper.new(yaks_context).tap do |mapper|
+        mapper.call(object) # set @object
       end
     end
 
@@ -152,6 +152,13 @@ RSpec.describe Yaks::Mapper::Link do
       end
     end
 
+    context 'with a link generation method that returns nil' do
+      let(:template) { :returns_nil }
+
+      it 'should return nil' do
+        expect(resource_link).to be_nil
+      end
+    end
   end
 
 end

data/spec/unit/yaks/mapper_spec.rb

@@ -1,16 +1,17 @@
 require 'spec_helper'
 
 RSpec.describe Yaks::Mapper do
-  subject(:mapper)   { mapper_class.new(context) }
+  include_context 'yaks context'
+
+  subject(:mapper)   { mapper_class.new(yaks_context) }
   let(:resource)     { mapper.call(instance) }
 
   let(:mapper_class) { Class.new(Yaks::Mapper) { type 'foo' } }
   let(:instance)     { double(foo: 'hello', bar: 'world') }
-  let(:policy)       { nil }
-  let(:options)      { {} }
-  let(:context) {{policy: policy, env: {}}}
 
-  describe '#map_attributes' do
+  its(:env) { should equal rack_env }
+
+  context 'with attributes' do
     before do
       mapper_class.attributes :foo, :bar
     end
@@ -38,7 +39,7 @@ RSpec.describe Yaks::Mapper do
     end
   end
 
-  describe '#map_links' do
+  context 'with links' do
     before do
       mapper_class.link :profile, 'http://foo/bar'
     end
@@ -73,7 +74,7 @@ RSpec.describe Yaks::Mapper do
     end
   end
 
-  describe '#map_subresources' do
+  context 'with subresources' do
     let(:instance)      { double(widget: widget) }
     let(:widget)        { double(type: 'super_widget') }
     let(:widget_mapper) { Class.new(Yaks::Mapper) { type 'widget' } }
@@ -150,25 +151,23 @@ RSpec.describe Yaks::Mapper do
     end
   end
 
-  describe '#load_attributes' do
-    context 'when the mapper implements a method with the attribute name' do
-      before do
-        mapper_class.class_eval do
-          attributes :fooattr, :bar
+  context 'when the mapper implements a method with the attribute name' do
+    before do
+      mapper_class.class_eval do
+        attributes :fooattr, :bar
 
-          def fooattr
-            "#{object.foo} my friend"
-          end
+        def fooattr
+          "#{object.foo} my friend"
         end
       end
+    end
 
-      it 'should get the attribute from the mapper' do
-        expect(resource.attributes).to eq(fooattr: 'hello my friend', bar: 'world')
-      end
+    it 'should get the attribute from the mapper' do
+      expect(resource.attributes).to eq(fooattr: 'hello my friend', bar: 'world')
     end
   end
 
-  describe '#call' do
+  context 'with a nil subject' do
     it 'should return a NullResource when the subject is nil' do
       expect(mapper.call(nil)).to be_a Yaks::NullResource
     end

data/spec/unit/yaks/null_resource_spec.rb

@@ -0,0 +1,32 @@
+require 'spec_helper'
+
+RSpec.describe Yaks::NullResource do
+  subject(:null_resource) { described_class.new }
+
+  its(:attributes)     { should eq Hash[] }
+  its(:links)          { should eq [] }
+  its(:subresources)   { should eq Hash[] }
+  its(:collection?)    { should be false }
+  its(:null_resource?) { should be true }
+
+  it { should respond_to :[] }
+
+  its(:type) { should be_nil }
+
+  describe '#each' do
+    its(:each)         { should be_a Enumerator }
+
+    it 'should not yield anything' do
+      null_resource.each { fail }
+    end
+  end
+
+  it 'should contain nothing' do
+    expect( null_resource[:key] ).to be_nil
+  end
+
+  context 'when a collection' do
+    subject(:null_resource) { described_class.new( collection: true ) }
+    its(:collection?) { should be true }
+  end
+end

data/spec/unit/yaks/primitivize_spec.rb

@@ -0,0 +1,77 @@
+require 'spec_helper'
+
+RSpec.describe Yaks::Primitivize do
+  subject(:primitivizer) { described_class.create }
+
+  describe '.create' do
+    it 'should map String, true, false, nil, numbers to themselves' do
+      [
+        'hello',
+        true,
+        false,
+        nil,
+        100,
+        99.99,
+        -95.33333
+      ].each do |object|
+        expect(primitivizer.call(object)).to eql object
+      end
+    end
+
+    it 'should stringify symbols' do
+      expect(primitivizer.call(:foo)).to eql 'foo'
+    end
+
+    it 'should recursively handle hashes' do
+      expect(primitivizer.call(
+          :foo => {:wassup => :friends, 123 => '456'}
+      )).to eql('foo' => {'wassup' => 'friends', 123 => '456'})
+    end
+
+    it 'should handle arrays recursively' do
+      expect(primitivizer.call(
+          [:foo, [:wassup, :friends], 123, '456']
+      )).to eql( ['foo', ['wassup', 'friends'], 123, '456'] )
+    end
+  end
+
+  describe '#call' do
+    require 'ostruct'
+
+    let(:funny_object) {
+      OpenStruct.new('a' => 'b')
+    }
+
+    it 'should raise an error when passed an unkown type' do
+      def funny_object.inspect
+        "I am funny"
+      end
+
+      expect { primitivizer.call(funny_object) }.to raise_error "don't know how to turn OpenStruct (I am funny) into a primitive"
+    end
+
+    context 'with custom mapping' do
+      require 'matrix'
+
+      let(:primitivizer) do
+        described_class.new.tap do |p|
+          p.map Vector do |vec|
+            vec.map do |i|
+              call(i)
+            end.to_a
+          end
+
+          p.map Symbol do |sym|
+            sym.to_s.length
+          end
+        end
+      end
+
+      it 'should evaluate in the context of primitivize' do
+        expect( primitivizer.call( Vector[:foo, :baxxx, :bazz] ) ).to eql( [3, 5, 4] )
+      end
+    end
+
+
+  end
+end

data/spec/unit/yaks/resource/link_spec.rb

@@ -0,0 +1,21 @@
+require 'spec_helper'
+
+RSpec.describe Yaks::Resource::Link do
+  subject(:link) { described_class.new(rel, uri, options) }
+  let(:rel)      { :foo_rel }
+  let(:uri)      { 'http://api.example.org/rel/foo' }
+  let(:options)  { {name: 'jimmy', title: 'mr. spectacular' } }
+
+  its(:rel)     { should eql :foo_rel }
+  its(:uri)     { should eql 'http://api.example.org/rel/foo' }
+  its(:options) { should eql(name: 'jimmy', title: 'mr. spectacular') }
+
+  its(:name)       { should eql('jimmy') }
+  its(:title)      { should eql('mr. spectacular') }
+  its(:templated?) { should be false }
+
+  context 'with explicit templated option' do
+    let(:options) { super().merge(templated: true) }
+    its(:templated?) { should be true }
+  end
+end

data/spec/unit/yaks/resource_spec.rb

@@ -4,10 +4,13 @@ RSpec.describe Yaks::Resource do
   subject(:resource) { described_class.new(init_opts) }
   let(:init_opts) { {} }
 
-  its(:type)         { should be_nil }
-  its(:attributes)   { should eql({}) }
-  its(:links)        { should eql [] }
-  its(:subresources) { should eql({}) }
+  its(:type)           { should be_nil }
+  its(:attributes)     { should eql({}) }
+  its(:links)          { should eql [] }
+  its(:subresources)   { should eql({}) }
+  its(:self_link)      { should be_nil }
+  its(:null_resource?) { should be false }
+  its(:collection?)    { should be false }
 
   context 'with a type' do
     let(:init_opts) { { type: 'post' } }
@@ -23,16 +26,32 @@ RSpec.describe Yaks::Resource do
   end
 
   context 'with links' do
-    let(:init_opts) { { links: [Yaks::Resource::Link.new(:self, '/foo/bar', {})] } }
-    its(:links) { should eql [Yaks::Resource::Link.new(:self, '/foo/bar', {})] }
+    let(:init_opts) {
+      {
+        links: [
+          Yaks::Resource::Link.new(:profile, '/foo/bar/profile', {}),
+          Yaks::Resource::Link.new(:self, '/foo/bar', {})
+        ]
+      }
+    }
+    its(:links) { should eql [
+        Yaks::Resource::Link.new(:profile, '/foo/bar/profile', {}),
+        Yaks::Resource::Link.new(:self, '/foo/bar', {})
+      ]
+    }
+
+    its(:self_link) { should eql Yaks::Resource::Link.new(:self, '/foo/bar', {}) }
   end
 
   context 'with subresources' do
     let(:init_opts) { { subresources: { 'comments' => [Yaks::Resource.new(type: 'comment')] } } }
     its(:subresources) { should eql 'comments' => [Yaks::Resource.new(type: 'comment')]  }
+
+    it 'should return an enumerator for #each' do
+      expect(resource.each.with_index.to_a).to eq  [ [resource, 0] ]
+    end
   end
 
-  its(:collection?) { should equal false }
 
   it 'should act as a collection of one' do
     expect(resource.each.to_a).to eql [resource]

data/spec/unit/yaks/serializer/hal_spec.rb

@@ -3,7 +3,7 @@ require 'spec_helper'
 RSpec.describe Yaks::Serializer::Hal do
   include_context 'plant collection resource'
 
-  subject { Yaks::Primitivize.create.call(described_class.new(resource).serialize) }
+  subject { Yaks::Primitivize.create.call(described_class.new.call(resource)) }
 
   it { should eq(load_json_fixture('hal_plant_collection')) }
 end

metadata

@@ -1,125 +1,125 @@
 --- !ruby/object:Gem::Specification
 name: yaks
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors:
 - Arne Brasseur
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-18 00:00:00.000000000 Z
+date: 2014-06-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: inflection
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
 - !ruby/object:Gem::Dependency
   name: concord
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 0.1.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 0.1.4
 - !ruby/object:Gem::Dependency
   name: uri_template
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 0.6.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 0.6.0
 - !ruby/object:Gem::Dependency
   name: rack-accept
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 0.4.5
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 0.4.5
 - !ruby/object:Gem::Dependency
   name: virtus
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '2.99'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '2.99'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: mutant-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
@@ -140,28 +140,28 @@ dependencies:
   name: rspec-its
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: benchmark-ips
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 description: Serialize to hypermedia. HAL, JSON-API, etc.
@@ -172,10 +172,12 @@ extensions: []
 extra_rdoc_files:
 - README.md
 files:
-- .gitignore
-- .travis.yml
+- ".gitignore"
+- ".travis.yml"
+- ADDING_FORMATS.md
 - CHANGELOG.md
 - Gemfile
+- IDENTIFIERS.md
 - LICENSE
 - README.md
 - Rakefile
@@ -239,6 +241,9 @@ files:
 - spec/unit/yaks/mapper/has_one_spec.rb
 - spec/unit/yaks/mapper/link_spec.rb
 - spec/unit/yaks/mapper_spec.rb
+- spec/unit/yaks/null_resource_spec.rb
+- spec/unit/yaks/primitivize_spec.rb
+- spec/unit/yaks/resource/link_spec.rb
 - spec/unit/yaks/resource_spec.rb
 - spec/unit/yaks/serializer/hal_spec.rb
 - spec/unit/yaks/serializer_spec.rb
@@ -256,12 +261,12 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
@@ -301,6 +306,9 @@ test_files:
 - spec/unit/yaks/mapper/has_one_spec.rb
 - spec/unit/yaks/mapper/link_spec.rb
 - spec/unit/yaks/mapper_spec.rb
+- spec/unit/yaks/null_resource_spec.rb
+- spec/unit/yaks/primitivize_spec.rb
+- spec/unit/yaks/resource/link_spec.rb
 - spec/unit/yaks/resource_spec.rb
 - spec/unit/yaks/serializer/hal_spec.rb
 - spec/unit/yaks/serializer_spec.rb