yaks 0.8.3 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a609ab5341e17172a098a296e8935d9abf4fa995
-  data.tar.gz: 44f4ef2d6d7786bf09261b352ed9e253064ff31e
+  metadata.gz: e1351b2c236dc9fb68ff5bbe9c365f7addb38cad
+  data.tar.gz: d8baafb1e55bc4bf5e926e012dac9bd20d7284f8
 SHA512:
-  metadata.gz: f65c4f9d62853543fc92fbe58fc9a3c4b057eac27473a951d8cfe38edf19cf0af461bd9e047e20cbce47ab771ded553b859937e6c8dff7e1a25aa2f1101f8a18
-  data.tar.gz: be7d5c1edcc4e745a25897deae315000d1bdff1713b8a6d61876f36d62d4dc866792a5f362957c7218e64e7a9c346bec38bd064e7297cfa33be26702b451bd33
+  metadata.gz: 4f5732d430846954a651d3aff1145cf07610098d23c0ba2b28bfe7626b3e3c2c3c741d6f50d84459360a1986d820f10604d115bd3336ccad6dac2386bf808142
+  data.tar.gz: 7ce7ea4c6bdf3c0e0fc2ae11ecee61813c4be3b8eefe01316153ba427d6522496f2d92e3efcbf2c29f60bea9db3a93b158caf4d667472835438c284ae14df08f

data/README.md

@@ -12,8 +12,15 @@
 
 # Yaks
 
+![](logo.png)
+
 The library that understands hypermedia.
 
+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
+linked resources, a concept central to the architecture of the web.
+
 Yaks consists of a resource representation that is independent of any
 output type. A Yaks mapper transforms an object into a resource, which
 can then be serialized into whichever output format the client
@@ -482,6 +489,11 @@ 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.
 
+At this time, The JSON-API specification has not reached a 1.0 release.
+Some changes to the Yaks JSON-API formatter may still be required
+before it is completely compatible with the latest version of the
+specification.
+
 If you would like to see better JSON-API support, get in touch. We
 might be able to work something out.
 

data/lib/yaks.rb

@@ -12,11 +12,11 @@ require 'rack/accept'
 
 require 'yaks/version'
 require 'yaks/util'
+require 'yaks/attributes'
 require 'yaks/configurable'
 require 'yaks/fp'
 require 'yaks/fp/callable'
 require 'yaks/primitivize'
-require 'yaks/attributes'
 require 'yaks/builder'
 require 'yaks/errors'
 
@@ -75,10 +75,11 @@ require 'yaks/mapper/has_one'
 require 'yaks/mapper/has_many'
 require 'yaks/mapper/attribute'
 require 'yaks/mapper/link'
-require 'yaks/mapper/form/config'
 require 'yaks/mapper/form/field/option'
 require 'yaks/mapper/form/field'
 require 'yaks/mapper/form/fieldset'
+require 'yaks/mapper/form/dynamic_field'
+require 'yaks/mapper/form/config'
 require 'yaks/mapper/form'
 require 'yaks/mapper/config'
 require 'yaks/mapper'
@@ -98,5 +99,6 @@ require 'yaks/format/json_api'
 require 'yaks/format/collection_json'
 
 require 'yaks/reader/hal'
+require 'yaks/reader/json_api'
 require 'yaks/pipeline'
 require 'yaks/runner'

data/lib/yaks/attributes.rb

@@ -13,7 +13,7 @@ module Yaks
     end
 
     def remove(*attrs)
-      self.class.new(*[*(names-attrs), @defaults.reject {|k,v| attrs.include?(k) }])
+      self.class.new(*[*(names-attrs), @defaults.reject {|k| attrs.include?(k) }])
     end
 
     def included(descendant)

data/lib/yaks/builder.rb

@@ -7,8 +7,8 @@ module Yaks
   #
   #   # This code
   #   Form.create(:search)
-  #          .method("POST")
-  #          .action("/search")
+  #       .method("POST")
+  #       .action("/search")
   #
   #   # Can be written as
   #   Builder.new(Form, [:method, :action]).create(:search) do
@@ -19,6 +19,13 @@ module Yaks
   class Builder
     include Configurable
 
+    def initialize(klass, methods = [], &block)
+      @klass = klass
+      @methods = methods
+      def_forward *methods if methods.any?
+      instance_eval(&block) if block
+    end
+
     def create(*args, &block)
       build(@klass.create(*args), &block)
     end
@@ -29,15 +36,8 @@ module Yaks
       @config
     end
 
-    def initialize(klass, methods = [], &block)
-      @klass = klass
-      @methods = methods
-      def_forward *methods if methods.any?
-      instance_eval(&block) if block
-    end
-
     def inspect
-      "#<Builder #{@klass} #{@methods.inspect}>"
+      "#<Builder #{@klass} #{@methods}>"
     end
   end
 end

data/lib/yaks/collection_mapper.rb

@@ -4,7 +4,7 @@ module Yaks
 
     # @param [Array] collection
     # @return [Array]
