seat-belt 0.10.0

data/lib/seatbelt/core/ghost_tunnel.rb

@@ -0,0 +1,81 @@
+module Seatbelt
+
+  # Public: Provides switches to enable accessing the implementation instance
+  # of an API class instances.
+  #
+  # Any API class that implements Seatbelt::Ghost can have access to its
+  # implementation class instance. This behaviour has to be enabled before using
+  # because its a violation of the Public/Private API approach.
+  #
+  # (And yes - in Ruby private methods are not really private methods.)
+  #
+  # Accessing the implementation instance is only available after the API Class
+  # was instantiated.
+  #
+  # Example:
+  #
+  # class Hotel
+  #   include Seatbelt::Ghost
+  #
+  #   enable_tunneling! # access to the implementation instance is not
+  #                     # possible.
+  #
+  # end
+  #
+  # class ImplementationHotel
+  #   include Seatbelt::Document
+  #   include Seatbelt::Gate
+  #
+  #   attribute :ignore_dirty_rooms, Boolean
+  #
+  # end
+  #
+  # hotel = new Hotel
+  # hotel.tunnel(:ignore_dirty_rooms=,false)
+  #
+  # Passing blocks is also available if the accessed method supports blocks
+  #
+  # class ImplementationHotel
+  #   include Seatbelt::Document
+  #   include Seatbelt::Gate
+  #
+  #   attribute :ignore_dirty_rooms, Boolean
+  #
+  #   def filter_rooms(sections)
+  #     rooms = self.rooms.map{|room| sections.include?(room_type)}
+  #     yield(rooms)
+  #   end
+  # end
+  #
+  # hotel.tunnel(:filter_rooms, ["shower, kitchen"]) do |rooms|
+  #   rooms.select do |room|
+  #     # do something
+  #   end
+  # end
+  module GhostTunnel
+    extend self
+
+    # Public: Enables tunnel support for an instance of API class.
+    #
+    # Defines the #tunnel method.
+    def enable_tunneling!
+      define_method :tunnel do |name, *args, &block|
+        callees = self.eigenmethods.map{|n| n.instance_variable_get(:@callee)}
+        unless callees.empty?
+          callee = callees.first
+          callee.send(name, *args, &block)
+        end
+      end
+    end
+
+    # Public: Disables tunnel support for an instance of API class.
+    #
+    # Removes the #tunnel method defined in #enable_tunneling! .
+    def disable_tunneling!
+      if self.instance_methods.include?(:tunnel)
+        remove_method(:tunnel)
+      end
+    end
+
+  end
+end

data/lib/seatbelt/core/implementation.rb

