seat-belt 0.10.0

data/lib/seatbelt/core/property.rb

@@ -0,0 +1,161 @@
+module Seatbelt
+  module Property
+    module ClassMethods
+      
+      # Public: Defines an API property. This is only working if its called within
+      # the #interface method block.
+      #
+      # Wraps Seatbelt::Pool::Api#api_method with a getter and setter method name.
+      #
+      # *args - An argument list containing:
+      #         name    - Name of the API property (required)
+      #         options - An optional options Hash containing:
+      #                   :accessible - Property is mass assignable 
+      #                                 (defaults to false)
+      #
+      # Examples:
+      #
+      #   class Book
+      #     interface :instance do
+      #       define_property :author
+      #       define_property :title
+      #     end
+      #   end
+      def define_property(*args)
+        if @scope.eql?(:class)
+          raise Seatbelt::Errors::PropertyOnClassLevelDefinedError
+        end
+        hsh         = {}
+        options     = args.extract_options!
+        accessible  = options.fetch(:accessible, false)
+        name        = args.pop
+        hsh[:scope] = @scope
+
+        self.send(:api_method, name, hsh)
+        hsh[:args] = [:value]
+        self.send(:api_method, :"#{name}=", hsh)
+
+        property_list << name
+        self.send(:property_accessible, name) if accessible
+
+      end
+
+      # Public: Mass defining of properties.
+      #
+      # See #define_property for details
+      #
+      # - properties - A list of property names to define.
+      #
+      def define_properties(*properties)
+        properties.each { |property| define_property(property) }
+      end
+
+      # Public: All properties that are marked as accessible.
+      #
+      # Returns the property list or an empty Array.
+      def accessible_properties
+        @accessible_properties ||= []
+      end
+
+      # Public: Defines one or more properties to be mass assignable due
+      # the #properties= setter method.
+      #
+      # If the class implements an #attributes method (e.g. coming from 
+      # Seatbelt::Document) these attributes are includeable in this list too.
+      #
+      # properties - A list of property names. Requires at least one property.
+      #
+      def property_accessible(*properties)
+        properties.each do |property|
+          attribute_defined = false
+          if self.respond_to?(:attributes)  
+            if self.attribute_set.map(&:name).include?(property)
+              attribute_defined = true
+            end 
+          end
+          unless attribute_defined 
+            unless property_list.include?(property) && !attribute_defined
+              raise Seatbelt::Errors::PropertyNotDefinedYetError.new(property)
+            end
+          end
+          accessible_properties << property
+        end
+      end
+
+      private
+
+      # Internal: All properties of the class defined with #define_property.
+      #
+      # Returns the the properties as Array or an empty Array.
+      def property_list
+        @property_list ||= []
+      end
+
+    end
+
+    module InstanceMethods
+
+      require 'active_support/core_ext/hash/keys'
+
+      # Public: Gets a list of key-value pairs that includes the properties
+      # with its values.
+      #
+      # role -  The scope of properties that will be selected 
+      #         Defaults to :accessibles which will only select properties that 
+      #         are defined as accessible.
+      #
+      # Returns an Hash containing the property names and its values. 
+      def properties(role = :accessibles)
+        injector = lambda do |result, item|
+          result[item] = self.send(item)
+          result
+        end
+        list = case role
+          when :accessibles then
+            self.class.accessible_properties.inject({}, &injector)
+          when :all then
+            all = self.class.send(:property_list).inject({}, &injector)
+            all.merge!(attributes) if self.respond_to?(:attributes)
+            all
+          else
+            {}
+        end
+        list.with_indifferent_access
+      end
+
+      # Public: Sets a bunch of properties that are marked as accessible.
+      #
+      # property_hsh -  The Hash containing the property name and the property 
+      #                 value.
+      #
+      # Examples
+      #
+      #   class Car
+      #     include Seatbelt::Ghost
+      #
+      #     interface :instance do 
+      #       define_property :wheels
+      #       define_property :color
+      #       
+      #       property_accessible :color
+      #     end
+      #   end
+      #   
+      #   car = Car.new
+      #   car.properties = { :color => "yellow", :wheels => 3 }
+      #   
+      #   car.color   # => 'yellow' because it's accessible
+      #   car.wheels  # => nil because it's not accessible
+      #
+      def properties=(property_hsh)
+        property_hsh.each do |property_key, property_value|
+          if self.class.accessible_properties.include?(property_key) || \
+            self.class.accessible_properties.map(&:to_s).include?(property_key)
+            self.send("#{property_key}=", property_value)
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/seatbelt/core/proxy.rb

