rails-erd 0.3.0 → 0.4.0

data/.gitignore

@@ -5,5 +5,6 @@
 *.rbc
 doc
 pkg
+output
 rdoc
 site/_generated

data/CHANGES.rdoc

@@ -1,3 +1,19 @@
+=== 0.4.0:
+
+* Support to optionally display single table inheritance relationships
+  (inheritance=true).
+* Support to optionally display polymorphic associations (polymorphism=true).
+* Adjustments to 'advanced' style so that it matches original Bachman style,
+  and therefore now called 'bachman'.
+* Ignore models without tables (reported by Mark Chapman).
+* Mutual indirect relationships are now combined.
+* Changed API for diagram generation.
+* Restructured classes and renamed several API properties and methods.
+* Added new edge type to describe single table inheritance and polymorphic
+  associations: Specialization.
+* Added compatibility for Active Record 3.1 (beta), removed dependency on Arel.
+* Rubinius compatibility.
+
 === 0.3.0:
 
 * Added the ability to support multiple styles of cardinality notations.
@@ -10,7 +26,7 @@
 * More versatile API that allows you to inspect relationships and their
   cardinalities.
 * Changed line widths to 1.0 to avoid invisible node boundaries with older
-  versions of Graphviz.
+  versions of Graphviz (reported by Mike McQuinn).
 * Bundled examples based on actual applications.
 
 === 0.2.0

data/Gemfile

@@ -1,8 +1,8 @@
 source "http://rubygems.org"
 
 gem "rails-erd", :path => "."
-gem "activesupport", :require => false
-gem "activerecord", :require => "active_record"
+gem "activerecord"
+gem "activesupport"
 gem "rake"
 gem "jeweler"
 
@@ -13,4 +13,5 @@ end
 platforms :jruby do
   gem "jdbc-sqlite3", :require => "jdbc/sqlite3"
   gem "activerecord-jdbc-adapter", "1.0.0.beta2"
+  gem "jruby-openssl", :require => false # Silence openssl warnings.
 end

data/Gemfile.lock

@@ -1,10 +1,10 @@
 PATH
   remote: .
   specs:
-    rails-erd (0.2.0)
-      activerecord (~> 3.0.0)
+    rails-erd (0.3.0)
+      activerecord (~> 3.0)
       activesupport (~> 3.0)
-      ruby-graphviz (~> 0.9.17)
+      ruby-graphviz (~> 0.9.18)
 
 GEM
   remote: http://rubygems.org/
@@ -22,6 +22,7 @@ GEM
     activesupport (3.0.0)
     arel (1.0.1)
       activesupport (~> 3.0.0)
+    bouncy-castle-java (1.5.0145.2)
     builder (2.1.2)
     gemcutter (0.6.1)
     git (1.2.5)
@@ -31,9 +32,11 @@ GEM
       gemcutter (>= 0.1.0)
       git (>= 1.2.5)
       rubyforge (>= 2.0.0)
+    jruby-openssl (0.7.1)
+      bouncy-castle-java
     json_pure (1.4.6)
     rake (0.8.7)
-    ruby-graphviz (0.9.17)
+    ruby-graphviz (0.9.18)
     rubyforge (2.0.4)
       json_pure (>= 1.1.7)
     sqlite3-ruby (1.3.1)
@@ -49,6 +52,7 @@ DEPENDENCIES
   activesupport
   jdbc-sqlite3
   jeweler
+  jruby-openssl
   rails-erd!
   rake
   sqlite3-ruby

data/README.md

