datashift 0.15.0 → 0.16.0

data/lib/datashift/method_detail.rb

@@ -3,16 +3,13 @@
 # Date ::     Aug 2010
 # License::   MIT
 #
-# Details::   This class provides info and access to the individual population methods
+# Details::   This class provides info and access to the details of individual population methods
 #             on an AR model. Populated by, and coupled with MethodMapper,
 #             which does the model interrogation work and stores sets of MethodDetails.
 #
 #             Enables 'loaders' to iterate over the MethodMapper results set,
 #             and assign values to AR object, without knowing anything about that receiving object.
 #
-require 'to_b'
-require 'logging'
-require 'populator'
 require 'set'
 
 module DataShift
@@ -32,21 +29,35 @@ module DataShift
     end
 
 
-    # Name is the raw, client supplied name
+    def self.is_association_type? ( type )
+      association_types_enum.member?( type )
+    end
+
+
+    # Klass is the class of the 'parent' object i.e with the associations,
+    # For example Product which may have operator orders
+    attr_accessor :klass
+    
+    # Name is the raw, client supplied name e.g Orders
     attr_accessor :name
     attr_accessor :column_index
   
     # The rel col type from the DB
-    attr_reader :col_type, :current_value
+    attr_reader :col_type
 
+    # The :operator that can be called to assign  e.g orders or Products.new.orders << Order.new
+    # 
+    # The type of operator e.g :assignment, :belongs_to, :has_one, :has_many etc
     attr_reader :operator, :operator_type
 
     # TODO make it a list/primary keys
+    # Additional helpers for where clauses
     attr_accessor :find_by_operator, :find_by_value
         
     # Store the raw (client supplied) name against the active record  klass(model).
     # Operator is the associated method call on klass,
-    # so client name maybe Price but true operator is price
+    # i.e client supplies name 'Price' in a spreadsheet, 
+    # but true operator to call on klass is price
     # 
     # col_types can typically be derived from klass.columns - set of ActiveRecord::ConnectionAdapters::Column
 
@@ -88,11 +99,10 @@ module DataShift
 
     # Return the operator's expected class name, if can be derived, else nil
     def operator_class_name()
-      @operator_class_name ||= if(operator_for(:has_many) || operator_for(:belongs_to) || operator_for(:has_one))
-        begin
-          Kernel.const_get(operator.classify)
-          operator.classify
-        rescue; ""; end
+      @operator_class_name ||= 
+        if(operator_for(:has_many) || operator_for(:belongs_to) || operator_for(:has_one))
+   
+        get_operator_class.name
   
       elsif(@col_type)
         @col_type.type.to_s.classify
@@ -115,63 +125,31 @@ module DataShift
 
     private
 
-    # Attempt to find the associated object via id, name, title ....
-    def insistent_belongs_to( record, value )
-
-      if( value.class == operator_class)
-        record.send(operator) << value
-      else
+    # Return the operator's expected class, if can be derived, else nil
+    # TODO rspec- can reflect_on_association ever actually fail & do we ever need to try ourselves (badly)
+    def get_operator_class()
+      
+      if(operator_for(:has_many) || operator_for(:belongs_to) || operator_for(:has_one))
 
-        @@insistent_find_by_list.each do |x|
-          begin
-            next unless operator_class.respond_to?( "find_by_#{x}" )
-            item = operator_class.send( "find_by_#{x}", value)
-            if(item)
-              record.send(operator + '=', item)
-              break
-            end
-          rescue => e
-            logger.error "Failed to match belongs_to association #{value}"
-            puts "ERROR: #{e.inspect}"
-            if(x == Populator::insistent_method_list.last)
-              raise "I'm sorry I have failed to assign [#{value}] to #{@assignment}" unless value.nil?
-            end
-          end
-        end
-      end
-    end
+        result = klass.reflect_on_association(operator)
 
-    # Attempt to find the associated object via id, name, title ....
-    def insistent_has_many( record, value )
+        return result.klass if(result)
 
-      if( value.class == operator_class)
-        record.send(operator) << value
-      else
-        @@insistent_find_by_list.each do |x|
+        result = ModelMapper::class_from_string(operator.classify)
+        
+        if(result.nil?)
           begin