-    def call(collection, env = {})
+    def call(collection, _env = nil)
       @object = collection
 
       attrs = {

data/lib/yaks/config.rb

@@ -18,7 +18,7 @@ module Yaks
 
     deprecated_alias :namespace, :mapper_namespace
 
-    def format_options(format = Undefined, options = Undefined)
+    def format_options(format, options = Undefined)
       with(format_options_hash: format_options_hash.merge(format => options))
     end
 

data/lib/yaks/configurable.rb

@@ -1,4 +1,22 @@
 module Yaks
+  # A "Configurable" class is one that keeps a configuration in a
+  # separate immutable object, of type class::Config. say you have
+  #
+  #     class MyMapper < Yaks::Mapper
+  #       # use yaks configuration DSL in here
+  #     end
+  #
+  # The links, associations, etc, that you set up for MyMapper, will
+  # be available in MyMapper.config, which is an instance of
+  # Yaks::Mapper::Config.
+  #
+  # Each configuration step, like `link`, `has_many`, will replace
+  # MyMapper.config with an updated version, discarding the old
+  # config.
+  #
+  # By extending Configurable, a number of "macros" become available
+  # to describe the DSL that subclasses can use. See the docs for
+  # `def_set`. `def_forward`, and `def_add`.
   module Configurable
     attr_accessor :config
 
@@ -10,14 +28,28 @@ module Yaks
       child.config = config
     end
 
+    # Create a DSL method to set a certain config property. The
+    # generated method will take either a plain value, or a block,
+    # which will be captured and stored instead.
     def def_set(*method_names)
       method_names.each do |method_name|
-        define_singleton_method method_name do |arg|
-          self.config = config.update(method_name => arg)
+        define_singleton_method method_name do |arg = Undefined, &block|
+          if arg == Undefined && block
+            self.config = config.update(method_name => block)
+          elsif arg == Undefined
+            raise ArgumentError, "wrong number of arguments (0 for 1)"
+          else
+            self.config = config.update(method_name => arg)
+          end
         end
       end
     end
 
+    # Forward a method to the config object. This assumes the method
+    # will return an updated config instance.
+    #
+    # Either takes a list of methods to forward, or a mapping (hash)
+    # of source to destination method name.
     def def_forward(method_names, *args)
       unless method_names.is_a? Hash
         def_forward([method_names, *args].map{|name| {name => name}}.inject(:merge))
@@ -30,6 +62,13 @@ module Yaks
       end
     end
 
+    # Generate a DSL method that creates a certain type of domain
+    # object, and adds it to a list on the config.
+    #
+    #     def_add :fieldset, create: Fieldset, append_to: :fields
+    #
+    # This will generate a `fieldset` method, which will call
+    # `Fieldset.create`, and append the result to `config.fields`
     def def_add(name, options)
       define_singleton_method name do |*args, &block|
         defaults = options.fetch(:defaults, {})

data/lib/yaks/format/json_api.rb

@@ -7,12 +7,12 @@ module Yaks
 
       # @param [Yaks::Resource] resource
       # @return [Hash]
-      def call(resource, env = {})
+      def call(resource, _env = nil)
         main_collection = resource.seq.map(&method(:serialize_resource))
 
-        { pluralize(resource.type) => main_collection }.tap do |serialized|
-          linked = resource.seq.each_with_object({}) do |res, hsh|
-            serialize_linked_subresources(res.subresources, hsh)
+        { data: main_collection }.tap do |serialized|
+          linked = resource.seq.each_with_object([]) do |res, array|
+            serialize_linked_subresources(res.subresources, array)
           end
           serialized.merge!(linked: linked) unless linked.empty?
         end
@@ -21,11 +21,10 @@ module Yaks
       # @param [Yaks::Resource] resource
       # @return [Hash]
       def serialize_resource(resource)
-        result = resource.attributes
+        result = {type: pluralize(resource.type).to_sym}.merge(resource.attributes)
 
-        unless resource.subresources.empty?
-          result[:links] = serialize_links(resource.subresources)
-        end
+        links = serialize_links(resource.subresources)
+        result[:links] = links unless links.empty?
 
         if resource.self_link && !result.key?(:href)
           result[:href]  = resource.self_link.uri
@@ -39,29 +38,32 @@ module Yaks
       def serialize_links(subresources)
         subresources.each_with_object({}) do |resource, hsh|
           next if resource.null_resource?
-          key = resource.collection? ? pluralize(resource.type) : resource.type
-          hsh[key] = serialize_link(resource)
+          hsh[resource.type] = serialize_link(resource)
         end
       end
 
       # @param [Yaks::Resource] resource
       # @return [Array, String]
       def serialize_link(resource)
-        resource.collection? ? resource.map(&send_with_args(:[], :id)) : resource[:id]
+        if resource.collection?
+          {type: resource.type, ids: resource.map(&send_with_args(:[], :id))}
+        else
+          {type: pluralize(resource.type), id: resource[:id]}
+        end
       end
 
       # @param [Hash] subresources
-      # @param [Hash] hsh
-      # @return [Hash]
-      def serialize_linked_subresources(subresources, hsh)
+      # @param [Array] array
+      # @return [Array]
+      def serialize_linked_subresources(subresources, array)
         subresources.each do |resources|
-          serialize_linked_resources(resources, hsh)
+          serialize_linked_resources(resources, array)
         end
       end
 
       # @param [Array] resources
-      # @param [Hash] linked
-      # @return [Hash]
+      # @param [Array] linked
+      # @return [Array]
       def serialize_linked_resources(subresource, linked)
         subresource.seq.each_with_object(linked) do |resource, memo|
           serialize_subresource(resource, memo)
@@ -74,32 +76,16 @@ module Yaks
       # @param [Hash] linked
       # @return [Hash]
       def serialize_subresource(resource, linked)
-        key = pluralize(resource.type)
-        set = linked.fetch(key) { Set.new }
-        linked[key] = (set << serialize_resource(resource))
+        linked << serialize_resource(resource)
         serialize_linked_subresources(resource.subresources, linked)
       end
 
       def inverse
-        JsonApi::Reader.new
+        Yaks::Reader::JsonAPI.new
       end
     end
 
     class Reader
-      def call(data, env)
-        type = data.detect do |key, value|
-          key unless key == "links"
-        end
-
-        CollectionResource.new(
-          type: type,
-          members: map_to_resource(data[type], )
-        )
-      end
-
-      def inverse
-        JsonApi.new
-      end
     end
   end
 end

data/lib/yaks/mapper.rb

@@ -2,7 +2,8 @@ module Yaks
   class Mapper
     extend Configurable
 
-    def_forward :type       => :with_type
+    def_set :type
+
     def_forward :attributes => :add_attributes
     def_forward :append_to
 

data/lib/yaks/mapper/form.rb

@@ -1,22 +1,8 @@
 module Yaks
   class Mapper
     class Form
-      extend Configurable, Forwardable, Util
+      extend Forwardable, Util
 
-      ConfigBuilder = Builder.new(Config) do
-        def_set :action, :title, :method, :media_type
-        def_add :field, create: Field::Builder, append_to: :fields
-        def_add :fieldset, create: Fieldset, append_to: :fields
-        HTML5Forms::INPUT_TYPES.each do |type|
-          def_add(type,
-            create: Field::Builder,
-            append_to: :fields,
-            defaults: { type: type }
-          )
-        end
-        def_forward :dynamic
-        def_forward :condition
-      end
 
       def_delegators :config, :name, :action, :title, :method,
                               :media_type, :fields, :dynamic_blocks
@@ -28,28 +14,22 @@ module Yaks
           options[:name] = args.first
         end
 
-        new(ConfigBuilder.build(Config.new(options), &block))
+        new(config: Config.build(options, &block))
       end
 
       ############################################################
       # instance
 
-      include Concord.new(:config)
+      include Attributes.new(:config)
 
       def add_to_resource(resource, mapper, _context)
         return resource if config.if && !mapper.expand_value(config.if)
-        resource.add_form(to_resource(mapper))
+        resource.add_form(to_resource_form(mapper))
       end
 
-      private
-
-      def to_resource(mapper)
-        config = dynamic_blocks.inject(self.config) do |config, block|
-          ConfigBuilder.build(config, mapper.object, &block)
-        end
-
+      def to_resource_form(mapper)
         attrs = {
-          fields: resource_fields(config.fields, mapper),
+          fields: config.to_resource_fields(mapper),
           action: mapper.expand_uri(config.action, true)
         }
 
@@ -60,9 +40,6 @@ module Yaks
         Resource::Form.new(attrs)
       end
 
-      def resource_fields(fields, mapper)
-        fields.map { |field| field.to_resource(mapper) }
-      end
     end
   end
 end

data/lib/yaks/mapper/form/config.rb

@@ -9,17 +9,51 @@ module Yaks
                   method: nil,
                   media_type: nil,
                   fields: [],
-                  dynamic_blocks: [],
                   if: nil
                 )
 