@@ -0,0 +1,158 @@
+module Seatbelt
+  module Gate
+    module Implementation
+
+      # Internal: Helper array to store method iterationable values.
+      def bulk_methods
+        @bulk_methods ||= []
+      end
+      private :bulk_methods
+      # Public: Provides definition for which class and object level (instance,
+      # class) the implementation methods match the API class methods.
+      #
+      # namespace - The API class (with complete namespace)
+      # scope     - The object level of 'namespace' [:instance, :class]
+      # &block    - The block that contains the implementation match
+      #             definitions.
+      #
+      # Example:
+      #
+      #   class ImplementHotel
+      #     include Seatbelt::Gate
+      #
+      #     implementation "Hotel", :class do
+      #       match 'implement_find_region' => 'find_nearby'
+      #     end
+      #
+      #     def implement_find_region(options)
+      #       #....
+      #     end
+      #   end
+      #
+      def implementation(namespace, scope, &block)
+        methods       = []
+        @_namespace     = namespace
+        @_scope       = Seatbelt::GateConfig.method_directives[scope]
+        yield(self)
+        iterator      = Core::Iterators::MethodConfig.
+                                send("array_method_iterator",@_namespace,
+                                     self,scope)
+        bulk_methods.each(&iterator)
+      end
+
+      # Public: Builds an Hash representation that is used by the method_added
+      # hook (Seatbelt::Gate::Classmethods) to find the implementation methods
+      # of a specific object level.
+      #
+      # If the argument includes a :superclass key with a truthy value,
+      # #implementation_from_superclass is called to simulate similiar behaviour
+      # to the method added hook.
+      #
+      # Examples:
+      #
+      #   implementation "Book", :instance do
+      #     match 'implementation_publishing' => 'publishing'
+      #     match 'implementation_paper_type' => 'paper_type',
+      #            :superclass => true
+      #   end
+      #
+      # hsh - An Hash containing the implementation method name as key and
+      #       the API method as value.
+      #       :superclass - defines that there will be an extra lookup for an
+      #                     implementation method in the class' superclass.
+      #                     (defaults to false)
+      def match(hsh)
+        hsh.stringify_keys!
+        superclass_definition = hsh.fetch("superclass", false)
+        delegate              = hsh.fetch("delegated", false)
+        hsh.delete("superclass")
+        implementation_method = hsh.keys.first.to_sym
+        remote_method         = hsh.values.first
+        if superclass_definition
+          config = {:as => "#{@_namespace}#{@_scope}#{remote_method}"}
+          self.send(:implementation_from_superclass,
+                    implementation_method, config)
+        end
+        imp_hsh = {
+          implementation_method => {:as => "#{@_scope}#{remote_method}"}
+        }
+        bulk_methods << imp_hsh
+        if delegate && @_scope.eql?("#")
+          notify_delgated_method(implementation_method, imp_hsh, remote_method)
+        end
+      end
+
+      # Public: Builds an Hash representation for property that is passed to
+      # #match(hsh)
+      #
+      # A property is an ivar that is accessible through a getter and setter.
+      #
+      # #match_property is only useable within the :instance scope,
+      #
+      # Examples:
+      #
+      #   # Having an identical property wthin the interface.
+      #   implementation "Book", :instance do
+      #     match_property 'author'
+      #   end
+      #
+      #   # Property names differ
+      #   implementation "Book", :instance do
+      #     match_property 'implementation_title' => 'title'
+      #   end
+      #
+      #   # Property is defined in the superclass
+      #   implementation "Novel", :instance do
+      #     match_property :publisher, :superclass => true
+      #   end
+      #
+      # args - An argumentlist containing one of the following
+      #         - property name as String or Symbol
+      #         - config Hash similiar to #match
+      #         - an Hash containing :superclass key (optional)
+      #
+      def match_property(*args)
+        options   = {}
+        if args.size.eql?(1)
+          property  = args.pop
+        else
+          options   = args.pop
+          property  = args.shift
+          options.stringify_keys!
+        end
+        if property.is_a?(String) || property.is_a?(Symbol)
+          [property, "#{property}="].each do |method|
+            match_options               = {}
+            match_options[method]       = method
+            match_options["superclass"] = options.fetch("superclass", false)
+            match(match_options)
+          end
+        elsif property.is_a?(Hash)
+          property.stringify_keys!
+          implement_property  = property.keys.first.to_sym
+          remote_property     = property.values.first
+          [{implement_property => remote_property},
+           {"#{implement_property}=" => "#{remote_property}="}].each do |opt|
+            if property.has_key?("superclass")
+              opt["superclass"] = property.fetch("superclass")
+            end
+            match(opt)
+          end
+        else
+          raise Seatbelt::Errors::TypeMissmatchError.
+                                  new("String, Symbol or Hash",
+                                      property.class.name)
+        end
+      end
+
+      private
+
+      def notify_delgated_method(implementation_method, imp_hsh, remote_method)
+        namespaced_scope = "#{@_namespace}#{@_scope}#{remote_method}"
+        bulk_methods.last[implementation_method][:as] = namespaced_scope
+        bulk_methods.last[implementation_method][:delegated] = true
+        mark_as_instance_implementation.call(imp_hsh, implementation_method)
+      end
+    end
+  end
+end

data/lib/seatbelt/core/interface.rb

@@ -0,0 +1,51 @@
+module Seatbelt
+  module Interface
+    extend self
+    include Seatbelt::Property::ClassMethods
+    # Public: Provides definitions of API Meta methods. For more informations
+    # of API meta methods see Seatbelt::Pool::Api#api_method
+    #
+    # scope     - the type the methods should be defined for [:instance, :class]
+    #
+    # &block    - The block that contains the API method definitions.
+    #
+    # Example
+    #
+    #   class Hotel
+    #     include Seatbelt::Ghost
+    #
+    #     interface :class do
+    #       define  :find_nearby,
+    #               :block_required => false,
+    #               :args => [:options]
+    #     end
+    #   end
+    #
+    def interface(scope, &block)
+      @scope = scope
+      yield(self) if block
+    end
+
+    # Public: Defines an API method. This is only working if its called within
+    # the #interface method block.
+    #
+    # Wraps Seatbelt::Pool::Api#api_method
+    #
+    # name        - Name of the API method
+    # hsh         - an options Hash that refines the methods usage:
+    #               :scope           - the method type
+    #                                  [:instance, :class]
+    #                                  defaults to :instance
+    #               :block_required  - defines if the method
+    #                                  require a Ruby Block for
+    #                                  usage.
+    #               :args             - An array of expected
+    #                                   arguments as Symbols or
+    #                                   Strings. If omitted the
+    #                                   method expects no arguments.
+    def define(name, hsh={})
+      hsh[:scope] = @scope
+      self.send(:api_method, name, hsh)
+    end
+  end
+end