@@ -0,0 +1,135 @@
+module Seatbelt
+
+  # Public: A Seatbelt::Proxy class is a shadow of any class that includes
+  # Seatbelt::Gate.
+  # It provides access to the API class or instance of the API class and
+  # implements the DynamicProxy pattern.
+  #
+  # A Proxy class provides a private dynamic accessor #klass that changes with
+  # the implementation scope of the API methods implementation.
+  #
+  # Let's show this by example:
+  #
+  # class ApiClass
+  #   include Seatbelt::Ghost
+  #
+  #   api_method :an_instance_method_to_implement
+  #   api_method :a_class_method_to_implement
+  #   def helper(a,b,c)
+  #     #....
+  #   end
+  #
+  #   def self.c_helper(options={})
+  #     # ...
+  #   end
+  # end
+  #
+  # class ApiClassImplementation
+  #
+  #   def instance_implementation
+  #     local = proxy.call(:helper, 1,2,4) # proxy scope is instance of ApiClass
+  #   end
+  #   implement :instance_implementation,
+  #             :as => "ApiClass#an_instance_method_to_implement"
+  #
+  #   def class_implementation
+  #     local = proxy.call(:c_helper, {:foo => 19})
+  #     # proxy scope is ApiClass
+  #   end
+  #   implement :class_implementation,
+  #             :as => "ApiClass.a_class_method_to_implement"
+  # end
+  class Proxy
+
+    NOT_ALLOWABLE_CALLS_ON_OBJECT = %w{ call object klass tunnel }
+
+    # Public: Send a method message to the current #klass scope receiver.
+    # See class documentation section for further informations about #klass.
+    #
+    # method_name - The method to call
+    # *args       - The methods argument list
+    # &block      - An optional block that should be passed to the callable
+    #               method
+    #
+    # Returns the return value of the callable method or raises a
+    # NoMethodError.
+    def call(method_name, *args, &block)
+      object.send(method_name,*args,&block)
+    end
+
+    def object
+      self.send(:klass)
+    end
+    
+    # Public: Calls a private API attribute or method of an object defined
+    # in a API class. 
+    #
+    # It is only working on a second level.
+    #
+    # chain - The attribute call chain as String.
+    #
+    # Example:
+    #
+    # class ApiA
+    #   include Seatbelt::Document
+    #   include Seatbelt::Ghost
+    #
+    #   has :b, "Models::B"
+    #
+    # end
+    #
+    # class Models::B
+    #   include Seatbelt::Document
+    #   include Seatbelt::Ghost
+    #
+    #   # definitions
+    #
+    # end
+    #
+    # class ImplementationB 
+    #   field :name, :type => String
+    # end
+    # 
+    # In a implementation method of ApiA
+    #
+    # proxy.tunnel("b.name")
+    #
+    #
+    # Returns the duplicated String.
+    def tunnel(chain)
+      proxy_associated_object,object_method = chain.split(".")
+      unless object.respond_to?(proxy_associated_object) 
+        raise Seatbelt::Errors::ObjectDoesNotExistError 
+      else
+        tunneled_object = object.send(proxy_associated_object)
+        callees         = tunneled_object.eigenmethods.map do |eigenmethod|
+          eigenmethod.send(:callee)
+        end
+      
+        callee = callees.uniq.first
+        unless callee.nil?
+          unless object_method
+            warn "You called a single object. Use #call instead." 
+            object_method = proxy_associated_object
+          end
+          return callee.send(object_method)
+        else
+          raise Seatbelt::Errors::MethodNotImplementedError
+        end
+      end
+    end
+
+    # Public: Delegates a method message to the #object receiver if the
+    # message is not included in NOT_ALLOWABLE_CALLS_ON_OBJECT or the
+    # class responds to.
+    def method_missing(method_name, *args, &block)
+      unless method_name.to_s.in?(NOT_ALLOWABLE_CALLS_ON_OBJECT) &&
+        (not self.respond_to?(method_name))
+        self.call(method_name, *args, &block)
+      else
+        super
+      end
+    end
+
+  end
+end

data/lib/seatbelt/core/synthesizeable.rb

