praxis-blueprints 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 37262e51d6ade8fa158c9d9f6de290736a0b3a51
+  data.tar.gz: a6a308d7b28643974c4226153be1a0414a84084d
+SHA512:
+  metadata.gz: 850cecb7dbc21a95ec11b7a055bcdb21238d436bcf9c51d26901d3c371fc507629d2ebe22afccdc21f75d855c9260afc696b51fdbc2bfee9c3936a1d7fefdcca
+  data.tar.gz: 50745d11696618b5d276415608d4e7a6e25815d75d272abb6525e8d40ff00e71dde1afa782a51fae307417b92aa873e374ae0103a218ab37e5d68324ce25e979

data/.gitignore

@@ -0,0 +1,28 @@
+*.swp
+*.swo
+
+# YARD
+.yardoc
+
+# Gemfile
+*.gem
+
+# Code coverage
+coverage
+
+# RConf
+.ruby-version
+
+# Bundler
+.bundle
+
+# Mac OSX files
+.DS_Store
+
+bin
+
+.idea
+
+tmp/
+
+Gemfile.lock

data/.rspec

@@ -0,0 +1,3 @@
+--colour
+--format=Fuubar
+--backtrace

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - "2.1.2"
+script: bundle exec rspec spec

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# praxis-blueprints changelog
+
+## 1.0
+
+Initial release!

data/Gemfile

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

data/Guardfile

@@ -0,0 +1,11 @@
+# Config file for Guard
+# More info at https://github.com/guard/guard#readme
+
+guard :rspec, cmd: 'bundle exec rspec' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/praxis-blueprints/(.+)\.rb$}) { |m| "spec/praxis-blueprints/#{m[1]}_spec.rb" }
+  watch('spec/*.rb')  { 'spec' }
+  watch('lib/praxis-blueprints.rb') { 'spec' }
+  watch(%r{^spec/support/(.+)\.rb$}) { 'spec' }
+end
+

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2014 RightScale
+
+MIT License
+
+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/README.md