data/lib/seatbelt/core/iterators/method_config.rb

@@ -0,0 +1,50 @@
+module Seatbelt
+  module Core
+    module Iterators
+
+      # Public: Various methods useful for performing mathematical operations.
+      # All methods are module methods and should be called on the Math module.
+      #
+      class MethodConfig
+
+
+        # Public: Method config iterator block used by Gate#implement_class.
+        #
+        # klass       - The API class name
+        # gate_klass  - The class that includes the Gate module
+        #
+        # Returns a Proc that is useable for [].each
+        def self.array_method_iterator(klass, gate_klass, scope)
+          return lambda do |method_config|
+            method_config.send(:each_pair,
+                               &hash_method_iterator(klass,gate_klass, scope))
+          end
+        end
+
+
+        # Public: Method config iterator block used by Gate#implement_class.
+        #
+        # klass       - The API class name
+        # gate_klass  - The class that includes the Gate module
+        #
+        # Returns a Proc that is useable for {}.each_pair
+        def self.hash_method_iterator(klass, gate_klass, scope)
+          methods_bucket = :implementation_methods if scope.eql?(:instance)
+          methods_bucket = :implementation_class_methods if scope.eql?(:class)
+          return lambda do |(key,value)|
+            method_name = key
+            implementation_config = {}
+            implementation_config[method_name] = {
+              :as => "#{klass}#{value[:as]}",
+            }
+            if value[:delegated]
+              implementation_config[method_name][:delegated] = value[:delegated]
+            end
+            gate_klass.send(methods_bucket) << implementation_config
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/seatbelt/core/lookup_table.rb

@@ -0,0 +1,101 @@
+module Seatbelt
+
+  # Public: Lookup table implementation that holds all meta methods for a
+  # Seatbelt API Class.
+  #
+  class LookupTable < Array
+
+    alias_method :add_method, :<<
+    alias_method :set, :<<
+
+    # Public: Removes a method configuration from the lookup table.
+    #
+    # method_name - The method name identifier as Symbol.
+    # scope       - The scope in for removing the method, defaults to :instance
+    #
+    # Returns the removed method configuration if found otherwise nil.
+    def remove_method(method_name, scope: :instance)
+      method = find_method(method_name, scope: scope)
+      delete(method) if method
+    end
+    alias_method :unset, :remove_method
+
+
+    # Public: Finds a method configuration by method name.
+    #
+    # method_name - The method configuration identifier.
+    # scope       - The scope to search for the method, defaults to :instance
+    #
+    # Example:
+    #
+    # table = Seatbelt::LookupTable.new
+    # table.set({:my_method => {:scope => :klass, :block_required => true } })
+    #
+    # method = table.find_method(:my_method)
+    # #=> {:my_method => {:scope => :klass, :block_required => true } }
+    #
+    # Returns the method configuration if found, otherwise nil.
+    def find_method(method_name, scope: :instance)
+      detect do |method_config|
+        name          = method_config.keys.first
+        method_scope  = method_config[name][:scope]
+        name.eql?(method_name.to_sym) && method_scope.eql?(scope)
+      end
+    end
+
+
+    # Public: Gets a method configuration by name or configuration.
+    #
+    # method_c - The method identifier or its whole configurations Hash
+    # scope    - The scope to search for the method, defaults to :instance
+    #
+    # Example:
+    #
+    # table     = Seatbelt::LookupTable.new
+    # config    = {
+    #   :my_method => {
+    #     :scope          => :klass,
+    #     :block_required => true
+    #   }
+    # }
+    # table.set(config)
+    #
+    # method = table.get(:my_method)
+    # #=> {:my_method => {:scope => :klass, :block_required => true } }
+    #
+    # method = table.get(config)
+    # #=> {:my_method => {:scope => :klass, :block_required => true } }
+    #
+    # Returns the method configuration if found, otherwise nil.
+    def get(method_c, scope: :instance)
+      eqlCheck = false
+      identifier = if method_c.is_a?(Symbol) or method_c.is_a?(String) then
+        method_c
+      elsif method_c.is_a?(Hash)
+        scope     = method_c.values.first[:scope]
+        eqlCheck  = true
+        method_c.keys.first
+      end
+      method = find_method(identifier, scope: scope)
+
+      return method unless eqlCheck
+      return method if method.eql?(method_c)
+    end
+
+
+    # Public: Check if the lookup table contains a method configuration.
+    #
+    # identifier - The method configuration identifier or the configuration
+    # scope      - The scope to search for the method, defaults to :instance
+    #
+    # Returns true if table has method otherwise false.
+    def has?(identifier, scope: :instance)
+      if identifier.is_a?(Symbol) or identifier.is_a?(String)
+        return not(find_method(identifier, scope: scope).nil?)
+      elsif identifier.is_a?(Hash)
+        return not(get(identifier, scope: scope).nil?)
+      end
+    end
+
+  end
+end

