yaks 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e1351b2c236dc9fb68ff5bbe9c365f7addb38cad
-  data.tar.gz: d8baafb1e55bc4bf5e926e012dac9bd20d7284f8
+  metadata.gz: 8e26f0f65962ea64eee11346ede1401347525188
+  data.tar.gz: 40881b570c5b8145e79a92251a35275b62da9994
 SHA512:
-  metadata.gz: 4f5732d430846954a651d3aff1145cf07610098d23c0ba2b28bfe7626b3e3c2c3c741d6f50d84459360a1986d820f10604d115bd3336ccad6dac2386bf808142
-  data.tar.gz: 7ce7ea4c6bdf3c0e0fc2ae11ecee61813c4be3b8eefe01316153ba427d6522496f2d92e3efcbf2c29f60bea9db3a93b158caf4d667472835438c284ae14df08f
+  metadata.gz: 9b4370186b9d44d56404df20e65bfb58bedd666b6bd5be2cb78684d1022ed74bb2df1a01c6381dc743c9769cadbdc3fcff441d52298108137a4fe60f873c2dab
+  data.tar.gz: 340ea7d369824f9ac7d0ea98e0995c0d4192b63c6a66f9faff2033b78b7b281d494c9044508c7a9bdd085e8a20ffb76b89a54716aef447c8824a27d3080a37ff

data/README.md

