yaks 0.8.2 → 0.8.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2011212cb9c579cebb6ee58228407bdfde224829
-  data.tar.gz: 96d967888e80337c38850db63923bac9a74446e9
+  metadata.gz: a609ab5341e17172a098a296e8935d9abf4fa995
+  data.tar.gz: 44f4ef2d6d7786bf09261b352ed9e253064ff31e
 SHA512:
-  metadata.gz: f6aa331742aabedbf57d46182d72029664f385af6d844bc92b1180e3aa8d0e956782deab1d2406ef8cebac36dbbea57189675a6d558d992dae6f37fd1bf12ad6
-  data.tar.gz: c53bec9f2219b58e7f2d6cd16b0966ec1ceeadc9507556c21569746e753e43fa6e65e7bd099f2b6cbe6d5943476824eea28ec6118beeffbef1665e5bb210cb9e
+  metadata.gz: f65c4f9d62853543fc92fbe58fc9a3c4b057eac27473a951d8cfe38edf19cf0af461bd9e047e20cbce47ab771ded553b859937e6c8dff7e1a25aa2f1101f8a18
+  data.tar.gz: be7d5c1edcc4e745a25897deae315000d1bdff1713b8a6d61876f36d62d4dc866792a5f362957c7218e64e7a9c346bec38bd064e7297cfa33be26702b451bd33

data/README.md