@@ -0,0 +1,36 @@
+# Praxis Blueprints
+
+Praxis Blueprints is a library that allows for defining a reusable class structures that has a set of typed attributes and a set of views with which to render them. Instantiations of Blueprints resemble ruby Structs which respond to methods of the attribute names. Rendering is format-agnostic in that
+it results in a structured hash instead of an encoded string. Blueprints can automatically generate object structures that follow the attribute definitions.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'praxis-blueprints'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install praxis-blueprints
+
+## Usage
+
+Documentation coming soon.
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/praxis-blueprints/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## License
+
+This software is released under the [MIT License](http://www.opensource.org/licenses/MIT). Please see  [LICENSE](LICENSE) for further details.
+
+Copyright (c) 2014 RightScale

data/Rakefile

@@ -0,0 +1,16 @@
+require 'bundler/setup'
+
+require "bundler/gem_tasks"
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+desc "Run RSpec code examples with simplecov"
+RSpec::Core::RakeTask.new do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/lib/praxis-blueprints/blueprint.rb

@@ -0,0 +1,330 @@
+require 'ostruct'
+
+# Blueprint ==
+#   - part implementation definition for attributes
+#   - part container for views
+module Praxis
+  class Blueprint
+    include Attributor::Type
+    extend Finalizable
+
+    @@caching_enabled = false
+
+    CIRCULAR_REFERENCE_MARKER = '...'.freeze
+
+    attr_accessor :object, :decorators
+    attr_reader :validating, :active_renders
+
+    class << self
+      attr_reader :views, :attribute, :options
+      attr_accessor :reference
+    end
+
+    def self.inherited(klass)
+      super
+
+      klass.instance_eval do
+        @views = Hash.new
+        @options = Hash.new
+      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.blueprint_cache[self]
+        else
+          self.cache
+        end
+
+        return cache[key] ||= begin
+          blueprint = self.allocate
+          blueprint.send(:initialize, object, decorators)
+          blueprint
+        end
+      end
+
+      blueprint = self.allocate
+      blueprint.send(:initialize, object, decorators)
+      blueprint
+    end
+
+
+    def self.describe(shallow=false)
+      type_name = self.ancestors.find { |k| k.name && !k.name.empty? }.name
+
+      description = self.attribute.type.describe(shallow).merge!(name: type_name)
+
+      unless shallow
+        description[:views] = self.views.each_with_object({}) do |(view_name, view), hash|
+          hash[view_name] = view.describe
+        end
+      end
+      
+      description
+    end
+
+
+    def self.attributes(opts={}, &block)
+      if block_given?
+        if self.const_defined?(:Struct, false)
+          raise "Redefining Blueprint attributes is not currently supported"
+        else
+
+          if opts.has_key?(:reference) && opts[:reference] != self.reference
+            raise "Reference mismatch in #{self.inspect}. Given :reference option #{opts[:reference].inspect}, while using #{self.reference.inspect}"
+          elsif self.reference
+            opts[:reference] = self.reference #pass the reference Class down
+          else
+            opts[:reference] = self
+          end
+
+          @options = opts
+          @block = block
+        end
+
+        return @attribute
+      end
+
+      unless @attribute
+        raise "@attribute not defined yet for #{self.name}"
+      end
+
+      @attribute.attributes
+    end
+
+
+    def self.check_option!(name, value)
+      case name
+      when :identity
+        raise Attributor::AttributorException, "Invalid identity type #{value.inspect}" unless value.kind_of?(::Symbol)
+        return :ok
+      else
+        return Attributor::Struct.check_option!(name, value)
+      end
+    end
+
+
+    def self.load(value,context=Attributor::DEFAULT_ROOT_CONTEXT, **options)
+      case value
+      when nil, self
+        value
+      when Hash, String
+        # Need to parse/deserialize first
+        self.new(self.attribute.load(value,context, **options))
+      else
+        # Just wrap whatever value
+        self.new(value)
+      end
+    end
+
+
+    def self.caching_enabled?
+      @@caching_enabled
+    end
+
+    def self.caching_enabled=(caching_enabled)
+      @@caching_enabled = caching_enabled
+    end
+
+    # Fetch current blueprint cache, scoped by this class
+    def self.cache
+      Thread.current[:praxis_blueprints_cache][self]
+    end
+
+    def self.cache=(cache)
+      Thread.current[:praxis_blueprints_cache] = cache
+    end
+
+    def self.valid_type?(value)
+      # FIXME: this should be more... ducklike
+      value.kind_of?(self) || value.kind_of?(self.attribute.type)
+    end
+
+    def self.example(context=nil, **values)
+      context = case context
+      when nil
+        ["#{self.name}-#{values.object_id.to_s}"]
+      when ::String
+        [context]
+      else
+        context
+      end
+
+      self.new(self.attribute.example(context, values: values))
+    end
+
+
+    def self.validate(value, context=Attributor::DEFAULT_ROOT_CONTEXT, _attribute=nil)
+
+      raise ArgumentError, "Invalid context received (nil) while validating value of type #{self.name}" if context == nil
+      context = [context] if context.is_a? ::String
+
+      unless value.kind_of?(self)
+        raise ArgumentError, "Error validating #{Attributor.humanize_context(context)} as #{self.name} for an object of type #{value.class.name}."
+      end
+
+      value.validate(context)
+    end
+
+
+    def self.view(name, &block)
+      if block_given?
+        return self.views[name] = View.new(name, self, &block)
+      end
+
+      self.views[name]
+    end
+
+    def self.dump(object, view: :default, context: Attributor::DEFAULT_ROOT_CONTEXT, **opts)
+      object = self.load(object, context)
+      object.render(view, context: context)
+    end
+
+
+    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 = []
+    end
+
+
+    # Render the wrapped data with the given view
+    def render(view_name=:default, context: Attributor::DEFAULT_ROOT_CONTEXT)
+      unless (view = self.class.views[view_name])
+        raise "view with name '#{view_name.inspect}' is not defined in #{self.class}"
+      end
+
+      return @rendered_views[view_name] if @rendered_views.has_key? view_name
+      return CIRCULAR_REFERENCE_MARKER if @active_renders.include?(view_name)
+      @active_renders << view_name
+
+      @rendered_views[view_name] = view.dump(self, context: context)
+    ensure
+      @active_renders.delete view_name
+    end
+
+
+    alias_method :to_hash, :render
+
+
+    def dump(view: :default, context: Attributor::DEFAULT_ROOT_CONTEXT)
+      self.render(view, context: context)
+    end
+
+    # Internal finalize! logic
+    def self._finalize!
+      if @block
+        self.define_attribute!
+        self.define_readers!
+        self.generate_master_view!
+      end
+      super
+    end
+
+    def self.define_attribute!
+      @attribute = Attributor::Attribute.new(Attributor::Struct, @options, &@block)
+      @block = nil
+      self.const_set(:Struct, @attribute.type)
+    end
+
+    def self.define_readers!
+      self.attributes.each do |name, attribute|
+        name = name.to_sym
+
+        # Don't redefine existing methods
+        next if self.instance_methods.include? name
+
+        define_reader! name
+      end
+    end
+
+
+    def self.define_reader!(name)
+      attribute = self.attributes[name]
+      if attribute.type < Praxis::Blueprint
+        define_blueprint_reader!(name)
+      else
+        define_direct_reader!(name)
+      end
+    end
+
+    def self.define_blueprint_reader!(name)
+      # it's faster to use define_method in this case than module_eval
+      # because we save the attribute lookup on every access.
+      attribute = self.attributes[name]
+      define_method(name) do
+       if @decorators && @decorators.respond_to?(name)
+         @decorators.send(name)
+       else
+         value = @object.send(name)
+         return value if value.nil? || value.kind_of?(attribute.type)
+         attribute.type.new(value)
+       end
+      end
+    end
+
+    def self.define_direct_reader!(name)
+      module_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{name}
+          if @decorators && @decorators.respond_to?(:#{name})
+            @decorators.#{name}
+          else
+            @object.#{name}
+          end
+        end
+      RUBY
+    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
+        end
+      end
+    end
+
+
+    def validate(context=Attributor::DEFAULT_ROOT_CONTEXT)
+
+      raise ArgumentError, "Invalid context received (nil) while validating value of type #{self.name}" if context == nil
+      context = [context] if context.is_a? ::String
+
+      raise "validation conflict" if @validating
+      @validating = true
+
+
+      self.class.attributes.each_with_object(Array.new) do |(sub_attribute_name, sub_attribute), errors|
+        sub_context = self.class.generate_subcontext(context,sub_attribute_name)
+        value = self.send(sub_attribute_name)
+
+        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)
+      end
+    ensure
+      @validating = false
+    end
+
+
+  end
+
+end

data/lib/praxis-blueprints/config_hash.rb

@@ -0,0 +1,40 @@
+module Praxis
+  class ConfigHash < BasicObject
+
+    attr_reader :hash
+
+    def self.from(hash={},&block)
+      self.new(hash,&block)
+    end
+
+    def initialize(hash={},&block)
+      @hash = hash
+      @block = block
+    end
+
+    def to_hash
+      self.instance_eval(&@block)
+      @hash
+    end
+
+    def method_missing(name, value, *rest, &block)
+      if (existing = @hash[name])
+        if block
+          existing << [value, block]
+        else
+          existing << value
+          rest.each do |v|
+            existing << v
+          end
+        end
+      else
+        if rest.any?
+          @hash[name] = [value] + rest
+        else
+          @hash[name] = value
+        end
+      end
+    end
+
+  end
+end

data/lib/praxis-blueprints/finalizable.rb

@@ -0,0 +1,38 @@
+module Praxis
+  module Finalizable
+
+
+    def self.extended(klass)
+      klass.module_eval do
+        @finalizable = Set.new
+      end
+    end
+
+    def inherited(base)
+      @finalizable << base
+      base.instance_variable_set(:@finalizable, @finalizable)
+      base.instance_variable_set(:@finalized, false)
+    end
+
+    def finalizable
+      @finalizable
+    end
+
+    def finalized?
+      @finalized
+    end
+
+    def _finalize!
+      @finalized = true
+    end
+
+    def finalize! 
+      self.finalizable.reject(&:finalized?).each do |klass|
+        klass._finalize!
+      end
+
+      self.finalize! unless self.finalizable.all?(&:finalized?)
+    end
+
+  end
+end

data/lib/praxis-blueprints/version.rb

@@ -0,0 +1,3 @@
+module Praxis
+  BLUEPRINTS_VERSION = "1.0.0"
+end

data/lib/praxis-blueprints/view.rb

@@ -0,0 +1,93 @@
+module Praxis
+
+  class View
+    attr_reader :schema, :contents, :name
+
+
+    def initialize(name, schema, &block)
+      @name = name
+      @schema = schema
+      @contents = ::Hash.new
+      @block = block
+    end
+
+
+    def contents
+      if @block
+        self.instance_eval(&@block)
+        @block = nil
+      end
+
+      @contents
+    end
+
+
+    def dump(object, context: Attributor::DEFAULT_ROOT_CONTEXT,**opts)
+      self.contents.each_with_object({}) do |(name, (dumpable, dumpable_opts)), hash|
+        next unless object.respond_to?(name)
+
+        begin
+          value = object.send(name)
+        rescue => e
+          raise Attributor::DumpError, context: context, name: name, type: object.class, original_exception: e
+        end
+        next if value.nil?
+        
+        # FIXME: this is such an ugly way to do this. Need attributor#67.
+        if dumpable.kind_of?(View)
+          new_context = context + [name]
+          hash[name] = dumpable.dump(value, context: new_context ,**(dumpable_opts||{}))
+        else
+          type = dumpable.type
+          if type.respond_to?(:attributes) || type.respond_to?(:member_attribute)
+            new_context = context + [name]
+            hash[name] = dumpable.dump(value, context: new_context ,**(dumpable_opts||{}))
+          else
+            hash[name] = value
+          end
+        end
+      end
+    end
+    alias_method :to_hash, :dump
+
+
+    def attribute(name, opts={}, &block)
+      raise AttributorException, "Attribute names must be symbols, got: #{name.inspect}" unless name.kind_of? ::Symbol
+
+      attribute = self.schema.attributes.fetch(name) do
+        raise "Attribute '#{name}' does not exist in #{self.schema}"
+      end
+
+      if block_given?
+        view = View.new(name, attribute, &block)
+        @contents[name] = view
+      else
+        raise "Invalid options (#{opts.inspect}) for #{name} while defining view #{@name}" unless opts.is_a?(Hash)
+        @contents[name] = [attribute, opts]
+      end
+
+    end
+
+
+    def example(context=nil)
+      object = self.schema.example(context)
+      opts = {}
+      opts[:context] = context if context
+      self.dump(object, opts)
+    end
+
+    def describe
+      # TODO: for now we are just return the first level keys
+      view_attributes = {}
+
+      self.contents.each do |k,(dumpable,dumpable_opts)|
+        inner_desc = {}
+        inner_desc[:view] = dumpable_opts[:view] if dumpable_opts && dumpable_opts[:view]
+        view_attributes[k] = inner_desc
+      end
+
+      { attributes: view_attributes }
+    end
+
+  end
+end

data/lib/praxis-blueprints.rb

@@ -0,0 +1,14 @@
+require 'json'
+require 'yaml'
+require 'logger'
+
+require 'attributor'
+
+require "praxis-blueprints/version"
+
+require 'praxis-blueprints/finalizable'
+require 'praxis-blueprints/config_hash'
+
+require 'praxis-blueprints/blueprint'
+require 'praxis-blueprints/view'
+