yaks 0.8.1 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2e248248443677439e3a74cc66a1dc5a71977094
-  data.tar.gz: b8fb999606b2675d964eb93fa00c4e2f447741db
+  metadata.gz: 2011212cb9c579cebb6ee58228407bdfde224829
+  data.tar.gz: 96d967888e80337c38850db63923bac9a74446e9
 SHA512:
-  metadata.gz: 81021221514f434b2e412f7b1cd894d0fe3e134a2adc5f4dfae727473bfaca130372ca7409b2a795aa47e626ee700068351d59587972cd2ff4ebdcc6b44f2d31
-  data.tar.gz: bef8b36b5b9815bd4275fd2ce2a182a4c191f718ba1967ba91338b9f133fdb0b6c969e63d4040177f6d81c88192164ddad8a7c73064a96edf6163d2fc3a62458
+  metadata.gz: f6aa331742aabedbf57d46182d72029664f385af6d844bc92b1180e3aa8d0e956782deab1d2406ef8cebac36dbbea57189675a6d558d992dae6f37fd1bf12ad6
+  data.tar.gz: c53bec9f2219b58e7f2d6cd16b0966ec1ceeadc9507556c21569746e753e43fa6e65e7bd099f2b6cbe6d5943476824eea28ec6118beeffbef1665e5bb210cb9e

data/README.md

@@ -37,8 +37,7 @@ supporting hypermedia formats in Ruby.
 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). At this point we recommend locking to an
-exact version number.
+[changelog](/CHANGELOG.md).
 
 ## Concepts
 
@@ -301,9 +300,14 @@ class FooMapper
 end
 ```
 
-The env hash will be available to all mappers, so you can use this to pass around context. In particular context related to the current HTTP request, e.g. the current logged in user, which is why the recommended use is to pass in the Rack environment.
+The env hash will be available to all mappers, so you can use this to
+pass around context. In particular context related to the current HTTP
+request, e.g. the current logged in user, which is why the recommended
+use is to pass in the Rack environment.
 
-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.
+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.
 
 ## Namespace
 
@@ -385,23 +389,43 @@ class ErrorMapper < Yaks::Mapper
 end
 ```
 
-## Resources and Serializers
+## Resources, Formatters, Serializers
 
-Yaks uses an intermediate "Resource" representation to support multiple output formats. A mapper turns a domain model into a `Yaks::Resource`. A serializer (e.g. `Yaks::Serializer::Hal`) takes the resource and outputs the structure of the target format.
+Yaks uses an intermediate "Resource" representation to support
+multiple output formats. A mapper turns a domain model into a
+`Yaks::Resource`. A formatter (e.g. `Yaks::Format::Hal`) takes
+the resource and outputs the structure of the target format.
 