@@ -2,11 +2,13 @@
 [![Build Status](https://secure.travis-ci.org/plexus/yaks.png?branch=master)][travis]
 [![Dependency Status](https://gemnasium.com/plexus/yaks.png)][gemnasium]
 [![Code Climate](https://codeclimate.com/github/plexus/yaks.png)][codeclimate]
+[![Gitter](https://badges.gitter.im/Join Chat.svg)][gitter]
 
 [gem]: https://rubygems.org/gems/yaks
 [travis]: https://travis-ci.org/plexus/yaks
 [gemnasium]: https://gemnasium.com/plexus/yaks
 [codeclimate]: https://codeclimate.com/github/plexus/yaks
+[gitter]: https://gitter.im/plexus/yaks?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
 
 # Yaks
 
@@ -22,6 +24,7 @@ requested. These formats are presently supported:
 * Collection+JSON
 * HTML
 * HALO
+* Transit
 
 ## State of Development
 
@@ -309,9 +312,15 @@ If `env` contains a `HTTP_ACCEPT` key (Rack's way of representing the
 `Accept` header), Yaks will return the format that most closely
 matches what was requested.
 
+<a id="namespace"></a>
+
 ## Namespace
 
-Yaks by default will find your mappers for you if they follow the naming convention of appending 'Mapper' to the model class name. This (and all other "conventions") can be easily redefined though, see below. If you have your mappers inside a module, use `namespace`.
+Yaks by default will find your mappers for you if they follow the
+naming convention of appending 'Mapper' to the model class name. This
+(and all other "conventions") can be easily redefined though, see the
+<a href="#policy">policy</a> section. If you have your mappers inside a
+module, use `namespace`.
 
 ```ruby
 module API
@@ -327,7 +336,8 @@ yaks = Yaks.new do
 end
 ```
 
-If your namespace contains a `CollectionMapper`, Yaks will use that instead of `Yaks::CollectionMapper`, e.g.
+If your namespace contains a `CollectionMapper`, Yaks will use that
+instead of `Yaks::CollectionMapper`, e.g.
 
 ```ruby
 module API
@@ -339,7 +349,8 @@ module API
 end
 ```
 
-You can also have collection mappers based on the type of members the collection holds, e.g.
+You can also have collection mappers based on the type of members the
+collection holds, e.g.
 
 ```ruby
 module API
@@ -358,12 +369,20 @@ module API
 end
 ```
 
-Yaks will automatically detect and use this collection when serializing an array of `LineItem` objects.
+Yaks will automatically detect and use this collection when
+serializing an array of `LineItem` objects. See <a
+href="#derive_mapper_from_object">derive_mapper_from_object</a> for
+details.
 
 
 ## Custom attribute/link/subresource handling
 
-When inheriting from `Yaks::Mapper`, you can override `map_attributes`, `map_links` and `map_resources` to skip (or augment) above methods, and instead implement your own custom mechanism. These methods take a `Yaks::Resource` instance, and should return an updated resource. They should not alter the resource instance in-place. For example
+When inheriting from `Yaks::Mapper`, you can override
+`map_attributes`, `map_links` and `map_resources` to skip (or augment)
+above methods, and instead implement your own custom mechanism. These
+methods take a `Yaks::Resource` instance, and should return an updated
+resource. They should not alter the resource instance in-place. For
+example
 
 ```ruby
 class ErrorMapper < Yaks::Mapper
@@ -441,6 +460,9 @@ HAL. To stick close to the spec you're best to create your own
 singular types that represent collections, rather than rendering a top
 level CollectionResource.
 
+Yaks also has a derived format called HALO, which is a non-standard
+extension to HAL which includes form elements.
+
 ### HTML
 
 The hypermedia format *par excellence*. Yaks can generate a version of
@@ -511,11 +533,20 @@ class PostMapper < Yaks::Mapper
 end
 ```
 
-Subresources aren't mapped because Collection+JSON doesn't really have that concept.
+Subresources aren't mapped because Collection+JSON doesn't really have
+that concept.
+
+### Transit
+
+There is experimental support for Transit. The transit gem handles
+serialization internally, so there is no intermediate document. The
+`format` step already returns the serialized string.
 
 ## Hooks
 
-It is possible to hook into the Yaks pipeline to perform extra processing steps before, after, or around each step. It also possible to skip a step.
+It is possible to hook into the Yaks pipeline to perform extra
+processing steps before, after, or around each step. It also possible
+to skip a step.
 
 ``` ruby
 yaks = Yaks.new do
@@ -530,6 +561,8 @@ yaks = Yaks.new do
 end
 ```
 
+<a id="policy"></a>
+
 ## Policy over Configuration
 
 It's an old adage in the Ruby/Rails world to have "Convention over Configuration", mostly to derive values that were not given explicitly. Typically based on things having similar names and a 1-1 derivable relationship.
@@ -574,7 +607,89 @@ yaks = Yaks.new do
 end
 ```
 
-<a id="primitivizer">
+<a id="derive_mapper_from_object"></a>
+
+### derive_mapper_from_object
+
+This is called when trying to serialize something and no explicit
+mapper is given. To recap, it's always possible to be explicit, e.g.
+
+```
+yaks.call(widget, mapper: WidgetMapper)
+yaks.call(array_of_widgets, mapper: MyCollectionMapper, item_mapper: WidgetMapper)
+```
+
+If the mapper is left unspecified, Yaks will inspect whatever you pass
+it, and try various constant lookups based on naming. These all happen
+in the configured namespace, which defaults to the Ruby top level.
+
+If the object responds to `to_ary` it is considered a collection. If
+the first object in the collection has a class of `Widget`, and the
+configured namespace is `API`, then these are tried in turn
+
+* `API::WidgetCollectionMapper`
+* `API::CollectionMapper`
+* `Yaks::CollectionMapper`
+
+Note that Yaks can only find a specific collection mapper for a type
+if the collection passed to Yaks contains at least one element. If
+it's important that empty collections are handled by the right mapper
+(e.g. to set a specific `self` or `profile` link), then you have to be
+explicit.
+
+If the object is not a collection, then lookup happens based on the
+class name, and will traverse up the class hierarchy if no suitable
+mapper is found. So for a `class Widget < Thing`, yaks would look for
+
+* `API::WidgetMapper`
+* `API::ThingMapper`
+* `API::ObjectMapper`
+
+If none of these are found an error is raised.
+
+### derive_mapper_from_association
+
+When no mapper is specified for an association, then this method is
+called to find the right mapper, based on the association name. In
+case of `has_many` collections this is the "item mapper", the
+collection mapper is resolved using `derive_mapper_from_object`.
+
+By default the mapper class is derived from the name of the association, e.g.
+
+```
+has_many :widgets #=> WidgetMapper
+has_one :widget   #=> WidgetMapper
+```
+
+It is always possible to explicitly set a mapper.
+
+```
+has_one :widget, mapper: FooMapper
+has_many :widgets, collection_mapper: MyCollectionMapper, mapper: FooMapper
+```
+
+### derive_rel_from_association
+
+Associations have a "rel", an IANA registered identifier or fully
+qualified URI, that specifies how the object relates to the parent
+document.
+
+When configuring Yaks one can set a `rel_template`, that will be used
+to generate these rels if not explicitly given. The `rel` placeholder
+in the template will be substituted with the association name.
+
+``` ruby
+yaks = Yaks.new do
+  rel_template "http://api.example.com/rel/{rel}"
+end
+
+# ... mapper
+
+has_many :widgets #=> rel: "http://api.example.com/rel/widgets"
+has_one :widget #=> rel: "http://api.example.com/rel/widget"
+```
+
+<a id="primitivizer"></a>
 
 ## Primitivizer
 
@@ -603,7 +718,7 @@ end
 Yaks by default "primitivizes" symbols (as strings), and classes that include Enumerable (as arrays).
 
 
-<a id="integration">
+<a id="integration"></a>
 
 ## Integration
 

data/lib/yaks/default_policy.rb

@@ -36,8 +36,16 @@ module Yaks
         end
         CollectionMapper
       else
+        klass = model.class
+        begin
+          name = klass.name.split('::').last
+          return @options[:namespace].const_get(name + 'Mapper')
+        rescue NameError
+          klass = klass.superclass
+          retry if klass
+        end
         name = model.class.name.split('::').last
-        @options[:namespace].const_get(name + 'Mapper')
+        raise "Failed to find a mapper for #{model.inspect}. Did you mean to implement #{name}Mapper?"
       end
     end
 

data/lib/yaks/version.rb

@@ -1,3 +1,3 @@
 module Yaks
-  VERSION = '0.8.2'
+  VERSION = '0.8.3'
 end

data/spec/support/classes_for_policy_testing.rb

@@ -1,11 +1,13 @@
 # Used by Yaks::DefaultPolicy* tests to test various name inference schemes
 
 class SoyMapper ; end
-class Soy ; end
+class Bean ; end
+class Soy < Bean; end
 class Wheat ; end
 
 module MyMappers
   class SoyMapper ; end
+  class BeanMapper ; end
 end
 
 class SoyCollectionMapper ; end
@@ -13,6 +15,12 @@ class SoyCollectionMapper ; end
 module Namespace
   module Nested
     class Rye ; end
+    class Mung < Bean
+      alias inspect to_s # on 1.9 inspect calls to_s
+      def to_s
+        "mungbean"
+      end
+    end
   end
 
   class RyeMapper ; end

data/spec/unit/yaks/default_policy/derive_mapper_from_object_spec.rb

@@ -75,4 +75,20 @@ RSpec.describe Yaks::DefaultPolicy, '#derive_mapper_from_object' do
     end
   end
 
+  context 'when a mapper exists for a superclass' do
+    let(:options) { {namespace: MyMappers} }
+
+    it 'should use the superclass mapper' do
+      expect(policy.derive_mapper_from_object(Namespace::Nested::Mung.new)).to be(MyMappers::BeanMapper)
+    end
+  end
+
+  context 'when no mapper is found' do
+    it 'should give a nice message' do
+      expect {
+        policy.derive_mapper_from_object(Namespace::Nested::Mung.new)
+      }.to raise_error /Failed to find a mapper for #<Namespace::Nested::Mung:0x\h+>. Did you mean to implement MungMapper\?/
+    end
+  end
+
 end

data/yaks.gemspec

@@ -34,8 +34,8 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency 'bogus'
   gem.add_development_dependency 'rake'
   gem.add_development_dependency 'yard'
-  gem.add_development_dependency 'mutant-rspec'
-  gem.add_development_dependency 'mutant'
+  gem.add_development_dependency 'mutant-rspec' if RUBY_VERSION > '1.9'
+  gem.add_development_dependency 'mutant'       if RUBY_VERSION > '1.9'
   gem.add_development_dependency 'rspec-its'
   gem.add_development_dependency 'benchmark-ips'
   gem.add_development_dependency 'yaks-html'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yaks
 version: !ruby/object:Gem::Version
-  version: 0.8.2
+  version: 0.8.3
 platform: ruby
 authors:
 - Arne Brasseur
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-02 00:00:00.000000000 Z
+date: 2015-03-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: inflection