schema_associations 0.1.0.pre3 → 0.1.0

data/README.rdoc

@@ -8,7 +8,18 @@ columns, keeping your model class definitions simple and DRY.  That's great
 for simple data columns, but where it falls down is when your table
 contains references to other tables: then the "accessors" you need are the
 +belongs_to+, +has_one+, +has_many+, and +has_and_belongs_to_many+
-associations -- and you need to put them into your model class definitions by hand, which isn't so DRY.
+associations -- and you need to put them into your model class definitions
+by hand.  In fact, for every relation, you need to define two associations, such as
+
+    class Post < ActiveRecord::Base
+        has_many :commens
+    end
+
+    class Comment < ActiveReocrd::Base
+        belongs_to :post
+    end
+
+....which isn't so DRY.
 
 Enter the SchemaAssociations gem.  It extends ActiveRecord to automatically
 define the appropriate associations based on foreign key constraints in the
@@ -21,14 +32,17 @@ automatically defines foreign key constraints.  So the common case is simple --
 
     create_table :comments do |t|
       t.integer post_id
-      # ... whatever ...
     end
 
-Then SchemaAssociations will define the corresponding associations:
+Then all you need for your models is:
 
-    Post.has_many :comments
-    Comment.belongs_to :post
+    class Post < ActiveRecord::Base
+    end
+
+    class Comment < ActiveRecord::Base
+    end
 
+and SchemaAssociations defines the appropriate associations under the hood
 
 == What if I want something special?
 
@@ -37,18 +51,178 @@ to pass special options.  SchemaAssociations won't clobber any existing
 definitions.
 
 You can also control the behavior with various options, globally via
-SchemaAssociations.setup or per-model via #schema_associations.  See
+SchemaAssociations::setup or per-model via SchemaAssociations::ActiveRecord#schema_associations.  See
 SchemaAssociations::Config for the available options.
 
-== Full details
+== Full Details
 
 === The basics
 
-=== Multiple references
+The common cases work entirely as you'd expect.  For a one-to-many
+relationship using standard naming conventions:
+
+    # migration:
+    
+    create_table :comments do |t|
+        t.integer post_id
+    end
+
+    # models:
+
+    class Post < ActiveRecord::Base
+        has_many :comments
+    end
+
+    class Comment < ActiveReocrd::Base
+        belongs_to :post
+    end
+
+For a one-to-one relationship:
+
+    # migration:
+    
+    create_table :comments do |t|
+        t.integer post_id, :index => :unique    # (using the :index option provided by schema_plus )
+    end
+
+    # models:
+
+    class Post < ActiveRecord::Base
+        has_one :comment
+    end
+
+    class Comment < ActiveReocrd::Base
+        belongs_to :post
+    end
+
+And for many-to-many relationships:
+
+    # migration:
+    
+    create_table :groups_members do |t|
+        integer :group_id
+        integer :member_id
+    end
+
+    class Group < ActiveReocrd::Base
+        has_and_belongs_to_many :members
+    end
+
+    class Member < ActiveRecord::Base
+        has_and_belongs_to_many :groups
+    end
+
+=== Unusual names, multiple references
+
+Sometimes you want or need to deviate from the simple naming conventions.  In
+this case, the +belongs_to+ relationship name is taken from the name of the
+foreign key column, and the +has_many+ or +has_one+ is named by the referencing
+table, suffixed with "as" the relationship name.  An example should make this clear...
+
+Suppose your company hires interns, and each intern is assigned a manager and a
+mentor, who are regular employees. 
+
+        create_table :interns do |t|
+            t.integer :manager_id,      :references => :employees
+            t.integer :mentor_id,       :references => :employees
+        end
+
+SchemaAssociations defines a +belongs_to+ association for each reference, named according to
+the column:
+
+        class Intern < ActiveRecord::Base
+            belongs_to  :manager, :class_name => "Employee", :foreign_key => "manager_id"
+            belongs_to  :mentor,  :class_name => "Employee", :foreign_key => "mentor_id"
+        end
+
+And the corresponding +has_many+ association each gets a suffix to indicate which one relation it refers to:
+
+        class Employee < ActiveRecord::Base
+            has_many :interns_as_manager, :class_name => "Intern", :foreign_key => "manager_id"
+            has_many :interns_as_mentor,  :class_name => "Intern", :foreign_key => "mentor_id"
+        end
+
+=== Special case for trees
+
+If your forward relation is named "parent", SchemaAssociations names the reverse
+relation "child" or "children".  That is, if you have:
+
+        create_table :nodes
+           t.integer :parent_id         # schema_plus assumes it's a reference to this table
+        end
+
+Then SchemaAssociations will define
+
+        class Node < ActiveRecord::Base
+            belongs_to :parent, :class_name => "Node", :foreign_key => "parent_id"
+            has_many :children, :class_name => "Node", :foreign_key => "parent_id"
+        end
 
 === Concise names
 
