praxis-blueprints 2.2 → 3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c0621988651c28b2a7067510da6b334b3bb788fd
-  data.tar.gz: f89f81316cb31874e7353cf86b85e5f29552112e
+  metadata.gz: 9fe3a8efadb5bf8bc0014eae372157bd62020363
+  data.tar.gz: df99c67d44c66bf7d99ab017a56c220b7ff01586
 SHA512:
-  metadata.gz: a9d0c616bb141113114edadd7aa8446ad686da969bb0bb7f4b018b5999a7190cb8f8f570b003503728849841dfbee17be1c5bd21a14e50cd9a1e147e58724f82
-  data.tar.gz: e5c20f1b9577216b1a480cabfbf1fcb0941391f3937b0096ce0f1e7c11212e6eba64e60aad6b3be0b4403a6f6584a4ba83d561c53bc3591d6e017d0e1deff60c
+  metadata.gz: ba760805fbd070350e360638d781833bd9f66abc2dfb2f1a3f30cc5456ab8f6fbfbfdd3e0a1cb5088ba18d4c1299641f8f804e4123fcc453a91c40b4e6d49091
+  data.tar.gz: 2588dbe95bc05c824c8dfd7bffe1ddb7973839f8cbe0dca72ff5a37744add676535c09f27f733dd40f593e57aba95d9556cee183cad0e093c20c170e152c9cbc

data/.travis.yml

@@ -1,5 +1,6 @@
 language: ruby
 cache: bundler
+sudo: false
 rvm:
   - 2.1.2
   - 2.2.2

data/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 ## next
 
