yaks-html 0.6.0.alpha

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ad2e8ddea305f3b9c4197e27c908f81df3a6aad7
+  data.tar.gz: b15fa02453e1b71c6de06ac9fc157dddf09be27d
+SHA512:
+  metadata.gz: 169685112529c42eb30ffc8250344f10ba137367f50d73661346a110b701a533a91a609cb088b995488aaf0c277dec32ca23b048e551652fc0a11b224de77cc2
+  data.tar.gz: 03103204631478678810e10eccaca2cd66ed9bafbb3b25cf891b8f23e4aab01ed1b2493c918ebf3622f1a20d32d34e42476d8c3ac4b8fdea52752bd557d49066

data/.gitignore

@@ -0,0 +1,7 @@
+pkg
+.bundle
+coverage
+Gemfile.lock
+*~
+.yardoc
+doc

data/.travis.yml

@@ -0,0 +1,36 @@
+language: ruby
+script: bundle exec rake $TASK
+rvm:
+  - 1.9.3
+  - 2.0
+  - 2.1
+  - ruby-head
+  - rbx-2
+  - jruby
+  - jruby-head
+env:
+  - TASK=yaks:rspec
+  - TASK=yaks:mutant
+  - TASK=yaks-html:rspec
+  - TASK=yaks-html:mutant
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: jruby-head
+    - env: TASK=yaks:mutant
+    - env: TASK=yaks-html:mutant
+  exclude:
+    - rvm: jruby
+      env: TASK=yaks:mutant
+    - rvm: jruby
+      env: TASK=yaks-html:mutant
+
+    - rvm: jruby-head
+      env: TASK=yaks:mutant
+    - rvm: jruby-head
+      env: TASK=yaks-html:mutant
+
+    - rvm: rbx-2
+      env: TASK=yaks:mutant
+    - rvm: rbx-2
+      env: TASK=yaks-html:mutant

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

@@ -0,0 +1,149 @@
+### Development
+[full changelog](http://github.com/plexus/yaks/compare/v0.5.0...master)
+
+### 0.5.0
+
+* Yaks now serializes (returns a string), instead of returning a data structure. This is a preparatory step for supporting non-JSON formats. To get the old behavior back, do this
+
+``` ruby
+yaks = Yaks.new do
+  skip :serialize
+end
+```
+
+* The old `after` hook has been removed, instead there are now generic hooks for all steps: `before`, `after`, `around`, `skip`; `:map`, `:format`, `:primitivize`, `:serialize`.
+
+* By default Yaks uses `JSON.pretty_generate` as a JSON unparser. To use something else, for example `Oj.dump`, do this
+
+``` ruby
+yaks = Yaks.new do
+  json_serializer &Oj.method(:dump)
+end
+```
+
+* Mapping a non-empty collection will try to infer the type, and hence rel of the nested items, based on the first object in the collection. This is only relevant for formats like HAL that don't have a top-level collection representation, and only matters when mapping a collection at the top level, not when mapping a collection from an association.
+
+* Collection+JSON uses a link's "title" attribute to output a link's "name", to better correspond with other formats
+
+* When registering a custom format (Yaks::Format subclass), the signature has changed
+
+``` ruby
+# 0.4.3
+Format.register self, :collection_json, 'application/vnd.collection+json'
+
+# 0.5.0
+register :collection_json, :json, 'application/vnd.collection+json'
+```
+
+* `yaks.call` is now the preferred interface, rather than `yaks.serialize`, although there are no plans yet to remove the alias.
+
+* The result of a call to `Yaks.new` now responds to `to_proc`, so you can treat it as a Proc/Symbol, e.g. `some_method &yaks`
+
+* Improved YARD documentation
+
+* 100% mutation coverage :trumpet: :tada:
+
+### 0.4.3
+
+* when specifying a rel_template, instead of allowing for {src} and {dest} fields, now a single {rel} field is expected, which corresponds more with typical usage.
+
+```ruby
+Yaks.new do
+  rel_template 'http://my-api/docs/relationships/{rel}'
+end
+```
+
+* Yaks::Serializer has been renamed to Yaks::Format
+
+* Yaks::Mapper#{map_attributes,map_links,map_subresource} signature has changed, they now are responsible for adding themselves to a resource instance.
+
+```ruby
+class FooMapper < Yaks::Mapper
+  def map_attributes(resource)
+    resource.update_attributes(:example => 'attribute')
+  end
+end
+```
+
+* Conditionally turn associations into links
+
+```ruby
+class ShowMapper < Yaks::Mapper
+  has_many :events, href: '/show/{id}/events', link_if: ->{ events.count > 50 }
+end
+```
+
+* Reify `Yaks::Mapper::Attribute`
+
+* Remove `Yaks::Mapper#filter`, instead override `#attributes` or `#associations` to filter things out, for example:
+
+```ruby
+class SongMapper
+  attributes :title, :duration, :lyrics
+  has_one :artist
+  has_one :album
+
+  def minimal?
+    env['HTTP_PREFER'] =~ /minimal/
+  end
+
+  def attributes
+    if minimal?
+      super.reject {|attr| attr.name.equal? :lyrics } # These are instances of Yaks::Mapper::Attribute
+    else
+      super
+    end
+  end
+
+  def associations
+    return [] if minimal?
+    super
+  end
+end
+```
+
+* Give Attribute, Link, Association a common interface : `add_to_resource(resource, mapper, context)`
+* Add persistent update methods to `Yaks::Resource`
+
+### 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
+* Fix JSON-API bug (#18 reported by Nicolas Blanco)
+* Don't pluralize has_one association names in JSON-API
+
+## v0.4.0
+
+* Introduce after {} post-processing hook
+* Streamline interfaces and variable names, especially the use of `call`
+* Improve deriving mappers automatically, even with Rails style autoloading
+* Give CollectionResource a members_rel, for HAL-like formats with no top-level collection concept
+* Switch back to using `src` and `dest` as the rel-template keys, instead of `association_name`
+* deprecate `mapper_namespace` in favor of `namespace`
+
+### v0.4.0.rc1
+
+* Introduce Yaks.new as the main public interface
+* Fix JsonApiSerializer and make it compliant with current spec
+* Remove Hamster dependency, Yaks new uses plain old Ruby arrays and hashes
+* Remove `RelRegistry` and `ProfileRegistry` in favor of a simpler explicit syntax + policy based fallback
+* Add more policy derivation hooks, plus make `DefaultPolicy` template for rel urls configurable
+* Optionally take a Rack env hash, pass it around so mappers can inspect it
+* Honor the HTTP Accept header if it is present in the rack env
+* Add map_to_primitive configuration option
+
+## v0.3.0
+
+* Allow partial expansion of templates, expand certain fields, leave others as URI template in the result.
+
+## v0.2.0
+
+* links can now take a simple for a template to compute a link just like an attribute

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+gemspec path: 'yaks'
+gemspec path: 'yaks-html'

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/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2013-2014 Arne Brasseur
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.