-=== How do I know what it did?
+For modularity in your tables and classes, you might  use a common prefix for
+related objects.  For example, you may have widgets each of which has a color,
+and might have one base that has a top color and a bottom color, from the same
+set of colors.
+
+        create_table :widget_colors |t|
+        end
+
+        create_table :widgets do |t|
+            t.integer   :widget_color_id
+        end
+
+        create_table :widget_base
+            t.integer :widget_id, :index => :unique
+            t.integer :top_widget_color_id,    :references => :widget_colors
+            t.integer :bottom_widget_color_id, :references => :widget_colors
+        end
+
+Using the full name for the associations would make your code verbose and not quite DRY:
+
+        @widget.widget_color
+        @widget.widget_base.top_widget_color
+
+Instead, by default, SchemaAssociations uses concise names: shared leading
+words are removed from the association name.  So instead of the above, your
+code looks like:
+
+        @widget.color
+        @widget.base.top_color
+
+i.e. these associations would be defined:
+
+        class WidgetColor < ActiveRecord::Base
+            has_many :widgets,         :class_name => "Widget",     :foreign_key => "widget_color_id"
+            has_many :bases_as_top,    :class_name => "WidgetBase", :foreign_key => "top_widget_color_id"
+            has_many :bases_as_bottom, :class_name => "WidgetBase", :foreign_key => "bottom_widget_color_id"
+        end
+
+        class Widget < ActiveRecord::Base
+            belongs_to :color, :class_name => "WidgetColor", :foreign_key => "widget_color_id"
+            has_one    :base,  :class_name => "WidgetBase",  :foreign_key => "widget_base_id"
+        end
+
+        class WidgetBase < ActiveRecord::Base
+            belongs_to :top_color,    :class_name => "WidgetColor", :foreign_key => "top_widget_color_id"
+            belongs_to :bottom_color, :class_name => "WidgetColor", :foreign_key => "bottom_widget_color_id"
+            belongs_to :widget,       :class_name => "Widget",      :foreign_key => "widget_id"
+        end
+
+If you like the formality of using full names for the asociations, you can turn off concise names globally or per-model, see SchemaAssociations::Config
+
+== How do I know what it did?
+
+If you're curious (or dubious) about what associations SchemaAssociations defines, you can check the log file.  For every assocation that SchemaAssociations defines, it generates an info entry such as
+
+        [schema_associations] Post.has_many :comments, :class_name "Comment", :foreign_key "comment_id"
+
+which shows the exact method definition call.  
+
+SchemaAssociations defines the associations lazily, only creating them when
+they're first needed.  So you may need to search through the log file to find
+them all (and some may not be defined at all if they were never needed for the
+use cases that you logged).
 
 == Compatibility
 
@@ -66,14 +240,6 @@ or in a Gemfile
 
         gem "schema_associations"
 