-        def dynamic(&blk)
-          append_to(:dynamic_blocks, blk)
+        def self.builder
+          @builder ||= Builder.new(self) do
+            def_set :action, :title, :method, :media_type
+            def_add :field, create: Field::Builder, append_to: :fields
+            def_add :fieldset, create: Fieldset, append_to: :fields
+            HTML5Forms::INPUT_TYPES.each do |type|
+              def_add(type,
+                      create: Field::Builder,
+                      append_to: :fields,
+                      defaults: { type: type })
+            end
+            def_add :dynamic, create: DynamicField, append_to: :fields
+            def_forward :condition
+          end
+        end
+
+        # Builder expects a `create' method. Alias to constructor
+        def self.create(options)
+          new(options)
+        end
+
+        # Build up a configuration based on an initial set of
+        # attributes, and a configuration block
+        def self.build(options = {}, &block)
+          builder.create(options, &block)
+        end
+
+        # Build up a configuration based on a config block. Provide an
+        # object to be supplied to the block
+        def self.build_with_object(object, &block)
+          builder.build(new, object, &block)
         end
 
         def condition(prc = nil, &blk)
           with(if: prc || blk)
         end
+
+        def to_resource_fields(mapper)
+          fields.flat_map do |field|
+            field.to_resource_fields(mapper)
+          end
+        end
       end
     end
   end