-            item = operator_class.send( "find_by_#{x}", value)
-            if(item)
-              record.send(operator) << item
-              break
-            end
+            
+            first = klass.to_s.split('::').first
+            logger.debug "Trying to find operator class with Parent Namespace #{first}"
+
+            result = ModelMapper::const_get_from_string("#{first}::#{operator.classify}")
           rescue => e
-            puts "ERROR: #{e.inspect}"
-            if(x == Populator::insistent_method_list.last)
-              raise "I'm sorry I have failed to assign [#{value}] to #{operator}" unless value.nil?
-            end
+            logger.error("Failed to derive Class for #{operator} (#{@operator_type} - #{e.inspect}")
           end
         end
-      end
-    end
-    
-  private
-  
-    # Return the operator's expected class, if can be derived, else nil
-    def get_operator_class()
-      if(operator_for(:has_many) || operator_for(:belongs_to) || operator_for(:has_one))  
-        begin     
-          Kernel.const_get(operator.classify)
-        rescue; nil; end
+        
+        result
 
       elsif(@col_type)
         begin

data/lib/datashift/method_details_manager.rb

@@ -6,6 +6,11 @@
 # Details::   This class provides info and access to groups of accessor methods,
 #             grouped by AR model. 
 #
+#             Stores complete collection of MethodDetail instances per mapped class.
+#             Provides high level find facilites to find a MethodDetail and to list out
+#             operators per type (has_one, has_many, belongs_to, instance_method etc) 
+#             and all possible operators, 
+
 require 'to_b'
 
 module DataShift
@@ -68,11 +73,22 @@ module DataShift
       get_list(type).collect { |md| md.operator }
     end
     
-    alias_method(:get_list_of_operators, :get_list) 
+    alias_method(:get_list_of_operators, :get_operators) 
      
-    def all_available_operators
+    def available_operators
       method_details_list.values.flatten.collect(&:operator)
     end
+
+    # A reverse map  showing all operators with their associated 'type'
+    def available_operators_with_type
+      h = {}
+      method_details_list.each { |t, mds| mds.each do |v| h[v.operator] = t end }
+    
+      # this is meant to be more efficient that Hash[h.sort]
+      sh = {}
+      h.keys.sort.each do |k| sh[k] = h[k] end
+      sh
+    end
     
   end
   

data/lib/datashift/method_dictionary.rb

@@ -10,7 +10,8 @@ module DataShift
   class MethodDictionary
 
     include DataShift::Logging
-   
+    extend DataShift::Logging
+
     # Return true if dictionary has  been populated for  klass
     def self.for?(klass)
       any = has_many[klass] || belongs_to[klass] || has_one[klass] || assignments[klass]
@@ -27,6 +28,8 @@ module DataShift
       
       raise "Cannot find operators supplied klass nil #{klass}" if(klass.nil?)
 
+      logger.debug("MethodDictionary - building operators information for #{klass}")
+
       # Find the has_many associations which can be populated via <<
       if( options[:reload] || has_many[klass].nil? )
         has_many[klass] = klass.reflect_on_all_associations(:has_many).map { |i| i.name.to_s }
@@ -63,8 +66,6 @@ module DataShift
         
         assignments[klass].uniq!
 
-        #puts "\nDEBUG: DICT Setters\n#{assignments[klass]}\n"
-        
         assignments[klass].each do |assign|
           column_types[klass] ||= {}
           column_def = klass.columns.find{ |col| col.name == assign }
@@ -95,10 +96,17 @@ module DataShift
     
     # Build a thorough and usable picture of the operators by building dictionary of our MethodDetail
     # objects which can be used to import/export data to objects of type 'klass'
-    #
-    def self.build_method_details( klass )
+    # Subsequent calls with same class will return existign mapping
+    # To over ride this behaviour, supply :force => true to force  regeneration
+
+    def self.build_method_details( klass, options = {} )
+
+      return method_details_mgrs[klass] if(method_details_mgrs[klass] && !options[:force])
+
       method_details_mgr = MethodDetailsManager.new( klass )
-         
+      
+      method_details_mgrs[klass] = method_details_mgr
+            
       assignments_for(klass).each do |n|
         method_details_mgr << MethodDetail.new(n, klass, n, :assignment, column_types[klass])
       end
@@ -115,7 +123,7 @@ module DataShift
         method_details_mgr << MethodDetail.new(n, klass, n, :belongs_to)
       end
       
-      method_details_mgrs[klass] = method_details_mgr
+      method_details_mgr
       
     end
     