@@ -1,21 +1,21 @@
 [![Gem Version](https://badge.fury.io/rb/yaks.png)][gem]
 [![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
 
-![](logo.png)
+<img align="left" src="https://raw.githubusercontent.com/plexus/yaks/master/logo.png">
 
 The library that understands hypermedia.
 
+**If you use Yaks please help out by filling out the [Yaks Users Survey](https://docs.google.com/forms/d/1sZB03Vf32igmNmJ7RP8mo8H4VZHcVIpSrUSbvx2xD8s/viewform)**
+
 Yaks takes your data and transforms it into hypermedia formats such as
 HAL, JSON-API, or HTML. It allows you to build APIs that are
 discoverable and browsable. It is built from the ground up around
@@ -33,21 +33,48 @@ requested. These formats are presently supported:
 * HALO
 * Transit
 
-## State of Development
-
-This library came into existence because we at
-[Ticketsolve](http://www.ticketsolve.com) wanted to build a rich
-hypermedia API, and were dissatisfied with any of the existing Ruby
-solutions at the time (November 2013).
+## Table of Contents
+
+- [State of Development](#user-content-state-of-development)
+- [Concepts](#user-content-concepts)
+- [Mappers](#user-content-mappers)
+  - [Attributes](#user-content-attributes)
+  - [Forms](#user-content-forms)
+    - [Filtering](#user-content-filtering)
+  - [Links](#user-content-links)
+  - [Associations](#user-content-associations)
+- [Calling Yaks](#user-content-calling-yaks)
+  - [Rack env](#user-content-rack-env)
+- [Namespace](#user-content-namespace)
+- [Custom attribute/link/subresource handling](#user-content-custom-attributelinksubresource-handling)
+- [Resources, Formatters, Serializers](#user-content-resources-formatters-serializers)
+- [Formats](#user-content-formats)
+  - [HAL](#user-content-hal)
+  - [HTML](#user-content-html)
+  - [JSON-API](#user-content-json-api)
+  - [Collection+JSON](#user-content-collection-json)
+  - [Transit](#user-content-transit)
+- [Hooks](#user-content-hooks)
+- [Policy over Configuration](#user-content-policy-over-configuration)
+  - [derive_mapper_from_object](#user-content-derive_mapper_from_object)
+  - [derive_mapper_from_association](#user-content-derive_mapper_from_association)
+  - [derive_rel_from_association](#user-content-derive_rel_from_association)
+- [Primitivizer](#user-content-primitivizer)
+- [Integration](#user-content-integration)
+- [Real World Usage](#user-content-real-world-usage)
+- [Demo](#user-content-demo)
+- [Cookbook](#user-content-cookbook)
+- [Standards Based](#user-content-standards-based)
+- [How to contribute](#user-content-how-to-contribute)
+- [License](#user-content-license)
 
-We are still actively expanding our API, and with that Yaks continues
-to grow and improve. The aim is to create *the reference* for
-supporting hypermedia formats in Ruby.
+## State of Development
 
-Yaks can be used in production today, as we do, but until 1.0 is
-released there will regularly be breaking changes, as we figure out
-the best way to do things. These are all documented clearly in the
-[changelog](/CHANGELOG.md).
+Recent focus has been on stabilizing the core classes, improving
+format support, and increasing test (mutation) coverage. We are
+committed to a stable public API and semantic version. On the 0.x line
+the minor version is bumped when non-backwards compatible changes are
+introduced. After 1.x regular semver conventions will be used.
 
 ## Concepts
 
@@ -59,13 +86,13 @@ yaks = Yaks.new do
   default_format :hal
   rel_template 'http://api.example.com/rels/{rel}'
   format_options(:hal, plural_links: [:copyright])
-  namespace ::MyAPI
+  mapper_namespace ::MyAPI
   json_serializer do |data|
-    MultiJson.dump(data)
+    JSON.dump(data)
   end
 end
 
-yaks.call(data) # => '{"foo": "bar", "_links": { ... }}'
+yaks.call(product)
 ```
 
 Yaks performs this serialization in three steps
@@ -115,12 +142,12 @@ yaks = Yaks.new do
   format_options(:hal, plural_links: [:copyright])
 end
 
-yaks.call(post, mapper: PostMapper, format: :hal)
+yaks.call(post, mapper: ::PostMapper, format: :hal)
 ```
 
 ### Attributes
 
-Use the `attributes` DSL method to specify which attributes of your model you want to expose, as in the example above. You can override the `load_attribute` method to change how attributes are fetched from the model.
+Use the `attribute` or `attributes` DSL methods to specify which attributes of your model you want to expose, as in the example above. You can override the `load_attribute` method to change how attributes are fetched from the model.
 
 For example, if you are representing data that is stored in a Hash, you could do
 
@@ -134,12 +161,14 @@ class PostHashMapper < Yaks::Mapper
   end
 end
 ```
-
-The default implementation will first try to find a matching method for an attribute on the mapper itself, and will then fall back to calling the actual model. So you can add extra 'virtual' attributes like so :
+The `attribute` method may also take a block that will be called with the context of the mapper instance. The default implementation will use the block if provided, otherwise it will first try to find a matching method for an attribute on the mapper itself, and will then fall back to calling the actual model. So you can add extra 'virtual' attributes like so :
 
 ```ruby
 class CommentMapper < Yaks::Mapper
-  attributes :id, :body, :date
+  attributes :body, :date
+  attribute :id do
+    "Id-#{object.id}"
+  end
 
   def date
     object.created_at.strftime("at %I:%M%p")
@@ -176,7 +205,7 @@ rendering of forms, dynamic form sections, ...
 You can override `#attributes`, or `#associations`.
 
 ```ruby
-class SongMapper
+class SongMapper < Yaks::Mapper
   attributes :title, :duration, :lyrics
 
   has_one :artist
@@ -257,7 +286,7 @@ confirming an order, the previously held cart is no longer valid, you
 could use the IANA standard `invalidates` rel to communicate this.
 
 ``` ruby
-class OrderMapper < BaseMapper
+class OrderMapper < Yaks::Mapper
   link :invalidates, '/api/cart', if: ->{ env['api.invalidate_cart'] }
 end
 ```
@@ -296,10 +325,7 @@ it the data to be serialized, plus options.
 When serializing, Yaks lets you pass in an `env` hash, which will be made available to all mappers.
 
 ```ruby
-yaks = Yaks.new
-yaks.call(foo, env: my_env)
-
-class FooMapper
+class FooMapper < Yaks::Mapper
   attributes :bar
 
   def bar
@@ -308,6 +334,9 @@ class FooMapper
     end
   end
 end
+
+yaks = Yaks.new
+yaks.call(foo, env: my_env)
 ```
 
 The env hash will be available to all mappers, so you can use this to
@@ -327,7 +356,7 @@ 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`.
+module, use `mapper_namespace`.
 
 ```ruby
 module API
@@ -339,7 +368,7 @@ module API
 end
 
 yaks = Yaks.new do
-  namespace API::Mappers
+  mapper_namespace API::Mappers
 end
 ```
 
@@ -498,7 +527,9 @@ If you would like to see better JSON-API support, get in touch. We
 might be able to work something out.
 
 ```ruby
-default_format :json_api
+Yaks.new do
+  default_format :json_api
+end
 ```
 
 JSON-API has no concept of outbound links, so these will not be
@@ -506,8 +537,8 @@ rendered. Instead the key will be inferred from the mapper class name
 by default. This can be changed per mapper:
 
 ```ruby
-class AnimalMapper
-  key :pet
+class AnimalMapper < Yaks::Mapper
+  type :pet
 end
 ```
 
@@ -528,10 +559,12 @@ option can be used. It will map the specified form to a CJ template. Please
 notice that CJ only allows one template per representation.
 
 ```ruby
-default_format :collection_json
+Yaks.new do
+  default_format :collection_json
 
-collection_json = Yaks.new do
-  format_options :collection_json, template: :my_template_form
+  collection_json = Yaks.new do
+    format_options :collection_json, template: :my_template_form
+  end
 end
 
 class PostMapper < Yaks::Mapper
@@ -589,10 +622,20 @@ In Yaks whenever missing values need to be inferred, like finding an unspecified
 
 ```ruby
 yaks = Yaks.new do
+  mapper_for Post, SpecialMapper
+
   derive_mapper_from_object do |model|
     # ...
   end
 
+  derive_mapper_from_collection do |collection|
+    # ...
+  end
+
+  derive_mapper_from_item do |model|
+    # ...
+  end
+
   derive_type_from_mapper_class do |mapper_class|
     # ...
   end
@@ -607,15 +650,18 @@ yaks = Yaks.new do
 end
 ```
 
+Note that within these blocks, you may call `super()` which would call
+the default implementation.
+
 You can also subclass or create from scratch your own policy class
 
 ```ruby
-class MyPolicy < DefaultPolicy
+class MyPolicy < Yaks::DefaultPolicy
   #...
 end
 
 yaks = Yaks.new do
-  policy MyPolicy
+  policy_class MyPolicy
 end
 ```
 
@@ -632,11 +678,35 @@ yaks.call(array_of_widgets, mapper: MyCollectionMapper, item_mapper: WidgetMappe
 ```
 
 If the mapper is left unspecified, Yaks will inspect whatever you pass
-it, and try various constant lookups based on naming. These all happen
+it. First it will test the given object against the mappings defined using `mapper_for`.
+If no mapper is found, it will call `derive_mapper_from_item` or `derive_mapper_from_collection`
+depending on whether the given object is a collection or not. If the object responds
+to `to_ary` it is considered a collection.
+
+### mapper_for
+
+This method allows you to define a one-to-one mapping between a mapping rule and a mapper class.
+During the lookup, Yaks will check if any mapping rule matches the given object using the `#===`
+operator.
+
+Here are a few examples on how to use it:
+```ruby
+yaks = Yaks.new do
+  mapper_for(:home, HomeMapper)
+  mapper_for(Post, SpecialMapper)
+  mapper_for(->(author) { author.respond_to?(:name) && author.name == 'doh' }, AuthorMapper)
+end
+
+yaks.call(:home) # would map using HomeMapper
+yaks.call(Post.new) # would map using PostMapper
+yaks.call(Author.new(name: 'doh')) # would map using AuthorMapper
+```
+
+### derive_mapper_from_collection
+This method will 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
+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`
@@ -649,13 +719,35 @@ 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
+### derive_mapper_from_item
+
+When using this method, the lookup happens based on the class name,
+and will traverse up the class hierarchy in the configured namespace if
+no suitable mapper is found. Take the following
+code:
+```ruby
+module Stuff
+  class Thing ; end
+  class Widget < Thing ; end
+end
+```
+The lookup we'll be done as followed.
+
+* If the `namespace` option is set (to `Mappers` for example):
+ * `Mappers::Stuff::WidgetMapper`
+ * `Mappers::Stuff::ThingMapper`
+ * `Mappers::Stuff::ObjectMapper`
+ * `Mappers::Stuff::BasicObjectMapper`
+ * `Mappers::WidgetMapper`
+ * `Mappers::ThingMapper`
 
-* `API::WidgetMapper`
-* `API::ThingMapper`
-* `API::ObjectMapper`
+* If the `namespace` option is not set:
+ * `Stuff::WidgetMapper`
+ * `Stuff::ThingMapper`
+ * `Stuff::ObjectMapper`
+ * `Stuff::BasicObjectMapper`
+ * `WidgetMapper`
+ * `ThingMapper`
 
 If none of these are found an error is raised.
 
@@ -695,10 +787,13 @@ yaks = Yaks.new do
   rel_template "http://api.example.com/rel/{rel}"
 end
 
-# ... mapper
+class MyMapper < Yaks::Mapper
+  # rel: "http://api.example.com/rel/widgets"
+  has_many :widgets
 
-has_many :widgets #=> rel: "http://api.example.com/rel/widgets"
-has_one :widget #=> rel: "http://api.example.com/rel/widget"
+  # rel: "http://api.example.com/rel/widget"
+  has_one :widget
+end
 ```
 
 <a id="primitivizer"></a>
@@ -752,10 +847,10 @@ Yaks::Format.all.each do |format|
 end
 
 # one time Yaks configuration
-yaks = Yaks.new {...}
+yaks = Yaks.new
 
 # on each request
-runner = yaks.runner(object, env: rack_env)
+runner = yaks.runner(post, env: rack_env)
 format = runner.format_name
 output = runner.call
 ```
@@ -763,12 +858,19 @@ output = runner.call
 
 ## Real World Usage
 
-Yaks is used in production by [Ticketsolve](http://www.ticketsolve.com/). You can find an example API endpoint [here](http://leicestersquaretheatre.ticketsolve.com/api).
+Yaks is used in production by
+
+* [Ticketsolve](http://www.ticketsolve.com/). You can find an example API endpoint [here](http://leicestersquaretheatre.ticketsolve.com/api).
+* Advertile Mobile for their product AppBounty (internal API)
 
 ## Demo
 
 You can find an outdated example app at [Yakports](https://github.com/plexus/yakports), or browse the HAL api directly using the [HAL browser](http://yaks-airports.herokuapp.com/browser.html).
 
+## Cookbook
+
+See the [cookbook](COOKBOOK.md) for some usage examples taking from a real world app.
+
 ## Standards Based
 
 Yaks is based on internet standards, including
@@ -781,7 +883,7 @@ Yaks is based on internet standards, including
 
 ## How to contribute
 
-Run the tests, the examples, try it with your own stuff and leave your impressions in the issues. Or discuss on [API-craft](https://groups.google.com/d/forum/api-craft).
+Run the tests, the examples, try it with your own stuff and leave your impressions in the issues.
 
 To fix a bug
 

data/Rakefile

@@ -58,8 +58,6 @@ task :mutant_chunked do
     # >> Yaks::Format::Transit::ReadHandler
     # >> Yaks::Format::Transit::WriteHandler
     # >> Yaks::HTML5Forms
-    # >> Yaks::Identifier
-    # >> Yaks::Identifier::LinkRelation
     # >> Yaks::IllegalStateError
     # >> Yaks::Mapper
     # >> Yaks::Mapper::Association
@@ -85,7 +83,7 @@ task :mutant_chunked do
     # Yaks::Resource::Form::Field,
     # Yaks::Resource::Form::Field::Option,
     # Yaks::Resource::Form::Fieldset,
-    #Yaks::Resource::Link,
+    # Yaks::Resource::Link,
     Yaks::Resource::HasFields,
     # >> Yaks::Runner
     # >> Yaks::RuntimeError

data/ataru_setup.rb

@@ -0,0 +1,72 @@
+# "Require your project source code, with the correct path"
+
+require "yaks"
+require "hamster"
+
+Post = Struct.new(:id, :title, :author, :comments)
+Author = Struct.new(:name)
+
+module MyAPI
+  Product = Struct.new(:id, :label)
+
+  class ProductMapper < Yaks::Mapper
+    attributes :id, :label
+  end
+end
+
+class AuthorMapper < Yaks::Mapper
+end
+
+class CommentMapper < Yaks::Mapper
+end
+
+class PostMapper < Yaks::Mapper
+  link :self, '/api/posts/{id}'
+
+  attributes :id, :title
+
+  has_one :author
+  has_many :comments
+end
+
+class HomeMapper < Yaks::Mapper; end
+
+class SpecialMapper < Yaks::Mapper; end
+
+module Setup
+  def setup
+    # Do some nice setup that is run before every snippet
+    # If you'd like to use instance variables define them here, e.g
+    #  @important_variable_i_will_use_in_my_code_snippets = true
+  end
+
+  def teardown
+    # Do some cleanup that is run after every snippet
+  end
+
+  # If you like local variables you can define methods, e.g
+  # def number_of_wishes
+  #  101
+  # end
+
+  def my_env
+    {'something' => true}
+  end
+  alias_method :rack_env, :my_env
+
+  def post
+    Post.new(7, "Yaks is Al Dente", nil, [])
+  end
+  alias_method :foo, :post
+
+  def product
+    MyAPI::Product.new(42, "Shiny thing")
+  end
+
+  # # Tell your web framework about the supported formats
+  # Yaks::Format.all.each do |format|
+  #   mime_type format.format_name, format.media_type
+  # end
+  def mime_type(*_args)
+  end
+end