yaks 0.4.4 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e75dbaa5cc865ca07fb16ae3e4662f3983652d96
-  data.tar.gz: bedaee826c1ae525bf0aa5511c62ccb3c02a0738
+  metadata.gz: 35548188d34c9c00d48ed2c575a2be98d424f313
+  data.tar.gz: 203ad17187b3063c9cf04592f026234d6474bc4e
 SHA512:
-  metadata.gz: 8f43aa2b03a6beb9f37009d3540ac8a75623e8dd3fb2b634785be696b81e20a3e7918cb3aef5eac86c63df49390f3ffd806c8a83596beff94e6dfb53793eba3d
-  data.tar.gz: 326578cce03f31740ceb6e927d431b8a42eefc0f79d8c65e0255bcd4475b952a6b0393eaf5ff11fcc5ae15f738bd7983ee767bd5964148cebccd9f8d68f50547
+  metadata.gz: dc6e520c6d8d5d878578481f3ab373867af02a90c3c1ccdf247dba7f3203049b0ba88b4681c6296c726eac52d5d85f30706449be9ae68193680a56ea407050fa
+  data.tar.gz: 465fbab2456ff24a8b1d948eb9cae76133a8d3fdbe2e71a6a54c246fe926693e58296626276560a8e55b99a45e4540345fdaf5b797745791af0ee97f53d4905c

data/.gitignore

@@ -3,3 +3,5 @@ pkg
 coverage
 Gemfile.lock
 *~
+.yardoc
+doc

data/CHANGELOG.md

@@ -1,7 +1,48 @@
 ### Development