@@ -135,9 +143,18 @@ module DataShift
         name.gsub(' ', '_').underscore
       ]
     end
-    
- 
-    # Find the proper format of name, appropriate call + column type for a given name.
+
+
+    # Dump out all available operators
+    #
+    def self.dump( klass )
+      method_details_mgr = get_method_details_mgr( klass )
+      #TODO
+    end
+
+
+    # For a client supplied name/header - find the operator i.e appropriate call + column type
+    # 
     # e.g Given users entry in spread sheet check for pluralization, missing underscores etc
     #
     # If not nil, returned method can be used directly in for example klass.new.send( call, .... )

data/lib/datashift/method_mapper.rb

@@ -23,22 +23,6 @@ module DataShift
     
     attr_accessor :method_details, :missing_methods
   
-    
-    # As well as just the column name, support embedding find operators for that column
-    # in the heading .. i.e Column header => 'BlogPosts:user_id' 
-    # ... association has many BlogPosts selected via find_by_user_id
-    # 
-    # in the heading .. i.e Column header => 'BlogPosts:user_name:John Smith' 
-    # ... association has many BlogPosts selected via find_by_user_name("John Smith")
-    #
-    def self.column_delim
-      @column_delim ||= ':'
-      @column_delim
-    end
-
-    def self.set_column_delim(x)  @column_delim = x; end
-    
-  
     def initialize
       @method_details = []
     end
@@ -47,10 +31,16 @@ module DataShift
     # Handles method names as defined by a user, from spreadsheets or file headers where the names
     # specified may not be exactly as required e.g handles capitalisation, white space, _ etc
     # 
-    # The header can also contain the fields to use in lookups, separated with MethodMapper::column_delim
-    # 
-    #   product:name or project:title  or user:email
-    # 
+    # The header can also contain the fields to use in lookups, separated with Delimiters ::column_delim
+    # For example specify that lookups on has_one association called 'product', be performed using name'
+    #   product:name
+    #
+    # The header can also contain a default value for the lookup field, again separated with Delimiters ::column_delim
+    #
+    # For example specify lookups on assoc called 'user', be performed using 'email' == 'test@blah.com'
+    #
+    #   user:email:test@blah.com
+    #
     # Returns: Array of matching method_details, including nils for non matched items
     # 
     # N.B Columns that could not be mapped are left in the array as NIL
@@ -59,15 +49,14 @@ module DataShift
     # 
     # Other callers can simply call compact on the results if the index not important.
     # 
-    # The Methoddetails instance will contain a pointer to the column index from which it was mapped.
-    # 
+    # The MethodDetails instance will contain a pointer to the column index from which it was mapped.
     # 
     # Options:
     # 
-    #   [:force_inclusion]  : List of columns that do not map to any operator but should be includeed in processing.
+    #   [:force_inclusion]  : List of columns that do not map to any operator but should be included in processing.
     #                     
     #       This provides the opportunity for loaders to provide specific methods to handle these fields
-    #       when no direct operator is available on the modle or it's associations
+    #       when no direct operator is available on the model or it's associations
     #       
     #   [:include_all]      : Include all headers in processing - takes precedence of :force_inclusion
     #
@@ -88,7 +77,7 @@ module DataShift
       @method_details, @missing_methods = [], []
     
       columns.each_with_index do |col_data, col_index|
-        
+
         raw_col_data = col_data.to_s
         
         if(raw_col_data.nil? or raw_col_data.empty?)
@@ -97,36 +86,55 @@ module DataShift
           next
         end
         
-        raw_col_name, lookup = raw_col_data.split(MethodMapper::column_delim) 
+        raw_col_name, where_field, where_value, *data = raw_col_data.split(Delimiters::column_delim)
          
         md = MethodDictionary::find_method_detail(klass, raw_col_name)
-               
-        if(md.nil?)          
-          #puts "DEBUG: Check Forced\n #{forced}.include?(#{raw_col_name}) #{forced.include?(raw_col_name.downcase)}"
-         
+
+        if(md.nil?)
           if(options[:include_all] || forced.include?(raw_col_name.downcase))
+            logger.debug("Operator #{raw_col_name} not found but forced inclusion operative")
             md = MethodDictionary::add(klass, raw_col_name)
           end
         end
         