@@ -0,0 +1,50 @@
+module Seatbelt
+  module Synthesizeable
+    extend self
+
+    # Public: Combined getter and setter for a map of attributes that should
+    # be used for synthesizing the proxy and the implementation object.
+    #
+    # map=nil - a Hash of proxy attributes as keys and implementation object
+    #           attributes as values.
+    #
+    # If map is nil, it returns the synthesize map (or an Empty hash if not
+    # previously set).
+    def synthesize_map(map=nil)
+      if map.nil?
+        return @synthesize_map ||={}
+      else
+        @synthesize_map=map
+      end
+    end
+
+    # Public: Defines a synthesizer for the implementation class. It takes an
+    # Hash argument to define the class the object should by synthesized and
+    # an additional adapter.
+    #
+    # options - A Hash containing synthesize configurations
+    #           :from   - The class the implementation and proxy object has to
+    #                     synthesized (String or Constant)
+    #           :adapter- An optional class name that points to a implemented
+    #                     Synthesizer. Defaults to
+    #                     Seatbelt::Synthesizers::Document
+    #
+    def synthesize(options)
+      klass_to_synthesize = options[:from]
+      synthesize_adapter  = options.fetch(:adapter,
+                                          "Seatbelt::Synthesizers::Document")
+      synthesize_adapter  = Module.const_get(synthesize_adapter)
+      unless klass_to_synthesize.respond_to?(:name)
+        klass_to_synthesize = Module.const_get(klass_to_synthesize)
+      end
+      synthesize_obj = {:klass => klass_to_synthesize.name,
+                        :adapter => synthesize_adapter}
+      klass_to_synthesize.class.class_eval do
+        def synthesizers
+          @synthesizers ||= []
+        end
+      end
+      klass_to_synthesize.synthesizers << synthesize_obj
+    end
+  end
+end

data/lib/seatbelt/core/terminal.rb

@@ -0,0 +1,59 @@
+module Seatbelt
+
+  # Public: Interface between API class and Implementation class.
+  # Calls the implementation of an API method with passed arguments and block.
+  #
+  class Terminal
+    # The implementation methods config store.
+    def self.luggage=(luggage_pack)
+      @luggage = luggage_pack
+    end
+
+    # Public: The implementation methods config store.
+    #
+    # Returns implementation methods config store.
+    def self.luggage
+      @luggage ||= []
+    end
+
+    def self.for_scope_and_namespace(scope, namespace)
+      Terminal.luggage.select do |package|
+        package.scope_level.eql?(scope) && package.namespace.eql?(namespace)
+      end
+    end
+
+
+    # Public: calls the implementation of an API method with passed arguments
+    # and block.
+    # Before sending the method message to the receiver, it defines the
+    # receivers proxy scope depending on klass (see below).
+    #
+    # action  -   The API method name to be called
+    # klass   -   The API class name on which the API method is declared
+    # arity   -   Number of required arguments
+    # *args   -   An argument list passed to the implementation method
+    # &block  -   An optional block passed to the implementation method.
+    #
+    # Returns the return value of the implementation method.
+    def self.call(action, klass, arity, *args, &block)
+      raise Seatbelt::Errors::MethodNotImplementedError if luggage.empty?
+      scope               = klass.class.eql?(Class) ? :class : :instance
+      klass_namespace     = scope.eql?(:class) ? klass.name : klass.class.name
+
+      eigenmethod = klass.eigenmethods.detect do |meth|
+        meth.implemented_as.eql?(action)
+      end
+
+      unless eigenmethod
+        raise Seatbelt::Errors::MethodNotImplementedError
+      end
+
+      if (not eigenmethod.delegated) && (not eigenmethod.arity.eql?(arity))
+        raise Seatbelt::Errors::ArgumentMissmatchError
+      end
+
+      eigenmethod.call(*args, &block)
+    end
+
+  end
+end

data/lib/seatbelt/dependencies.rb

@@ -0,0 +1,5 @@
+require 'active_support/core_ext/object/inclusion'
+require 'active_support/core_ext/string/inflections'
+require 'active_support'
+require 'virtus'
+require 'active_model'

data/lib/seatbelt/document.rb