@@ -0,0 +1,60 @@
+Rails ERD - Generate Entity-Relationship Diagrams for Rails applications
+========================================================================
+
+[Rails ERD](http://rails-erd.rubyforge.org/) is a Rails plugin that allows
+you to easily generate a diagram based on your Active Record models. The
+diagram gives an overview of how your models are related. Having a diagram
+that describes your models is perfect documentation for your application.
+
+The second goal of Rails ERD is to provide you with a tool to inspect your
+application's domain model. If you don't like the default output, it is very
+easy to use the API to build your own diagrams.
+
+Rails ERD was created specifically for Rails 3. It uses Active Record's
+built-in reflection capabilities to figure out how your models are associated.
+
+
+Preview
+-------
+
+Here's an example entity-relationship diagram that was generated by Rails ERD:
+
+![Entity-Relationship Diagram](http://rails-erd.rubyforge.org/images/entity-relationship-diagram.png)
+
+Browse the [gallery](http://rails-erd.rubyforge.org/gallery.html) for more
+example diagrams.
+
+
+Getting started
+---------------
+
+See the [installation instructions](http://rails-erd.rubyforge.org/install.html)
+for a complete description of how to install Rails ERD. Here's a summary:
+
+* Install Graphviz 2.22+ with Pango and Cairo support ([how?](http://rails-erd.rubyforge.org/install.html))
+
+* Add <tt>gem "rails-erd"</tt> to your application's Gemfile
+
+* Run <tt>rake erd</tt>
+
+
+Learn more
+----------
+
+More information can be found on [Rails ERD's project homepage](http://rails-erd.rubyforge.org/).
+
+If you wish to extend or customise Rails ERD, take a look at the [API documentation](http://rails-erd.rubyforge.org/doc/).
+
+
+About Rails ERD
+---------------
+
+Rails ERD was created by Rolf Timmermans (r.timmermans *at* voormedia.com)
+
+Copyright 2010 Voormedia - [www.voormedia.com](http://www.voormedia.com/)
+
+
+License
+-------
+
+Rails ERD is released under the MIT license.

data/Rakefile

@@ -12,9 +12,9 @@ Jeweler::Tasks.new do |spec|
   spec.email = "r.timmermans@voormedia.com"
   spec.homepage = "http://rails-erd.rubyforge.org/"
 
-  spec.add_runtime_dependency "activerecord", "~> 3.0.0"
+  spec.add_runtime_dependency "activerecord", "~> 3.0"
   spec.add_runtime_dependency "activesupport", "~> 3.0"
-  spec.add_runtime_dependency "ruby-graphviz", "~> 0.9.17"
+  spec.add_runtime_dependency "ruby-graphviz", "~> 0.9.18"
   spec.add_development_dependency "sqlite3-ruby"
   
   # Don't bundle examples or website in gem.
@@ -39,61 +39,21 @@ task :default => :test
 begin
   require "hanna/rdoctask"
   Rake::RDocTask.new do |rdoc|
-    rdoc.rdoc_files = Dir["[A-Z][A-Z]*"] + Dir["lib/**/*.rb"]
-    rdoc.title = "Rails ERD – Entity-Relationship Diagrams for Rails"
+    rdoc.rdoc_files = %w{CHANGES.rdoc LICENSE} + Dir["lib/**/*.rb"]
+    rdoc.title = "Rails ERD – API Documentation"
     rdoc.rdoc_dir = "rdoc"
+    rdoc.main = "RailsERD"
   end
 rescue LoadError
 end
 
 desc "Generate diagrams for bundled examples"
 task :examples do
-  require "rubygems"
-  require "bundler"
-  Bundler.require
-  require "rails_erd/diagram/graphviz"
-
-  Dir["examples/*/*"].each do |path|
-    name = File.basename(path)
-    print "==> Generating ERD for #{name.capitalize}... "
-    begin
-      # Load database schema.
-      ActiveRecord::Base.establish_connection :adapter => "sqlite3", :database => ":memory:"
-      ActiveRecord::Migration.suppress_messages do
-        begin
-          require File.expand_path("#{path}/schema.rb", File.dirname(__FILE__))
-        rescue LoadError
-        end
-      end
-      
-      # Load domain models for this example.
-      Dir["#{path}/**/*.rb"].each do |model|
-        require File.expand_path(model, File.dirname(__FILE__))
-      end
-      
-      # Skip empty domain models.
-      next if ActiveRecord::Base.descendants.empty?
-
-      puts "#{ActiveRecord::Base.descendants.length} models"
-      [:simple, :advanced].each do |notation|
-        filename = File.expand_path("examples/#{name}#{notation != :simple ? "-#{notation}" : ""}", File.dirname(__FILE__))
-
-        default_options = { :notation => notation, :filename => filename, :attributes => [:regular],
-          :title => name.classify + " domain model" }
-
-        specific_options = eval((File.read("#{path}/options.rb") rescue "")) || {}
+  require File.expand_path("examples/generate", File.dirname(__FILE__))
+end
 
-        # Generate ERD.
-        RailsERD::Diagram::Graphviz.create(default_options.merge(specific_options))
-      end
-    ensure
-      # Completely remove all loaded Active Record models.
-      ActiveRecord::Base.descendants.each do |model|
-        Object.send :remove_const, model.name.to_sym rescue nil
-      end
-      ActiveRecord::Base.direct_descendants.clear
-      Arel::Relation.send :class_variable_set, :@@connection_tables_primary_keys, {}
-      ActiveSupport::Dependencies::Reference.clear!
-    end
+namespace :examples do
+  task :sfdp do
+    require File.expand_path("examples/sfdp", File.dirname(__FILE__))
   end
 end

data/VERSION

@@ -1 +1 @@
-0.3.0
+0.4.0

data/lib/rails_erd.rb

@@ -1,6 +1,18 @@
 require "active_support/ordered_options"
 require "rails_erd/railtie" if defined? Rails
 
+# Welcome to the API documentation of Rails ERD. If you wish to extend or
+# customise the output that is generated by Rails ERD, you have come to the
+# right place.
+# 
+# == Creating custom output
+# 
+# If you want to create your own kind of diagrams, or some other output, a
+# good starting point is the RailsERD::Diagram class. It can serve as the base
+# of your output generation code.
+#
+# == Options
+#
 # Rails ERD provides several options that allow you to customise the
 # generation of the diagram and the domain model itself. For an overview of
 # all options available in Rails ERD, see README.rdoc.
@@ -21,15 +33,30 @@ module RailsERD
     # RailsERD::Diagram will use these options unless overridden.
     attr_accessor :options
   end
+  
+  module Inspectable # @private :nodoc:
+    def inspection_attributes(*attributes)
+      attribute_inspection = attributes.collect { |attribute|
+        " @#{attribute}=\#{[Symbol, String].include?(#{attribute}.class) ? #{attribute}.inspect : #{attribute}}"
+      }.join
+      class_eval <<-RUBY
+        def inspect
+          "#<\#{self.class}:0x%.14x#{attribute_inspection}>" % (object_id << 1)
+        end
+      RUBY
+    end
+  end
 
   self.options = ActiveSupport::OrderedOptions[
-    :attributes, :regular,
+    :attributes, :content,
     :disconnected, true,
     :filename, "ERD",
     :filetype, :pdf,
     :indirect, true,
+    :inheritance, false,
     :notation, :simple,
     :orientation, :horizontal,
+    :polymorphism, false,
     :warn, true,
     :title, true
   ]

data/lib/rails_erd/diagram.rb

@@ -12,7 +12,9 @@ module RailsERD
   #   require "rails_erd/diagram"
   #
   #   class YumlDiagram < RailsERD::Diagram
-  #     def process_relationship(relationship)
+  #     setup { @edges = [] }
+  #
+  #     each_relationship do |relationship|
   #       return if relationship.indirect?
   #
   #       arrow = case
@@ -21,12 +23,10 @@ module RailsERD
   #       when relationship.many_to_many? then "*-*>"
   #       end
   #
-  #       (@edges ||= []) << "[#{relationship.source}] #{arrow} [#{relationship.destination}]"
+  #       @edges << "[#{relationship.source}] #{arrow} [#{relationship.destination}]"
   #     end
   #
-  #     def save
-  #       instructions * "\n"
-  #     end
+  #     save { @edges * "\n" }
   #   end
   #
   # Then, to generate the diagram (example based on the domain model of Gemcutter):
@@ -51,12 +51,17 @@ module RailsERD
   # diagram generator inheriting from this class.
   #
   # attributes:: Selects which attributes to display. Can be any combination of
-  #              +:regular+, +:primary_keys+, +:foreign_keys+, or +:timestamps+.
+  #              +:content+, +:primary_keys+, +:foreign_keys+, +:timestamps+, or
+  #              +:inheritance+.
   # disconnected:: Set to +false+ to exclude entities that are not connected to other
   #                entities. Defaults to +false+.
   # indirect:: Set to +false+ to exclude relationships that are indirect.
   #            Indirect relationships are defined in Active Record with
   #            <tt>has_many :through</tt> associations.
+  # inheritance:: Set to +true+ to include specializations, which correspond to
+  #               Rails single table inheritance.
+  # polymorphism:: Set to +true+ to include generalizations, which correspond to
+  #                Rails polymorphic associations.
   # warn:: When set to +false+, no warnings are printed to the
   #        command line while processing the domain model. Defaults
   #        to +true+.
@@ -68,6 +73,34 @@ module RailsERD
       def create(options = {})
         new(Domain.generate(options), options).create
       end
+      
+      protected
+      
+      def setup(&block)
+        callbacks[:setup] = block
+      end
+      
+      def each_entity(&block)
+        callbacks[:each_entity] = block
+      end
+
+      def each_relationship(&block)
+        callbacks[:each_relationship] = block
+      end
+
+      def each_specialization(&block)
+        callbacks[:each_specialization] = block
+      end
+      
+      def save(&block)
+        callbacks[:save] = block
+      end
+
+      private
+
+      def callbacks
+        @callbacks ||= Hash.new { proc {} }
+      end
     end
 
     # The options that are used to create this diagram.
@@ -90,41 +123,35 @@ module RailsERD
     # Generates the diagram, but does not save the output. It is called
     # internally by Diagram#create.
     def generate
+      instance_eval &callbacks[:setup]
+
       filtered_entities.each do |entity|
-        process_entity entity, filtered_attributes(entity)
+        instance_exec entity, filtered_attributes(entity), &callbacks[:each_entity]
       end
 
-      filtered_relationships.each do |relationship|
-        process_relationship relationship
+      filtered_specializations.each do |specialization|
+        instance_exec specialization, &callbacks[:each_specialization]
       end
-    end
-
-    # Saves the diagram. Can be overridden in subclasses to write to an output
-    # file. It is called internally by Diagram#create.
-    def save
-    end
-        
-    protected
 
-    # Process a given entity and its attributes. This method should be implemented
-    # by subclasses. It is intended to add a representation of the entity to
-    # the diagram. This method will be called once for each entity that should
-    # be displayed, typically in alphabetic order.
-    def process_entity(entity, attributes)
+      filtered_relationships.each do |relationship|
+        instance_exec relationship, &callbacks[:each_relationship]
+      end
     end
     
-    # Process a given relationship. This method should be implemented by
-    # subclasses. It should add a representation of the relationship to
-    # the diagram. This method will be called once for eacn relationship
-    # that should be displayed.
-    def process_relationship(relationship)
+    def save
+      instance_eval &callbacks[:save]
     end
     
     private
     
+    def callbacks
+      @callbacks ||= self.class.send(:callbacks)
+    end
+    
     def filtered_entities
       @domain.entities.reject { |entity|
-        entity.descendant? or
+        !options.inheritance && entity.specialized? or
+        !options.polymorphism && entity.generalized? or
         !options.disconnected && entity.disconnected?
       }.compact.tap do |entities|
         raise "No entities found; create your models first!" if entities.empty?
@@ -133,19 +160,25 @@ module RailsERD
     
     def filtered_relationships
       @domain.relationships.reject { |relationship|
-        relationship.source.descendant? or
-        relationship.destination.descendant? or
         !options.indirect && relationship.indirect?
       }
     end
     
+    def filtered_specializations
+      @domain.specializations.reject { |specialization|
+        !options.inheritance && specialization.inheritance? or
+        !options.polymorphism && specialization.polymorphic?
+      }
+    end
+    
     def filtered_attributes(entity)
-      entity.attributes.select { |attribute|
+      entity.attributes.reject { |attribute|
         # Select attributes that satisfy the conditions in the :attributes option.
-        options.attributes and [*options.attributes].any? { |type| attribute.send(:"#{type.to_s.chomp('s')}?") }
+        !options.attributes or entity.specialized? or
+        [*options.attributes].none? { |type| attribute.send(:"#{type.to_s.chomp('s')}?") }
       }
     end
-
+    
     def warn(message)
       puts "Warning: #{message}" if options.warn
     end