-        if(md)       
+        if(md)
+
           md.name = raw_col_name
           md.column_index = col_index
-          
-          # TODO we should check that the assoc on klass responds to the specified
-          # lookup key now (nice n early)
-          # active_record_helper = "find_by_#{lookup}"
-          if(lookup)
-            find_by, find_value = lookup.split(MethodMapper::column_delim) 
-            md.find_by_value    = find_value 
-            md.find_by_operator = find_by # TODO and klass.x.respond_to?(active_record_helper))
-            puts "DEBUG: Method Detail #{md.name};#{md.operator} : find_by_operator #{md.find_by_operator}"
+
+          # put data back as string for now - leave it to clients to decide what to do with it later
+          Populator::set_header_default_data(md.operator, data.join(Delimiters::column_delim))
+
+          if(where_field)
+            logger.info("Lookup query field [#{where_field}] - specified for association #{md.operator}")
+
+            md.find_by_value = where_value
+
+            # Example :
+            # Project:name:My Best Project
+            #   User (klass) has_one project (operator) lookup by name  (find_by_operator) == 'My Best Project' (find_by_value)
+            #   User.project.where( :name => 'My Best Project')
+
+            # check the finder method name is a valid field on the actual association class
+
+            if(klass.reflect_on_association(md.operator) &&
+               klass.reflect_on_association(md.operator).klass.new.respond_to?(where_field))
+              md.find_by_operator = where_field
+              logger.info("Complex Lookup specified for [#{md.operator}] : on field [#{md.find_by_operator}] (optional value [#{md.find_by_value}])")
+            else
+              logger.warn("Find by operator [#{where_field}] Not Found on association [#{md.operator}] on Class #{klass.name} (#{md.inspect})")
+              logger.warn("Check column (#{md.column_index}) heading - e.g association field names are case sensitive")
+              # TODO - maybe derived loaders etc want this data for another purpose - should we stash elsewhere ?
+            end
           end
         else
           # TODO populate unmapped with a real MethodDetail that is 'null' and create is_nil
+          logger.warn("No operator or association found for Header #{raw_col_name}")
           @missing_methods << raw_col_name
         end
-        
+
+        logger.debug("Column [#{col_data}] (#{col_index}) - mapped to :\n#{md.inspect}")
+
         @method_details << md
         
       end

data/lib/datashift/model_mapper.rb

@@ -1,27 +1,47 @@
-class ModelMapper
-  
-  # Helper to deal with string versions of modules/namespaced classes
-  # Find and return the base class from a string.
-  # 
-  # e.g "Spree::Property" returns the Spree::Property class
-  # Raises exception if no such class found
-  def self.const_get_from_string(str)
-    str.to_s.split('::').inject(Object) do |mod, class_name| 
-      mod.const_get(class_name) 
-    end 
-  end 
-
-
-  # Similar to const_get_from_string except this version
-  # returns nil if no such class found
-  # Support modules e.g "Spree::Property"
-  # 
-  def self.class_from_string( str )
+module DataShift
+
+  class ModelMapper
+
+
+    def self.class_from_string_or_raise( klass )
+
+      ruby_klass = begin
+                     # support modules e.g "Spree::Property")
+        ModelMapper::class_from_string(klass)  #Kernel.const_get(model)
+      rescue NameError => e
+        puts e
+        raise Thor::Error.new("ERROR: No such Class [#{klass}] found - check valid model supplied")
+      end
+
+      raise NoSuchClassError.new("ERROR: No such Model [#{klass}] found - check valid model supplied") unless(ruby_klass)
+
+      ruby_klass
+    end
+
+
+    # Helper to deal with string versions of modules/namespaced classes
+    # Find and return the base class from a string.
+    #
+    # e.g "Spree::Property" returns the Spree::Property class
+    # Raises exception if no such class found
+    def self.const_get_from_string(str)
+      str.to_s.split('::').inject(Object) do |mod, class_name|
+        mod.const_get(class_name)
+      end
+    end
+
+
+    # Similar to const_get_from_string except this version
+    # returns nil if no such class found
+    # Support modules e.g "Spree::Property"
+    #
+    def self.class_from_string( str )
       begin
         ModelMapper::const_get_from_string(str.to_s)  #Kernel.const_get(model)
-      rescue NameError => e
-       return nil
+      rescue
+        return nil
       end
+    end
+
   end
-  
 end