-[full changelog](http://github.com/plexus/yaks/compare/v0.4.3...master)
+[full changelog](http://github.com/plexus/yaks/compare/v0.5.0...master)
 
-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.
+### 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.
+
+* When registering a custom format (Yaks::Format subclass), the signature has changed
+
+``` ruby
+
+* Collection+JSON uses a link's "title" attribute to output a link's "name", to better correspond with other formats
+
+# 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
 
@@ -106,4 +147,4 @@ end
 
 ## v0.2.0
 
-* links can now take a simple for a template to compute a link just like an attribute
+* links can now take a simple for a template to compute a link just like an attribute

data/README.md

@@ -27,17 +27,43 @@ They might also contain extra control data to specify possible future interactio
 
 These different media types for Hypermedia clients and servers base themselves on the same set of internet standards, such as [RFC4288 Media types](http://tools.ietf.org/html/rfc4288), [RFC5988 Web Linking](http://tools.ietf.org/html/rfc5988), [RFC6906 The "profile" link relation](http://tools.ietf.org/search/rfc6906) and [RFC6570 URI Templates](http://tools.ietf.org/html/rfc6570).
 
-## Yaks Resources
+## Concepts
 
-At the core of Yaks is the concept of a Resource, consisting of key-value attributes, RFC5988 style links, and embedded sub-resources.
+Yaks is a processing pipeline, you create and configure the pipeline, then feed data through it.
 
-To build an API you create 'mappers' that turn your domain models into resources. Then you pick a media type 'serializer', which can turn the resource into a hypermedia message.
+``` ruby
+yaks = Yaks.new do
+  default_format :hal
+  rel_template 'http://api.example.com/rels/{rel}'
+  format_options(:hal, plural_links: [:copyright])
+  namespace ::MyAPI
+  json_serializer do |data|
+    MultiJson.dump(data)
+  end
+end
+
+yaks.call(data) # => JSON
+```
+
+Yaks performs this serialization in three steps
 
-The web linking standard which defines link relations like 'self', 'next' or 'alternate' is embraced as far as practically possible, for instance to find the URI that uniquely defines a resource, we look at the 'self' link. To distinguish different types of resources we use the 'profile' link.
+* It *maps* your data to a `Yaks::Resource`
+* It *formats* the resource to a syntax tree representation
+* It *serializes* to get the final output
+
+For JSON types, the "syntax tree" is just a combination of Ruby primitives, nested arrays and hashes with strings, numbers, booleans, nils.
+
+A Resource is an abstraction shared by all output formats. It can contain key-value attributes, RFC5988 style links, and embedded sub-resources.
+
+To build an API you create a "mapper" for each type of object you want to represent. Yaks takes care of the rest.
+
+For all configuration options see [Yaks::Config::DSL](http://rdoc.info/gems/yaks/frames/Yaks/Config/DSL).
+
+See also the [API Docs on rdoc.info](http://rdoc.info/gems/yaks/frames/file/README.md)
 
 ## Mappers
 
-To turn your domain models into resources, you define mappers, for example :
+Say your app has a `Post` object for blog posts. To serve posts over your API, define a `PostMapper`
 
 ```ruby
 class PostMapper < Yaks::Mapper
@@ -54,7 +80,7 @@ Configure a Yaks instance and start serializing!
 
 ```ruby
 yaks = Yaks.new
-yaks.serialize(post)
+yaks.call(post)
 ```
 
 or a bit more elaborate
@@ -66,7 +92,7 @@ yaks = Yaks.new do
   format_options(:hal, plural_links: [:copyright])
 end
 
-yaks.serialize(post, mapper: PostMapper, format: :hal)
+yaks.call(post, mapper: PostMapper, format: :hal)
 ```
 
 ### Attributes
@@ -100,7 +126,7 @@ end
 
 #### Filtering
 
-Implementing a `#filter` method in your mappers is no longer supported. Instead you can override `#attributes`, or `#associations`.
+You can override `#attributes`, or `#associations`.
 
 ```ruby
 class SongMapper
@@ -186,6 +212,40 @@ class ShowMapper < Yaks::Mapper
 end
 ```
 
+## Calling Yaks
+
+Once you have a Yaks instance, you can call it with `call`
+(`serialize` also works but might be deprecated in the future.) Pass
+it the data to be serialized, plus options.
+
+* `:env` a Rack environment, see next section
+* `:format` the format to be used, e.g. `:json_api`. Note that if the Rack env contains an `Accept` header which resolves to a recognized format, then the header takes precedence
+* `:mapper` the mapper to be used. Will be inferred if omitted
+* `:item_mapper` When rendering a collection, the mapper to be used for each item in the collection. Will be inferred from the class of the first item in the collection if omitted.
+
+### Rack env
+
+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
+  attributes :bar
+
+  def bar
+    if env['something']
+      #...
+    end
+  end
+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.
+
+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
 
 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`.
@@ -237,28 +297,6 @@ end
 
 Yaks will automatically detect and use this collection when serializing an array of `LineItem` objects.
 
-## Rack env
-
-When serializing, Yaks lets you pass in an `env` hash, which will be made available to all mappers.
-
-```ruby
-yaks = Yaks.new
-yaks.serialize(foo, env: my_env)
-
-class FooMapper
-  attributes :bar
-
-  def bar
-    if env['something']
-      #...
-    end
-  end
-end
-```
-
-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.
 
 ## Custom attribute/link/subresource handling
 
@@ -296,7 +334,7 @@ Since version 0.4 the recommended API is through `Yaks.new {...}.serialize`. Thi
 
 ```ruby
 my_yaks = Yaks.new
-hal = my_yaks.serialize(model)
+hal = my_yaks.call(model)
 puts JSON.dump(hal)
 ```
 
@@ -352,6 +390,23 @@ Subresources aren't mapped because Collection+JSON doesn't really have that conc
 
 Are planned... at the moment HAL is the only format I actually use, so it's the one that's best supported. Adding formats that follow the resource=(attributes, links, subresources) structure or a subset thereof is straightforward. More features, e.g. forms/actions such as used in Mason might be added in the future.
 
+## 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.
+
+``` ruby
+yaks = Yaks.new do
+  # Automatically give every resource a self link
+  after :map, :add_self_link do |resource|
+    resource.add_link(Yaks::Resource::Link.new(:self, "/#{resource.type}/#{resource.attributes[:id]}"))
+  end
+
+  # Skip serialization, so Ruby primitives come back instead of JSON
+  # This was the default before versions < 0.5.0
+  skip :serialize
+end
+```
+
 ## 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.
@@ -398,7 +453,7 @@ end
 
 ## Primitives
 
-For JSON based formats, a final step in serializing is to turn the nested data into primitives that have a JSON equivalent. For example, JSON has no notion of symbols or 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`
+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`
 
 ```ruby
 Yaks.new do
@@ -420,7 +475,9 @@ Yaks.new do
 end
 ```
 
-## Usage
+Yaks by default "primitivizes" symbols (as strings), and classes that include Enumerable (as arrays).
+
+## 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/Rakefile

@@ -52,3 +52,13 @@ task :mutant_chunked do
     Rake::Task["mutant"].execute
   end
 end
+
+begin
+  require 'yard'
+
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yard do
+    $stderr.puts 'In order to run yard, you must: gem install yard'
+  end
+end

data/bench/bench.rb

@@ -13,5 +13,4 @@ Benchmark.ips do |x|
   x.report "Simple HAL mapping" do
     $yaks.serialize(input)
   end
-
 end

data/bench/bench_1000.rb

@@ -0,0 +1,60 @@
+#!/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/lib/yaks/breaking_changes.rb

@@ -4,6 +4,28 @@ module Yaks
 # gem to aid upgraiding
 
 BreakingChanges = {
+
+'0.5.0' => %q~
+
+Breaking Changes in Yaks 0.5.0
+==============================
+
+Yaks now serializes its output, you no longer have to convert to JSON
+yourself. Use `skip :serialize' to get the old behavior, or
+`json_serializer` to use a different JSON implementation.
+
+The single `after' hook has been replaced with a set of `before',
+`after', `around' and `skip' hooks.
+
+If you've created your own subclass of `Yaks::Format' (previously:
+`Yaks::Serializer'), then you need to update the call to
+`Format.register'.
+
+These are potentially breaking changes. See the CHANGELOG and README
+for full documentation.
+
+~,
+
 '0.4.3' => %q~
 
 Breaking Changes in Yaks 0.4.3

data/lib/yaks/config/dsl.rb

@@ -6,70 +6,157 @@ module Yaks
       attr_reader :config
 
       # @param [Yaks::Config] config
-      # @param [Proc] blk
-      # @return [Yaks::Config::DSL]
-      def initialize(config, &blk)
+      # @param [Proc] block
+      def initialize(config, &block)
         @config       = config
         @policy_class = Class.new(DefaultPolicy)
         @policies     = []
-        instance_eval(&blk) if blk
-        @policies.each do |policy_blk|
-          @policy_class.class_eval &policy_blk
+        instance_eval(&block) if block
+        @policies.each do |policy_block|
+          @policy_class.class_eval &policy_block
         end
         config.policy_class = @policy_class
       end
 
+      # Set the options for a format
+      #
       # @param [Symbol] format
-      # @return [Symbol]
+      # @param [Hash] options
+      #
+      # @example
+      #
+      #   yaks = Yaks.new do
+      #     format_options :hal, {plural_links: [:related_content]}
+      #   end
+      #
       def format_options(format, options)
         config.format_options[format] = options
       end
 
+      # Set the default format
+      #
+      # Defaults to +:hal+
+      #
       # @param [Symbol] format
-      # @return [Symbol]
+      #   Format identifier, one of +Yaks::Format.names+
+      #
+      # @example
+      #
+      #    yaks = Yaks.new do
+      #      default_fomat :json_api
+      #    end
+      #
       def default_format(format)
         config.default_format = format
       end
 
-      # @param [Object] klass
-      # @return [Object]
+      # Configure JSON serializer
+      #
+      # Defaults to JSON.pretty_generate
+      #
+      # @example
+      #
+      #   yaks = Yaks.new do
+      #     json_serializer &Oj.method(:dump)
+      #   end
+      #
+      # @param [Proc] block
+      #   Serialization procedure
+      #
+      def json_serializer(&block)
+        config.serializers[:json] = block
+      end
+
+      %w[before after around skip].map(&:intern).each do |hook_type|
+        define_method hook_type do |step, name = :"#{hook_type}_#{step}", &block|
+          config.hooks << [hook_type, step, name, block]
+        end
+      end
+
+      # Set a different policy implementation
+      #
+      # By default Yaks uses +Yaks::DefaultPolicy+ to derive missing
+      # information. You can swap in a class with a compatible
+      # interface to change the default behavior
+      #
+      # To override a single policy method, simply call a method with
+      # the same name as part of your Yaks configuration, passing a
+      # block to define the new behavior.
+      #
+      # @example
+      #
+      #    yaks = Yaks.new do
+      #      derive_type_from_mapper_class do |mapper_class|
+      #        mapper_class.name.sub(/Mapper^/,'')
+      #      end
+      #    end
+      #
+      # @param [Class] klass
+      #   Policy class
+      #
       def policy(klass)
         @policy_class = klass
       end
 
-      # @param [String] templ
-      # @return [String]
-      def rel_template(templ)
-        config.policy_options[:rel_template] = templ
+      # Set the template for deriving rels
+      #
+      # Used to derive rels for links and subresources.
+      #
+      # @example
+      #
+      #   yaks = Yaks.new do
+      #     rel_template 'http://api.example.com/rels/{rel}'
+      #   end
+      #
+      # @param [String] template
+      #   A valid URI template containing +{rel}+
+      #
+      def rel_template(template)
+        config.policy_options[:rel_template] = template
       end
 
-      # @param [Object] namespace
-      # @return [Object]
+      # Set the namespace (Ruby module) that contains your mappers
+      #
+      # When your mappers don't live at the top-level, then set this
+      # so Yaks can correctly infer the mapper class from the model
+      # class.
+      #
+      # @example
+      #
+      #   yaks = Yaks.new do
+      #     mapper_namespace API::Mappers
+      #   end
+      #
+      #   module API::Mappers
+      #     class FruitMapper < Yaks::Mapper
+      #        ...
+      #     end
+      #   end
+      #
+      #   class Fruit < BaseModel
+      #     ...
+      #   end
+      #
+      # @param [Module] namespace
+      #
       def mapper_namespace(namespace)
         config.policy_options[:namespace] = namespace
       end
       alias namespace mapper_namespace
 
       # @param [Array] args
-      # @param [Proc] blk
-      # @return [Array]
-      def map_to_primitive(*args, &blk)
-        config.primitivize.map(*args, &blk)
-      end
-
       # @param [Proc] block
-      # @return [Array]
-      def after(&block)
-        config.steps << block
+      def map_to_primitive(*args, &block)
+        config.primitivize.map(*args, &block)
       end
 
       # Will define each method available in the DefaultPolicy upon the DSL
       # and then make it available to apply to any Class taking on the
       # `@policies` Array.
       DefaultPolicy.public_instance_methods(false).each do |method|
-        define_method method do |&blk|
+        define_method method do |&block|
           @policies << proc {
-            define_method method, &blk
+            define_method method, &block
           }
         end
       end

data/lib/yaks/config.rb

@@ -1,79 +1,64 @@
 module Yaks
   class Config
+    include Yaks::FP::Callable
+
+    # @!attribute [r] format_options
+    #   @return [Hash<Symbol,Hash>]
+    attr_reader :format_options
 
-    # @!attribute [rw] format_options
-    #   @return [Hash]
     # @!attribute [rw] default_format
     #   @return [Symbol]
+    attr_accessor :default_format
+
     # @!attribute [rw] policy_class
-    #   @return [Constant]
-    # @!attribute [rw] policy_options
+    #   @return [Class]
+    attr_accessor :policy_class
+
+    # @!attribute [r] policy_options
     #   @return [Hash]
+    attr_reader :policy_options
+
     # @!attribute [rw] primitivize
-    #   @return [Boolean]
-    # @!attribute [rw] steps
+    #   @return [Primitivize]
+    attr_accessor :primitivize
+
+    # @!attribute [r] serializers
+    #   @return [Hash<Symbol,#call>]
+    attr_reader :serializers
+
+    # @!attribute [r] hooks
     #   @return [Array]
-    attr_accessor :format_options, :default_format, :policy_class, :policy_options, :primitivize, :steps
+    attr_reader :hooks
 
-    # @param [Proc] blk
-    # @return [Yaks::Config]
+    # @param blk [Proc] Configuration block
     def initialize(&blk)
       @format_options = Hash.new({})
       @default_format = :hal
       @policy_options = {}
       @primitivize    = Primitivize.create
-      @steps          = [
-        @primitivize
-      ]
+      @serializers    = {}
+      @hooks          = []
+
       DSL.new(self, &blk)
     end
 
-    # @return [Yaks::DefaultPolicy, Object]
+    # @return [Yaks::DefaultPolicy]
     def policy
-      @policy_class.new(@policy_options)
-    end
-
-    # @param [Hash] opts
-    # @param [Hash] env
-    # @return [Class]
-    def format_class(opts, env)
-      accept = Rack::Accept::MediaType.new(env['HTTP_ACCEPT'])
-      mime_type = accept.best_of([nil] + Format.mime_types.values)
-      return Format.by_mime_type(mime_type) if mime_type
-      Format.by_name(opts.fetch(:format) { @default_format })
-    end
-
-    # @param [Hash] opts
-    # @return [String]
-    def format_name(opts)
-      opts.fetch(:format) { @default_format }
-    end
-
-    # @param [Symbol] format
-    # @return [Object]
-    def options_for_format(format)
-      format_options[format]
+      @policy ||= @policy_class.new(@policy_options)
     end
 
-    # model                => Yaks::Resource
-    # Yaks::Resource       => serialized structure
-    # serialized structure => serialized flat
+    # Main entry point into yaks
     #
-    # @param [Object] object
-    # @param [Hash] opts
-    # @return [Object]
-    def call(object, opts = {})
-      env = opts.fetch(:env, {})
-      context = {
-        policy: policy,
-        env: env,
-        mapper_stack: []
-      }
-
-      mapper = opts.fetch(:mapper) { policy.derive_mapper_from_object(object) }.new(context)
-      format = format_class(opts, env).new(format_options[format_name(opts)])
-
-      [ mapper, format, *steps ].inject(object) {|memo, step| step.call(memo) }
+    # @param object [Object] The object to serialize
+    # @param options [Hash<Symbol,Object>] Serialization options
+    #
+    # @option env [Hash] The rack environment
+    # @option format [Symbol] The target format, default :hal
+    # @option mapper [Class] Mapper class to use
+    # @option item_mapper [Class] Mapper class to use for items in a top-level collection
+    #
+    def call(object, options = {})
+      Runner.new(config: self, object: object, options: options).call
     end
     alias serialize call
   end