-Since version 0.4 the recommended API is through `Yaks.new {...}.serialize`. This will give you back a composite value consisting of primitives that have a mapping to JSON, so you can use your favorite JSON encoder to turn this into a character stream.
+Finally a serializer will take this document structure and turn it
+into a string. For JSON documents the intermediate format consists of
+Ruby primitives like arrays and hashes. HTML/XML based formats on the
+other hand return a [Hexp::Node](https://github.com/plexus/hexp).
 
-```ruby
-my_yaks = Yaks.new
-hal = my_yaks.call(model)
-puts JSON.dump(hal)
-```
+For JSON based format there's an extra step between `format` and
+`serialize` called `primitivize`, this way Ruby objects which don't
+have an equivalent in the JSON spec, like `Symbol` or `Date`, can be
+turned into objects that are representable in JSON. See
+[Primitiver](#primitivizer).
+
+## Formats
 
-There are at least a handful of JSON libraries and implementations for Ruby out there, with different trade-offs. Yaks does not impose an opinion on which one to use
+Below follows a brief overview of formats that are available in
+Yaks. The maturity of these formats varies, since we depend on people
+that use a certain format actively to contribute. Implementing formats
+is in generally straightforward, and consists mostly of deciding how
+the attributes, links, forms, of a `Yaks::Resource` should be
+represented. Depending on the format this might be a subject for
+debate. We welcome these discussions, and if your opinion differs from
+what ends up in Yaks, it should be trivial to change these
+representations for your use case.
 
 ### HAL
 
-This is the default. In HAL one decides when building an API which links can only be singular (e.g. self), and which are always represented as an array. Yaks defaults to singular as I've found it to be the most common case. If you want specific links to be plural, then configure their rel href as such.
+This is the default. In HAL one decides when building an API which
+links can only be singular (e.g. self), and which are always
+represented as an array. Yaks defaults to singular as I've found it to
+be the most common case. If you want specific links to be plural, then
+configure their rel href as such.
 
 ```ruby
 hal = Yaks.new do
@@ -409,17 +433,43 @@ hal = Yaks.new do
 end
 ```
 
-CURIEs are not explicitly supported (yet), but it's possible to use them with some effort, see `examples/hal01.rb` for an example.
+CURIEs are not explicitly supported (yet), but it's possible to use
+them with some manual effort.
+
+The line between a singular resource and a collection is fuzzy in
+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.
+
+### HTML
+
+The hypermedia format *par excellence*. Yaks can generate a version of
+your API, including links and forms, that is usable straight from a
+standard web browser. This allows API interactions to be developed and
+tested independent from any client application.
 
-The line between a singular resource and a collection is fuzzy in 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.
+If you let Yaks handle your content type negotiation (i.e. pass it the
+rack env, and honour the content type it detects, see
+[integration](#integration), simply opening a browser and pointing it
+at your API entry point should do the trick.
 
 ### JSON-API
 
+The JSON-API spec has evolved since the Yaks formatter was
+implemented. It is also not the most suitable format for Yaks
+feature-set due to its strong convention-driven nature and weak
+support for hypermedia.
+
+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
 ```
 
-JSON-API has no concept of outbound links, so these will not be rendered. Instead the key will be inferred from the mapper class name by default. This can be changed per mapper:
+JSON-API has no concept of outbound links, so these will not be
+rendered. Instead the key will be inferred from the mapper class name
+by default. This can be changed per mapper:
 
 ```ruby
 class AnimalMapper
@@ -524,7 +574,9 @@ yaks = Yaks.new do
 end
 ```
 
-## Primitives
+<a id="primitivizer">
+
+## Primitivizer
 
 For JSON based formats, the "syntax tree" is merely a structure of Ruby primitives that have a JSON equivalent. If your mappers return non-primitive attribute values, you can define how they should be converted. For example, JSON has no notion of dates. If your mappers return these types as attributes, then Yaks needs to know how to turn these into primitives. To add extra types, use `map_to_primitive`
 
@@ -550,6 +602,38 @@ end
 
 Yaks by default "primitivizes" symbols (as strings), and classes that include Enumerable (as arrays).
 
+
+<a id="integration">
+
+## Integration
+
+It is recommended to let Yaks handle the negotiation of media types,
+so that consumer can request the format they prefer using an `Accept:`
+header. To do this requires two steps: first make sure you pass the
+rack env to Yaks, this way it will detect any `Accept` header and
+honor it. While this is enough to get the correct serialized output,
+it will likely be served up with the wrong `Content-Type` header by
+your web framework.
+
+To fix this, ask Yaks first for the "runner" for a given input, then
+get the media type and serialized resource from the runner.
+
+```ruby
+# Tell your web framework about the supported formats
+Yaks::Format.all.each do |format|
+  mime_type format.format_name, format.media_type
+end
+
+# one time Yaks configuration
+yaks = Yaks.new {...}
+
+# on each request
+runner = yaks.runner(object, env: rack_env)
+format = runner.format_name
+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).

data/lib/yaks/format.rb

@@ -8,6 +8,8 @@ module Yaks
     #   @return [Hash]
     attr_reader :options
 
+    attr_reader :env
+
     def_delegators :resource, :links, :attributes, :subresources
 
     protected :links, :attributes, :subresources, :options
@@ -20,7 +22,8 @@ module Yaks
 
     # @param [Yaks::Resource] resource
     # @return [Hash]
-    def call(resource, _env = {})
+    def call(resource, env = {})
+      @env = env
       serialize_resource(resource)
     end
     alias serialize call

data/lib/yaks/runner.rb

@@ -41,7 +41,7 @@ module Yaks
         Format.by_name(options.fetch(:format) { default_format })
       }
     end
-    memoize :format_class
+    memoize :format_class, freezer: :noop
 
     def steps
       [[ :map, mapper ],
@@ -61,7 +61,7 @@ module Yaks
     def formatter
       format_class.new(format_options_hash[format_name])
     end
-    memoize :formatter
+    memoize :formatter, freezer: :noop
 
     def primitivizer
       proc do |input|
@@ -77,7 +77,7 @@ module Yaks
     def serializer
       serializers.fetch(format_class.serializer)
     end
-    memoize :serializer
+    memoize :serializer, freezer: :noop
 
     def hooks
       config.hooks + options.fetch(:hooks, [])

data/lib/yaks/version.rb

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

metadata

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