yaks 0.6.0.alpha → 0.6.0.alpha.1

data/CHANGELOG.md

@@ -1,149 +0,0 @@
-### 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

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

data/IDENTIFIERS.md

@@ -1,113 +0,0 @@
-# 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

@@ -1,7 +0,0 @@
-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.

data/bench/bench.rb

@@ -1,16 +0,0 @@
-
-require 'benchmark/ips'
-require 'yaks'
-
-require_relative '../spec/acceptance/models'
-require_relative '../spec/fixture_helpers'
-
-Benchmark.ips do |x|
-  $yaks = Yaks.new
-
-  input = FixtureHelpers.load_yaml_fixture 'confucius'
-
-  x.report "Simple HAL mapping" do
-    $yaks.serialize(input)
-  end
-end

data/bench/bench_1000.rb

@@ -1,60 +0,0 @@
-#!/usr/bin/env ruby
-
-require 'benchmark/ips'
-require 'yaks'
-require 'ruby-prof'
-
-SIZE=20
-$timestamp = Time.now.utc.iso8601.gsub('-', '').gsub(':', '')
-$yaks = Yaks.new
-
-FlatModel = Struct.new(:field1, :field2)
-DeepModel = Struct.new(:field, :next)
-
-flat = SIZE.times.map do |i|
-  FlatModel.new(i, 'x' * (i % 50))
-end
-
-deep = nil
-SIZE.times do |i|
-  deep = DeepModel.new(i, deep)
-end
-
-class FlatMapper < Yaks::Mapper
-  attributes :field1, :field2
-  link :self, '/model/{field1}'
-end
-
-class DeepMapper < Yaks::Mapper
-  attributes :field
-  link :self, '/model/{field}'
-  has_one :next, mapper: DeepMapper
-end
-
-
-def profile!(name)
-  RubyProf.start
-  yield
-  results = RubyProf.stop
-  File.open "/tmp/#{name}-#{$timestamp}.out.#{$$}", 'w' do |file|
-    RubyProf::CallTreePrinter.new(results).print(file)
-  end
-end
-
-do_flat = ->(format) { -> { $yaks.serialize(flat, item_mapper: FlatMapper, format: format) } }
-do_deep = ->(format) { -> { $yaks.serialize(deep, mapper: DeepMapper, format: format) } }
-
-10.times { do_flat[:hal][] }
-10.times { do_deep[:hal][] }
-
-profile!('flat', &do_flat.(:hal))
-profile!('deep', &do_deep.(:hal))
-exit
-
-Benchmark.ips(10) do |job|
-  Yaks::Format.names.each do |format|
-
-    job.report "#{format} ; #{SIZE} objects in a list ; no nesting", &do_flat.(format)
-    job.report "#{format} ; #{SIZE} objects nested", &do_deep.(format)
-  end
-end

data/notes.org

@@ -1,72 +0,0 @@
-0.4
-
-* DONE Get rid of profile/rel registry, use policy instead
-* DONE pass around policy explicitly instead of through options
-* DONE introduce name/type separate from profile
-** DONE mapper
-** DONE Resource
-* DONE allow setting rel types directly on associations, with fallback to policy
-* DONE switch to hash-based init of Resource to make it more extensible
-* DONE add Resource#type
-* DONE not 100% happy yet about nameing of mapper#mapper_name / config#name. Maybe use `type` across the board?
-* DONE Fix JsonAPISerializer
-* top-level automatic links, e.g. for self and profile
-* make HAL plural/singular links configurable from the Yaks.new
-* make primitivize configuration instance based, not global
-* Have JsonApi add self links as href: attributes
-* Move examples to acceptance tests
-* Select mapper based on content type
-* move to 100% mutcov
-
-pre 0.5
-
-* CURIES/namespaces
-
-Ticketsolve::Api::Yaks = ::Yaks.new do
-  policy do
-    def derive...
-  end
-
-  hal_options.plural_link '...'
-
-  primitivize Date, Time do |o|
-    o.iso8601
-  end
-
-  rel_template "http://literature.example.com/rel/#{association_name}"
-
-  link :self, "http://api.com/{key}/{id}"
-  link :profile, "http://api.com/profile/{key}"
-
-  # and/or
-  derive_rel_from_association do |mapper, association|
-    "http://literature.example.com/rel/#{association.name}"
-  end
-end
-
-
-
-* DONE 59 lib/yaks/mapper.rb
-* DONE 92 lib/yaks/mapper/link.rb
-* DONE 37 lib/yaks/mapper/association.rb
-* DONE 3 lib/yaks/version.rb
-* DONE 13 lib/yaks/mapper/has_many.rb
-* DONE 9 lib/yaks/mapper/has_one.rb
-* DONE 79 lib/yaks/config.rb
-*   79 lib/yaks/mapper/config.rb
-*   73 lib/yaks.rb
-* DONE 72 lib/yaks/util.rb
-* DONE 65 lib/yaks/collection_resource.rb
-*   59 lib/yaks/json_api_serializer.rb
-*   59 lib/yaks/hal_serializer.rb
-*   43 lib/yaks/primitivize.rb
-*   37 lib/yaks/mapper/class_methods.rb
-* DONE 33 lib/yaks/collection_mapper.rb
-*   28 lib/yaks/null_resource.rb
-* DONE 27 lib/yaks/resource.rb
-*   25 lib/yaks/resource/link.rb
-* DONE 23 lib/yaks/fp.rb
-*   22 lib/yaks/serializer.rb
-*   15 lib/yaks/shared_options.rb
-*   15 lib/yaks/default_policy.rb
-*   10 lib/yaks/mapper/map_links.rb