+## 3.0
+
+* Added `FieldExpander`, a new class that recursively expands a tree of
+  of attributes for Blueprint types as well as view objects into their lowest-level values.
+    * For example, for the `Person` and `Address` blueprints defined in
+    [spec_blueprints.rb](sped/support/spec_blueprints.rb):
+      * `FieldExpander.expand(Person, {name: true, full_name: true})` would return
+        `{name: true, full_name: {first: true, last:true}}`.
+    * Attempting to expand attributes with circular references (i.e. the
+      a person's address, where that address then references that person) will
+      raise a `Praxis::FieldExpander::CircularExpansionError` error.
+* Added `Renderer`, a new class for rendering objects (typically Blueprint
+  instances) with an explicit and recursive set of fields (as from
+  `Fieldexpander`).
+    * For example:
+      * `render(person, name: true)` would produce `{name: person.name}`
+      * `render(person, name: true, address: {state: true})` would
+        produce `{name: person.name, address: {state: person.address.state}}`
+    * Accepts an `include_nil:` option when initialized, that if true will
+      cause the renderer to output values that are nil, rather than omit them.
+      Note: this will apply to the entire rendering, there is no way to set it
+      for only a portion of the rendering, or on a per-View basis.
+* Added `Blueprint.domain_model` to specify the underlying domain model, e.g.
+  a `Praxis::Mapper::Resource`. Accepts a string value that is resolved when
+  `Blueprint.finalize!` is called. Defaults to `Object`.
+* `Blueprint.load` will use the `domain_model` to wrap the incoming object
+  if it is not an instance of that class. Note: this does not change existing
+  default if `domain_model` is not set.
+* Refactored `View` and `CollectionView` rendering to use a `Renderer` with
+  a set of expanded fields.
+* The automatically generated `:master` view will now render sub-attributes
+  using their `:default` view, rather than `:master`.
+* `Blueprint#render` now uses `Renderer` and `FieldExpander` internally. In most
+  cases this will continue to function identically to the old behavior, but
+* Views defined with `Blueprint.view`, including subviews defined inside,
+  no longer accept the `:include_nil` option. This can be set using the same
+  option on `Renderer` described above.
+
+
 ## 2.2
 
 * Added instrumentation through `ActiveSupport::Notifications`

data/Gemfile

@@ -1,3 +1,2 @@
 source 'https://rubygems.org'
-
-gemspec
+gemspec

data/lib/praxis-blueprints.rb

@@ -12,3 +12,6 @@ require 'praxis-blueprints/config_hash'
 require 'praxis-blueprints/blueprint'
 require 'praxis-blueprints/view'
 require 'praxis-blueprints/collection_view'
+
+require 'praxis-blueprints/renderer'
+require 'praxis-blueprints/field_expander'

data/lib/praxis-blueprints/blueprint.rb

@@ -18,13 +18,15 @@ module Praxis
 
     @@caching_enabled = false
 
-    CIRCULAR_REFERENCE_MARKER = '...'.freeze
 
-    attr_accessor :object, :decorators
-    attr_reader :validating, :active_renders
+    attr_reader :validating
+    attr_accessor :object
+    attr_accessor :decorators
 
     class << self
-      attr_reader :views, :attribute, :options
+      attr_reader :views
+      attr_reader :attribute
+      attr_reader :options
       attr_accessor :reference
     end
 
@@ -34,21 +36,20 @@ module Praxis
       klass.instance_eval do
         @views = Hash.new
         @options = Hash.new
+        @domain_model = Object
       end
     end
 
     # Override default new behavior to support memoized creation through an IdentityMap
     def self.new(object, decorators=nil)
       if @@caching_enabled && decorators.nil?
-        key = object
-
         cache = if object.respond_to?(:identity_map) && object.identity_map
           object.identity_map.blueprint_cache[self]
         else
           self.cache
         end
 
-        return cache[key] ||= begin
+        return cache[object] ||= begin
           blueprint = self.allocate
           blueprint.send(:initialize, object, decorators)
           blueprint
@@ -112,6 +113,11 @@ module Praxis
     end
 
 
+    def self.domain_model(klass=nil)
+      return @domain_model if klass.nil?
+      @domain_model = klass
+    end
+
     def self.check_option!(name, value)
       case name
       when :identity
@@ -134,11 +140,19 @@ module Praxis
           self.new(value)
         end
       else
-        # Just wrap whatever value
-        self.new(value)
+        if value.kind_of?(self.domain_model) || value.kind_of?(self::Struct)
+          # Wrap the value directly
+          self.new(value)
+        else
+          # Wrap the object inside the domain_model
+          self.new(domain_model.new(value))
+        end
       end
     end
 
+    class << self
+      alias_method :from, :load
+    end
 
     def self.caching_enabled?
       @@caching_enabled
@@ -203,10 +217,8 @@ module Praxis
 
       object.render(view: view, context: context, **opts)
     end
-
-    # Allow render on the class too, for completeness and consistency
-    def self.render(object, **opts)
-      self.dump(object, **opts)
+    class << self
+      alias_method :render, :dump
     end
 
     # Internal finalize! logic
@@ -216,10 +228,17 @@ module Praxis
         self.define_readers!
         # Don't blindly override a master view if the MediaType wants to define it on its own
         self.generate_master_view! unless self.view(:master)
+        self.resolve_domain_model!
       end
       super
     end
 
+    def self.resolve_domain_model!
+      return unless self.domain_model.kind_of?(String)
+
+      @domain_model = self.domain_model.constantize
+    end
+
     def self.define_attribute!
       @attribute = Attributor::Attribute.new(Attributor::Struct, @options, &@block)
       @block = nil
@@ -256,13 +275,14 @@ module Praxis
     end
 
 
+
     def self.generate_master_view!
       attributes = self.attributes
       view :master do
         attributes.each do | name, attr |
           # Note: we can freely pass master view for attributes that aren't blueprint/containers because
           # their dump methods will ignore it (they always dump everything regardless)
-          attribute name, view: :master
+          attribute name, view: :default
         end
       end
     end
@@ -271,69 +291,50 @@ module Praxis
     def initialize(object, decorators=nil)
       # TODO: decide what sort of type checking (if any) we want to perform here.
       @object = object
+
       @decorators = if decorators.kind_of?(Hash) && decorators.any?
         OpenStruct.new(decorators)
       else
         decorators
       end
-      @rendered_views = {}
-      @validating = false
 
-      # OPTIMIZE: revisit the circular rendering tracking.
-      #           removing this results in a significant performance
-      #           and memory use savings.
-      @active_renders = []
+      @validating = false
     end
 
 
     # Render the wrapped data with the given view
-    def render(view_name=nil, context: Attributor::DEFAULT_ROOT_CONTEXT,**opts)
+    def render(view_name=nil, context: Attributor::DEFAULT_ROOT_CONTEXT,renderer: Renderer.new, **opts)
       if view_name != nil
         warn "DEPRECATED: please do not pass the view name as the first parameter in Blueprint.render, pass through the view: named param instead."
-      else
-        view_name = :default # Backwards compatibility with the default param value
+      elsif opts.key?(:view)
+        view_name = opts[:view]
       end
 
-      # Allow the opts to specify the view name for consistency with dump (overriding the deprecated named param)
-      view_name = opts[:view] if opts[:view]
-      unless (view = self.class.views[view_name])
-        raise "view with name '#{view_name.inspect}' is not defined in #{self.class}"
+      fields = opts[:fields]
+      if view_name.nil? && fields.nil?
+        view_name = :default
       end
 
-      rendered_key = if (fields = opts[:fields])
-        if fields.is_a? Array
-          # Accept a simple array of fields, and transform it to a 1-level hash with nil values
-          opts[:fields] = opts[:fields].each_with_object({}) {|field, hash| hash[field] = nil }
+
+      if view_name
+        unless (view = self.class.views[view_name])
+          raise "view with name '#{view_name.inspect}' is not defined in #{self.class}"
         end
-        # Rendered key needs to be different if only some fields were output
-        "%s:#%s" % [view_name, opts[:fields].hash.to_s]
-      else
-        view_name
+        return view.render(self, context: context, renderer: renderer)
       end
 
-      return @rendered_views[rendered_key] if @rendered_views.has_key? rendered_key
-      return CIRCULAR_REFERENCE_MARKER if @active_renders.include?(rendered_key)
-      @active_renders << rendered_key
-
-      notification_payload = {
-        blueprint: self,
-        view: view,
-        fields: fields
-      }
-
-      ActiveSupport::Notifications.instrument 'praxis.blueprint.render'.freeze,  notification_payload do
-        @rendered_views[rendered_key] = view.dump(self, context: context,**opts)
+      # Accept a simple array of fields, and transform it to a 1-level hash with true values
+      if fields.is_a? Array
+        fields = fields.each_with_object({}) {|field, hash| hash[field] = true }
       end
-    ensure
-      @active_renders.delete rendered_key
-    end
-    alias_method :to_hash, :render
 
+      # expand fields
+      expanded_fields = FieldExpander.expand(self.class, fields)
 
-    def dump(view: :default, context: Attributor::DEFAULT_ROOT_CONTEXT)
-      self.render(view: view, context: context)
+      renderer.render(self, expanded_fields, context: context)
     end
-
+    alias_method :to_hash, :render
+    alias_method :dump, :render
 
     def validate(context=Attributor::DEFAULT_ROOT_CONTEXT)
       raise ArgumentError, "Invalid context received (nil) while validating value of type #{self.name}" if context == nil
@@ -349,12 +350,17 @@ module Praxis
         if value.respond_to?(:validating) # really, it's a thing with sub-attributes
           next if value.validating
         end
-        errors.push *sub_attribute.validate(value, sub_context)
+        errors.push(*sub_attribute.validate(value, sub_context))
       end
     ensure
       @validating = false
     end
 
+    # generic semi-private getter used by Renderer
+    def _get_attr(name)
+      self.send(name)
+    end
+
   end
 
 end

data/lib/praxis-blueprints/collection_view.rb

@@ -1,30 +1,27 @@
 module Praxis
 
-  class CollectionView
-    attr_reader :name, :schema, :using
+  class CollectionView < View
+    def initialize(name, schema, member_view=nil)
+      super(name,schema)
 
-    def initialize(name, schema, using)
-      @name = name
-      @schema = schema
-      @using = using
-    end
-
-    def dump(collection, context: Attributor::DEFAULT_ROOT_CONTEXT,**opts)
-      collection.collect.with_index do |object, i|
-        subcontext = context + ["at(#{i})"]
-        using.dump(object, context: subcontext, **opts)
+      if member_view
+        @contents = member_view.contents.clone
       end
     end
 
     def example(context=Attributor::DEFAULT_ROOT_CONTEXT)
-      collection = self.schema.example(context)
+      collection = 3.times.collect do |i|
+        subcontext = context + ["at(#{i})"]
+        self.schema.example(subcontext)
+      end
       opts = {}
       opts[:context] = context if context
-      self.dump(collection, opts)
+
+      self.render(collection, **opts)
     end
 
     def describe
-      using.describe.merge(type: :collection)
+      super.merge(type: :collection)
     end
 
   end

data/lib/praxis-blueprints/field_expander.rb

@@ -0,0 +1,104 @@
+module Praxis
+  class FieldExpander
+    class CircularExpansionError < StandardError
+      attr_reader :stack
+      def initialize(message, stack=[])
+        super(message)
+        @stack = stack
+      end
+    end
+
+    def self.expand(object, fields=true)
+      self.new.expand(object,fields)
+    end
+
+    attr_reader :stack
+    attr_reader :history
+
+    def initialize
+      @stack = Hash.new do |hash, key|
+        hash[key] = Set.new
+      end
+      @history = Hash.new do |hash,key|
+        hash[key] = Hash.new
+      end
+    end
+
+    def expand(object, fields=true)
+      if stack[object].include? fields
+        raise CircularExpansionError, "Circular expansion detected for object #{object.inspect} with fields #{fields.inspect}"
+      else
+        stack[object] << fields
+      end
+
+      if object.kind_of?(Praxis::View)
+        self.expand_view(object, fields)
+      elsif object.kind_of? Attributor::Attribute
+        self.expand_type(object.type, fields)
+      else
+        self.expand_type(object,fields)
+      end
+    rescue CircularExpansionError => e
+      e.stack.unshift [object,fields]
+      raise
+    ensure
+      stack[object].delete fields
+    end
+
+    def expand_fields(attributes, fields)
+      raise ArgumentError, "expand_fields must be given a block" unless block_given?
+
+      unless fields == true
+        attributes = attributes.select do |k,v|
+          fields.key?(k)
+        end
+      end
+
+      attributes.each_with_object({}) do |(name, dumpable), hash|
+        sub_fields = case fields
+          when true
+            true
+          when Hash
+            fields[name] || true
+          end
+        hash[name] = yield(dumpable,sub_fields)
+      end
+    end
+
+
+    def expand_view(object,fields=true)
+      result = expand_fields(object.contents, fields) do |dumpable, sub_fields|
+        self.expand(dumpable, sub_fields)
+      end
+
+      return [result] if object.kind_of?(Praxis::CollectionView)
+      result
+    end
+
+
+    def expand_type(object,fields=true)
+      unless object.respond_to?(:attributes)
+        if object.respond_to?(:member_attribute)
+          fields = fields[0] if fields.kind_of? Array
+          return [self.expand(object.member_attribute.type, fields)]
+        else
+          return true
+        end
+      end
+
+      # just include the full thing if it has no attributes
+      if object.attributes.empty?
+        return true
+      end
+
+      if history[object].include? fields
+        return history[object][fields]
+      end
+
+      history[object][fields] = expand_fields(object.attributes, fields) do |dumpable, sub_fields|
+        self.expand(dumpable.type, sub_fields)
+      end
+    end
+
+  end
+end