@@ -0,0 +1,175 @@
+module Seatbelt
+
+  # Public: A Document is an interface to specify attributes for a API class.
+  # Accessing and setting attributes for an API class within an implementation
+  # class is possible during the proxy object.
+  #
+  # Example:
+  #
+  # class Airport
+  #   include Seatbelt::Ghost
+  #   include Seatbelt::Document
+  #
+  #   attribute :name,  String
+  #   attribute :lat,   Float
+  #   attribute :lng,   Float
+  #
+  #   api_method :identifier
+  #
+  # end
+  #
+  # class ImplementationKlass
+  #   include Seatbelt::Gate
+  #
+  #   def aiport_identifier
+  #     name = proxy.call(:name) # <= calls the Aiport attribute
+  #     return "airport_#{name}".underscore
+  #   end
+  #   implement :airport_identifier, :as => "Airport#identifier"
+  # end
+  #
+  # aiport = Airport.new(:name => "London Stansted")
+  # airport.identifier # => "airport_london_stansted"
+  #
+  # For more information about definining and working with attributes see
+  # 'Virtus' project page: https://github.com/solnic/virtus
+  #
+  # To have validations for attributes just implement ActiveModel validations.
+  # For more informations about that see the ActiveModel validations docs:
+  # http://api.rubyonrails.org/classes/ActiveModel/Validations.html
+  #
+  # Example
+  #
+  # class Airport
+  #   include Seatbelt::Ghost
+  #   include Seatbelt::Document
+  #
+  #   attribute :name,  String
+  #   attribute :lat,   Float
+  #   attribute :lng,   Float
+  #
+  #   validates_presence_of :name
+  #
+  #   api_method :identifier
+  #
+  #  end
+  #
+  # For associations between Documents see Association module below.
+  module Document
+
+    def self.included(base)
+      base.class_eval do
+        include ::Virtus.model
+        include ::ActiveModel::Validations
+        extend Document::Associations
+      end
+    end
+
+
+    # Associations are a set of macro-like class methods for tying Ruby objects
+    # together.
+    # Each macro adds a getter and setter method that expresses the realtionship
+    # depending on its type.
+    # A 'has_many' relation defines an Array of models that also acts just the
+    # same as the definition says.
+    # A 'has' relation defines a single relation to another Ruby object.
+    #
+    # Note that every Class used for associations has to include
+    # Seatbelt::Document.
+    #
+    # A little bit more about 'has_many':
+    #
+    # The resulting 'has_many' Array is an abstraction of
+    # Virtus::Attribute::Collection.
+    #
+    # If it's defined
+    #
+    # has_many :horses, Horse
+    #
+    # Seatbelt awaits a collection definition like:
+    #
+    # module Seatbelt
+    #   module Collections
+    #     class HorseCollection < Seatbelt::Collections::Collection
+    #       # do smth
+    #     end
+    #   end
+    # end
+    #
+    # The most important part is the collections namespace, it should be
+    # prefixed with Seatbelt::Collections. The collection itself has to
+    # implement a Virtus::Attribute.
+    #
+    module Associations
+
+      # Public: Defines a 1:n association.
+      #
+      # That is - in fact - an Array of models. There is no "other side" like
+      # it's known from ActiveRecord or Mongoid.
+      #
+      # collection_name   - The name of the collection. That will be also the
+      #                     name of accessor method.
+      # collection_model -  The model class used for this collection.
+      #
+      # The resulting accessor method as like an Array, with some features:
+      #
+      # Adding a model to the relationship awaits an instance of the class
+      # defined in 'collection_model' (otherwise a
+      # Seatbelt::Errors::TypeMissmatchError is raised) or a hash of attribute
+      # values. Any attributes included in this Hash that are not defined
+      # within the model are ignored.
+      #
+      # Example
+      #
+      #   module HorseFarm
+      #     module Models
+      #       class Barnstable
+      #         include Seatbelt::Document
+      #
+      #         has_many :horses, HorseFarm::Models::Horse
+      #
+      #       end
+      #     end
+      #   end
+      def has_many(collection_name, collection_model)
+        model_name              = collection_model.name.to_s.demodulize
+        collection_module_name  = "Seatbelt::Collections::#{model_name}Collection"
+        collection              = Module.const_get(collection_module_name)
+        collection.initialize_primitive(collection_model)
+        self.send(:attribute, collection_name, collection[collection_model])
+      end
+
+      # Public: Defines a single reference to another Seatbelt::Document class.
+      #
+      # reference_name        - The name of the reference that will be also the
+      #                         name of accessor method
+      # attribute_type = nil  - The reference attribute type (optional).
+      #                         If the attribute type if omitted
+      #                         Seabelt::Models::[reference_name class name] is
+      #                         used.
+      #
+      # Example
+      #
+      #   module HorseFarm
+      #     module Models
+      #       class Horse
+      #         include Seatbelt::Document
+      #
+      #         # needs Seatbelt::Models::Horse
+      #         has :horseman
+      #         has :barnstable, HorseFarm::Models::Barnstable
+      #       end
+      #     end
+      #   end
+      #
+      def has(reference_name, attribute_type = nil)
+        unless attribute_type
+          attribute_type = "Seatbelt::Models::#{reference_name.to_s.classify}".
+                            constantize
+        end
+        self.send(:attribute, reference_name, attribute_type)
+      end
+
+    end
+  end
+end