-== History
-
-* SchemaAssociations is derived from the "Red Hill On Rails" plugin
- foreign_key_associations originally created by harukizaemon
-  (https://github.com/harukizaemon)
-
-* SchemaAssociations was created in 2011 by Michal Lomnicki and Ronen Barzel
-
 == Testing
 
 SchemaAssociations is tested using rspec, sqlite3, and rvm, with some
@@ -85,13 +251,19 @@ full combo of tests, after you've forked & cloned:
   $ ./runspecs # as many times as you like
 
 You can also pick a specific version of rails and ruby to use, such as:
-  $ export SCHEMA_ASSOCIATIONS_RAILS_VERSION
-  $ SCHEMA_ASSOCIATIONS_RAILS_VERSION=3.1
   $ rvm use 1.9.2
+  $ export SCHEMA_ASSOCIATIONS_RAILS_VERSION=3.1
+  $ bundle update rails --local
   $ rake spec
 
 If you're running ruby 1.9.2, code coverage results will be in coverage/index.html -- it should be at 100% coverage.
 
+== History
+
+* SchemaAssociations is derived from the "Red Hill On Rails" plugin foreign_key_associations originally created by harukizaemon (https://github.com/harukizaemon)
+
+* SchemaAssociations was created in 2011 by Michal Lomnicki and Ronen Barzel
+
 == License
 
 This plugin is released under the MIT license.

data/lib/schema_associations/active_record/associations.rb

@@ -79,80 +79,22 @@ module SchemaAssociations
         return unless fk.column_names.size == 1
 
         referencing_table_name ||= fk.table_name
-
         column_name = fk.column_names.first
-        reference_name = column_name.sub(/_id$/, '')
+
         references_name = fk.references_table_name.singularize
         referencing_name = referencing_table_name.singularize
 
-        references_class_name = references_name.classify
         referencing_class_name = referencing_name.classify
+        references_class_name = references_name.classify
 
-        references_concise = _concise_name(references_name, referencing_name)
-        referencing_concise = _concise_name(referencing_name, references_name)
-
-        case reference_name
-        when 'parent'
-          belongs_to         = 'parent'
-          belongs_to_concise = 'parent'
-
-          has_one            = 'child'
-          has_one_concise    = 'child'
-
-          has_many           = 'children'
-          has_many_concise   = 'children'
-
-        when references_name
-          belongs_to         = references_name
-          belongs_to_concise = references_concise
-
-          has_one            = referencing_name
-          has_one_concise    = referencing_concise
-
-          has_many           = referencing_name.pluralize
-          has_many_concise   = referencing_concise.pluralize
-
-        when /(.*)_#{references_name}$/, /(.*)_#{references_concise}$/
-          label = $1
-          belongs_to         = "#{label}_#{references_name}"
-          belongs_to_concise = "#{label}_#{references_concise}"
-
-          has_one            = "#{referencing_name}_as_#{label}"
-          has_one_concise    = "#{referencing_concise}_as_#{label}"
-
-          has_many           = "#{referencing_name.pluralize}_as_#{label}"
-          has_many_concise   = "#{referencing_concise.pluralize}_as_#{label}"
-
-        when /^#{references_name}_(.*)$/, /^#{references_concise}_(.*)$/
-          label = $1
-          belongs_to            = "#{references_name}_#{label}"
-          belongs_to_concise    = "#{references_concise}_#{label}"
-
-          has_one               = "#{referencing_name}_as_#{label}"
-          has_one_concise       = "#{referencing_concise}_as_#{label}"
-
-          has_many              = "#{referencing_name.pluralize}_as_#{label}"
-          has_many_concise      = "#{referencing_concise.pluralize}_as_#{label}"
-
-        else
-          belongs_to            = reference_name
-          belongs_to_concise    = reference_name
-
-          has_one               = "#{referencing_name}_as_#{reference_name}"
-          has_one_concise       = "#{referencing_concise}_as_#{reference_name}"
-
-          has_many              = "#{referencing_name.pluralize}_as_#{reference_name}"
-          has_many_concise      = "#{referencing_concise.pluralize}_as_#{reference_name}"
-        end
+        names = _determine_association_names(column_name.sub(/_id$/, ''), referencing_name, references_name)
 
         case macro
         when :has_and_belongs_to_many
-          name = has_many
-          name_concise = has_many_concise
+          name = names[:has_many]
           opts = {:class_name => referencing_class_name, :join_table => fk.table_name, :foreign_key => column_name}
         when :belongs_to
-          name = belongs_to
-          name_concise = belongs_to_concise
+          name = names[:belongs_to]
           opts = {:class_name => references_class_name, :foreign_key => column_name}
         when :has_one_or_many
           opts = {:class_name => referencing_class_name, :foreign_key => column_name}
@@ -163,25 +105,66 @@ module SchemaAssociations
           # harder to debug.
           if connection.indexes(referencing_table_name, "#{referencing_table_name} Indexes").any?{|index| index.unique && index.columns == [column_name]}
             macro = :has_one
-            name = has_one
-            name_concise = has_one_concise
+            name = names[:has_one]
           else
             macro = :has_many
-            name = has_many
-            name_concise = has_many_concise
+            name = names[:has_many]
             if connection.columns(referencing_table_name, "#{referencing_table_name} Columns").any?{ |col| col.name == 'position' }
               opts[:order] = :position
             end
           end
         end
-        name = name_concise if _use_concise_name?
-        name = name.to_sym
         if (_filter_association(macro, name) && !_method_exists?(name))
           logger.info "[schema_associations] #{self.name || self.table_name.classify}.#{macro} #{name.inspect}, #{opts.inspect[1...-1]}"
           send macro, name, opts.dup
         end
       end
 
+      def _determine_association_names(reference_name, referencing_name, references_name)
+
+        references_concise = _concise_name(references_name, referencing_name)
+        referencing_concise = _concise_name(referencing_name, references_name)
+
+        if _use_concise_name?
+          references = references_concise
+          referencing = referencing_concise
+        else
+          references = references_name
+          referencing = referencing_name
+        end
+
+        case reference_name
+        when 'parent'
+          belongs_to         = 'parent'
+          has_one            = 'child'
+          has_many           = 'children'
+
+        when references_name
+          belongs_to         = references
+          has_one            = referencing
+          has_many           = referencing.pluralize
+
+        when /(.*)_#{references_name}$/, /(.*)_#{references_concise}$/
+          label = $1
+          belongs_to         = "#{label}_#{references}"
+          has_one            = "#{referencing}_as_#{label}"
+          has_many           = "#{referencing.pluralize}_as_#{label}"
+
+        when /^#{references_name}_(.*)$/, /^#{references_concise}_(.*)$/
+          label = $1
+          belongs_to         = "#{references}_#{label}"
+          has_one            = "#{referencing}_as_#{label}"
+          has_many           = "#{referencing.pluralize}_as_#{label}"
+
+        else
+          belongs_to         = reference_name
+          has_one            = "#{referencing}_as_#{reference_name}"
+          has_many           = "#{referencing.pluralize}_as_#{reference_name}"
+        end
+
+        { :belongs_to => belongs_to.to_sym, :has_one => has_one.to_sym, :has_many => has_many.to_sym }
+      end
+
       def _concise_name(string, other) #:nodoc:
         case
         when string =~ /^#{other}_(.*)$/           then $1

data/lib/schema_associations/version.rb

@@ -1,3 +1,3 @@
 module SchemaAssociations
-  VERSION = "0.1.0.pre3"
+  VERSION = "0.1.0"
 end

data/runspecs

@@ -14,14 +14,23 @@ OptionParser.new do |opts|
     end
 end.parse!
 
-cmd = if options [:install]
-          'bundle update'
-      else
-          'bundle update --local | grep rails \\n rake spec'
-      end
+cmds = if options [:install]
+           ['bundle update']
+       else
+           ['bundle update --local rails | grep rails', 'rake spec']
+       end
 
+n = 1
+total = RUBY_VERSIONS.size * RAILS_VERSIONS.size
 RUBY_VERSIONS.each do |ruby|
     RAILS_VERSIONS.each do |rails|
-        system "echo 'PS1="" SCHEMA_ASSOCIATION_RAILS_VERSION=#{rails} \\n rvm use #{ruby} \\n #{cmd} \\n exit' | bash -i" or abort "aborting #{$0}"
+        puts "\n\n*** ruby version #{ruby} - rails version #{rails}  [#{n} of #{total}]\n\n"
+        n += 1
+        allcmds = []
+        allcmds << "rvm use #{ruby}"
+        allcmds << "export SCHEMA_VALIDATIONS_RAILS_VERSION=#{rails}"
+        allcmds += cmds
+        allcmds << 'exit'
+        system %Q{echo '#{allcmds.join(' \n ')}' | bash -i} or abort "aborting #{$0}"
     end
 end

data/spec/association_spec.rb

@@ -518,8 +518,8 @@ describe ActiveRecord::Base do
     begin
       SchemaAssociations.setup do |config|
         config.update_attributes(opts)
-        yield
       end
+      yield
     ensure
       SchemaAssociations.config.update_attributes(save)
     end

metadata

@@ -1,8 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: schema_associations
 version: !ruby/object:Gem::Version 
-  prerelease: 6
-  version: 0.1.0.pre3
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
 platform: ruby
 authors: 
 - Ronen Barzel
@@ -11,17 +15,18 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-07-21 00:00:00 -07:00
+date: 2011-07-26 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: schema_plus
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
-    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        segments: 
+        - 0
         version: "0"
   type: :runtime
   version_requirements: *id001
@@ -29,10 +34,13 @@ dependencies:
   name: rake
   prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
-    none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 8
+        - 7
         version: 0.8.7
   type: :development
   version_requirements: *id002
@@ -40,10 +48,11 @@ dependencies:
   name: rspec
   prerelease: false
   requirement: &id003 !ruby/object:Gem::Requirement 
-    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        segments: 
+        - 0
         version: "0"
   type: :development
   version_requirements: *id003
@@ -51,10 +60,11 @@ dependencies:
   name: sqlite3
   prerelease: false
   requirement: &id004 !ruby/object:Gem::Requirement 
-    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        segments: 
+        - 0
         version: "0"
   type: :development
   version_requirements: *id004
@@ -62,10 +72,11 @@ dependencies:
   name: simplecov
   prerelease: false
   requirement: &id005 !ruby/object:Gem::Requirement 
-    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        segments: 
+        - 0
         version: "0"
   type: :development
   version_requirements: *id005
@@ -73,24 +84,14 @@ dependencies:
   name: simplecov-gem-adapter
   prerelease: false
   requirement: &id006 !ruby/object:Gem::Requirement 
-    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        segments: 
+        - 0
         version: "0"
   type: :development
   version_requirements: *id006
-- !ruby/object:Gem::Dependency 
-  name: ruby-debug19
-  prerelease: false
-  requirement: &id007 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
-  type: :development
-  version_requirements: *id007
 description: SchemaAssociations extends ActiveRecord to automatically create associations by inspecting the database schema.  This is more more DRY than the standard behavior, for which in addition to specifying the foreign key in the migration, you must also specify complementary associations in two model files (e.g. a :belongs_to and a :has_many).
 email: 
 - ronen@barzel.org
@@ -127,25 +128,25 @@ rdoc_options: []
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
-  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
-  none: false
   requirements: 
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version 
-      version: 1.3.1
+      segments: 
+      - 0
+      version: "0"
 requirements: []
 
 rubyforge_project: schema_associations
-rubygems_version: 1.6.2
+rubygems_version: 1.3.6
 signing_key: 
 specification_version: 3
 summary: ActiveRecord extension that automatically (DRY) creates associations based on the schema
-test_files: 
-- spec/association_spec.rb
-- spec/connection.rb
-- spec/spec_helper.rb
+test_files: []
+