data/lib/seatbelt/core/pool.rb

@@ -0,0 +1,90 @@
+module Seatbelt
+  module Pool
+
+    # Public: Provides storage of meta-method definitions.
+    # All classes that declare (API) meta-methods have to include this module
+    # by using the Seatbelt::Terminal wrapper.
+    #
+    # For API design matters: https://gist.github.com/dsci/a96048884fdff81aca68
+    module Api
+      extend self
+
+      # Public: Registeres a meta-method at the method pool by adding the
+      # method configuration to a lookup table.
+      #
+      # Each class that includes Seatbelt::Terminal has its own lookup table.
+      #
+      # *args - An argument list consisting of
+      #         * method_name - that has to be the first argument (required)
+      #         * options     - an options Hash that refines the methods usage:
+      #                         :scope           - the method type
+      #                                            [:instance, :class]
+      #                                            defaults to :instance
+      #                         :block_required  - defines if the method
+      #                                            require a Ruby Block for
+      #                                            usage.
+      #                         :args             - An array of expected
+      #                                             arguments as Symbols or
+      #                                             Strings. If omitted the
+      #                                             method expects no arguments.
+      #
+      #
+      # If no arguments are passed, a Seatbelt::Errors::ArgumentsMissmatchError
+      # is raised.
+      # Raises a Seatbelt::Errors::MissingMetaMethodName, if no meta-method
+      # name was given.
+      # If a meta-method name is passed that already exists in the lookup table,
+      # a Seatbelt::Errors::MetaMethodDuplicateError is raised.
+      #
+      # This will be a private method with Seatbelt 1.0.
+      def api_method(*args)
+        raise Errors::ArgumentsMissmatchError if args.empty?
+        raise Errors::MissingMetaMethodName if args.first.is_a?(Hash)
+        if lookup_tbl.map{|n| n.keys}.flatten.include?(args.first)
+          raise Errors::MetaMethodDuplicateError
+        end
+        default_options   = { :scope          => :instance,
+                              :block_required => false,
+                              :arity          => 0
+                            }
+        options           = args.extract_options!
+        if options.has_key?(:args)
+          arity = options.delete(:args)
+          size  = arity.size
+          block_size = lambda do
+            block_match = arity.join(",").scan(/\&{1,}/)
+            size = size - block_match.size if block_match
+            return size
+          end
+          if arity.join(",").match(/\*{1,}/)
+            size = -block_size.call
+            eqls = arity.join(",").scan(/[\=]+/).size
+            size = size + eqls
+            default_options[:arity] = size
+          else
+            size = block_size.call
+            eqls = arity.join(",").scan(/[\=]+/).size
+            size = eqls > 0 ? -size : size
+            default_options[:arity] = size
+          end
+        end
+
+        meta_definitions  = { args.first => default_options.merge(options) }
+
+        lookup_tbl.set(meta_definitions)
+      end
+
+
+      # Public: An accessor to the lookup table array.
+      #
+      # Creates the table if it doesn't exists.
+      #
+      # Returns an instance of Lookup Table
+      def lookup_tbl
+        @lookup_tbl = LookupTable.new if @lookup_tbl.nil?
+        return @lookup_tbl
+      end
+
+    end
+  end
+end