rails-erd 0.3.0 → 0.4.0

data/lib/rails_erd/diagram/graphviz.rb

@@ -19,13 +19,10 @@ end
 module RailsERD
   class Diagram
     # Create Graphviz-based diagrams based on the domain model. For easy
-    # command line graph generation, you can use rake:
+    # command line graph generation, you can use:
     #
     #   % rake erd
     #
-    # Please see the README.rdoc file for more details on how to use Rails ERD
-    # from the command line.
-    #
     # === Options
     #
     # The following options are supported:
@@ -37,7 +34,7 @@ module RailsERD
     #            worse than a PDF file. The available formats depend on your installation
     #            of Graphviz.
     # notation:: The cardinality notation to be used. Can be +:simple+ or
-    #            +:advanced+. Refer to README.rdoc or to the examples on the project
+    #            +:bachman+. Refer to README.rdoc or to the examples on the project
     #            homepage for more information and examples.
     # orientation:: The direction of the hierarchy of entities. Either +:horizontal+
     #               or +:vertical+. Defaults to +horizontal+. The orientation of the
@@ -60,9 +57,7 @@ module RailsERD
         :concentrate => true,
         :labelloc => :t,
         :fontsize => 13,
-        :fontname => "Arial Bold",
-        :remincross => true,
-        :outputorder => :edgesfirst
+        :fontname => "Arial Bold"
       }
 
       # Default node attributes.
@@ -86,94 +81,139 @@ module RailsERD
         :fontsize => 7  
       }
       
-      # Define different styles to draw the cardinality of relationships.
-      CARDINALITY_STYLES = {
-        # Closed arrows for to/from many.
-        :simple => lambda { |relationship, options|
-          options[:arrowhead] = relationship.to_many? ? :normal : :none
-          options[:arrowtail] = relationship.many_to? ? :normal : :none
-        },
-
-        # Closed arrow for to/from many, UML ranges at each end.
-        :uml => lambda { |relationship, options|
-          options[:arrowsize] = 0.7
-          options[:arrowhead] = relationship.to_many? ? :vee : :none
-          options[:arrowtail] = relationship.many_to? ? :vee : :none
-          ranges = [relationship.cardinality.destination_range, relationship.cardinality.source_range].map do |range|
-            if range.min == range.max
-              "#{range.min}"
-            else
-              "#{range.min}..#{range.max == Relationship::Cardinality::Infinity ? "∗" : range.max}"
-            end
+      module Simple
+        def entity_style(entity, attributes)
+          {}.tap do |options|
+            options[:fontcolor] = options[:color] = :grey60 if entity.abstract?
           end
-          options[:headlabel], options[:taillabel] = *ranges
-        },
+        end
         
-        # Arrow for to/from many, open or closed dots for optional/mandatory.
-        :advanced => lambda { |relationship, options|
-          dst = relationship.destination_optional? ? "odot" : "dot"
-          src = relationship.source_optional? ? "odot" : "dot"
-          dst << "normal" if relationship.to_many?
-          src << "normal" if relationship.many_to?
-          options[:arrowsize] = 0.6
-          options[:arrowhead], options[:arrowtail] = dst, src
-        }
-      }
+        def relationship_style(relationship)
+          {}.tap do |options|
+            options[:style] = :dotted if relationship.indirect?
 
-      def graph
-        @graph ||= GraphViz.digraph(@domain.name) do |graph|
-          # Set all default attributes.
-          GRAPH_ATTRIBUTES.each { |attribute, value| graph[attribute] = value }
-          NODE_ATTRIBUTES.each  { |attribute, value| graph.node[attribute] = value }
-          EDGE_ATTRIBUTES.each  { |attribute, value| graph.edge[attribute] = value }
+            # Closed arrows for to/from many.
+            options[:arrowhead] = relationship.to_many? ? "normal" : "none"
+            options[:arrowtail] = relationship.many_to? ? "normal" : "none"
+          end
+        end
 
-          # Switch rank direction if we're creating a vertically oriented graph.
-          graph[:rankdir] = :TB if vertical?
-          
-          # Title of the graph itself.
-          graph[:label] = "#{title}\\n\\n" if title
+        def specialization_style(specialization)
+          { :color => :grey60, :arrowtail => :onormal, :arrowhead => :none, :arrowsize => 1.2 }
         end
       end
-      
-      # Save the diagram and return the file name that was written to.
-      def save
-        graph.output(filetype => filename)
-        filename
-      rescue StandardError => e
-        raise "Saving diagram failed. Verify that Graphviz is installed or select filetype=dot."
-      end
+    
+      module Bachman
+        include Simple
+        def relationship_style(relationship)
+          {}.tap do |options|
+            options[:style] = :dotted if relationship.indirect?
 
-      protected
+            # Participation is "look-here".
+            dst = relationship.source_optional? ? "odot" : "dot"
+            src = relationship.destination_optional? ? "odot" : "dot"
 
-      def process_entity(entity, attributes)
-        graph.add_node entity.name, entity_options(entity, attributes)
+            # Cardinality is "look-across".
+            dst << "normal" if relationship.to_many?
+            src << "normal" if relationship.many_to?
+            options[:arrowsize] = 0.6
+            options[:arrowhead], options[:arrowtail] = dst, src
+          end
+        end
       end
+      
+      module Uml
+        include Simple
+        def relationship_style(relationship)
+          {}.tap do |options|
+            options[:style] = :dotted if relationship.indirect?
 
-      def process_relationship(relationship)
-        graph.add_edge graph.get_node(relationship.source.name), graph.get_node(relationship.destination.name),
-          relationship_options(relationship)
-      end
+            options[:arrowsize] = 0.7
+            options[:arrowhead] = relationship.to_many? ? "vee" : "none"
+            options[:arrowtail] = relationship.many_to? ? "vee" : "none"
 
-      # Returns +true+ if the layout or hierarchy of the diagram should be
-      # horizontally oriented.
-      def horizontal?
-        options.orientation == :horizontal
+            ranges = [relationship.cardinality.destination_range, relationship.cardinality.source_range].map do |range|
+              if range.min == range.max
+                "#{range.min}"
+              else
+                "#{range.min}..#{range.max == Domain::Relationship::N ? "∗" : range.max}"
+              end
+            end
+            options[:headlabel], options[:taillabel] = *ranges
+          end
+        end
       end
+      
+      attr_accessor :graph
 
-      # Returns +true+ if the layout or hierarchy of the diagram should be
-      # vertically oriented.
-      def vertical?
-        !horizontal?
+      setup do
+        self.graph = GraphViz.digraph(domain.name)
+
+        # Set all default attributes.
+        GRAPH_ATTRIBUTES.each { |attribute, value| graph[attribute] = value }
+        NODE_ATTRIBUTES.each  { |attribute, value| graph.node[attribute] = value }
+        EDGE_ATTRIBUTES.each  { |attribute, value| graph.edge[attribute] = value }
+
+        # Switch rank direction if we're creating a vertically oriented graph.
+        graph[:rankdir] = :TB if options.orientation == :vertical
+        
+        # Title of the graph itself.
+        graph[:label] = "#{title}\\n\\n" if title
+        
+        # Setup notation options.
+        extend self.class.const_get(options.notation.to_s.capitalize.to_sym)
+      end
+      
+      save do
+        raise "Saving diagram failed. Output directory '#{File.dirname(filename)}' does not exist." unless File.directory?(File.dirname(filename))
+        begin
+          graph.output(filetype => filename)
+          filename
+        rescue StandardError => e
+          raise "Saving diagram failed. Verify that Graphviz is installed or select filetype=dot."
+        end
       end
 
+      each_entity do |entity, attributes|
+        draw_node entity.name, entity_options(entity, attributes)
+      end
+      
+      each_specialization do |specialization|
+        from, to = specialization.generalized, specialization.specialized
+        draw_edge from.name, to.name, specialization_options(specialization)
+      end
+      
+      each_relationship do |relationship|
+        from, to = relationship.source, relationship.destination
+        unless draw_edge from.name, to.name, relationship_options(relationship)
+          if from.children.any?
+            from.children.each do |child|
+              draw_edge child.name, to.name, relationship_options(relationship)
+            end
+          end
+        end
+      end
+      
       private
       
+      def node_exists?(name)
+        !!graph.get_node(name)
+      end
+      
+      def draw_node(name, options)
+        graph.add_node name, options
+      end
+      
+      def draw_edge(from, to, options)
+        graph.add_edge graph.get_node(from), graph.get_node(to), options if node_exists?(from) and node_exists?(to)
+      end
+
       # Returns the title to be used for the graph.
       def title
         case options.title
         when false then nil
-        when true then
-          if @domain.name then "#{@domain.name} domain model" else "Domain model" end
+        when true
+          if domain.name then "#{domain.name} domain model" else "Domain model" end
         else options.title
         end
       end
@@ -188,32 +228,23 @@ module RailsERD
         if options.filetype.to_sym == :dot then :none else options.filetype.to_sym end
       end
 
-      # Returns an options hash based on the given entity and its attributes.
       def entity_options(entity, attributes)
-        { :label => "<#{NODE_LABEL_TEMPLATE.result(binding)}>" }
+        entity_style(entity, attributes).merge :label => "<#{NODE_LABEL_TEMPLATE.result(binding)}>"
       end
       
-      # Returns an options hash 
       def relationship_options(relationship)
-        relationship_style_options(relationship).tap do |opts|
+        relationship_style(relationship).tap do |options|
           # Edges with a higher weight are optimised to be shorter and straighter.
-          opts[:weight] = relationship.strength
+          options[:weight] = relationship.strength
           
           # Indirect relationships should not influence node ranks.
-          opts[:constraint] = false if relationship.indirect?
+          options[:constraint] = false if relationship.indirect?
         end
       end
-      
-      # Returns an options hash that defines the (cardinality) style for the
-      # relationship.
-      def relationship_style_options(relationship)
-        {}.tap do |opts|
-          opts[:style] = :dotted if relationship.indirect?
-          
-          # Let cardinality style callbacks draw arrow heads and tails.
-          CARDINALITY_STYLES[options.notation][relationship, opts]
-        end
+
+      def specialization_options(specialization)
+        specialization_style(specialization)
       end
     end
   end
-end
+end

data/lib/rails_erd/diagram/templates/node.erb

@@ -1,4 +1,4 @@
-<% if vertical? %>{<% end %>
+<% if options.orientation == :vertical %>{<% end %>
 <table border="0" align="center" cellspacing="0.5" cellpadding="0" width="<%= NODE_WIDTH + 4 %>">
   <tr><td align="center" valign="bottom" width="<%= NODE_WIDTH %>"><font face="Arial Bold" point-size="11"><%= entity.name %></font></td></tr>
 </table>
@@ -11,4 +11,4 @@
 </table>
 <% else %>
 <% end %>
-<% if vertical? %>}<% end %>
+<% if options.orientation == :vertical %>}<% end %>

data/lib/rails_erd/domain.rb

@@ -1,8 +1,8 @@
-require "set"
 require "rails_erd"
-require "rails_erd/entity"
-require "rails_erd/relationship"
-require "rails_erd/attribute"
+require "rails_erd/domain/attribute"
+require "rails_erd/domain/entity"
+require "rails_erd/domain/relationship"
+require "rails_erd/domain/specialization"
 
 module RailsERD
   # The domain describes your Rails domain model. This class is the starting
@@ -28,13 +28,16 @@ module RailsERD
       end
     end
     
+    extend Inspectable
+    inspection_attributes
+    
     # The options that are used to generate this domain model.
     attr_reader :options
 
     # Create a new domain model object based on the given array of models.
     # The given models are assumed to be subclasses of <tt>ActiveRecord::Base</tt>.
     def initialize(models = [], options = {})
-      @models, @options = models, RailsERD.options.merge(options)
+      @source_models, @options = models, RailsERD.options.merge(options)
     end
 
     # Returns the domain model name, which is the name of your Rails
@@ -45,7 +48,7 @@ module RailsERD
     
     # Returns all entities of your domain model.
     def entities
-      @entities ||= Entity.from_models(self, @models)
+      @entities ||= Entity.from_models(self, models)
     end
     
     # Returns all relationships in your domain model.
@@ -53,19 +56,23 @@ module RailsERD
       @relationships ||= Relationship.from_associations(self, associations)
     end
     
+    # Returns all specializations in your domain model.
+    def specializations
+      @specializations ||= Specialization.from_models(self, models)
+    end
+    
     # Returns a specific entity object for the given Active Record model.
-    def entity_for(model) # @private :nodoc:
-      entity_mapping[model] or raise "model #{model} exists, but is not included in domain"
+    def entity_by_name(name) # @private :nodoc:
+      entity_mapping[name]
     end
     
     # Returns an array of relationships for the given Active Record model.
-    def relationships_for(model) # @private :nodoc:
-      relationships_mapping[model] or []
+    def relationships_by_entity_name(name) # @private :nodoc:
+      relationships_mapping[name] or []
     end
-  
-    def inspect # @private :nodoc:
-      "#<#{self.class}:0x%.14x {%s}>" %
-        [object_id << 1, relationships.map { |rel| "#{rel.source} => #{rel.destination}" } * ", "]
+    
+    def specializations_by_entity_name(name)
+      specializations_mapping[name] or []
     end
     
     def warn(message) # @private :nodoc:
@@ -77,7 +84,7 @@ module RailsERD
     def entity_mapping
       @entity_mapping ||= {}.tap do |mapping|
         entities.each do |entity|
-          mapping[entity.model] = entity
+          mapping[entity.name] = entity
         end
       end
     end
@@ -85,25 +92,46 @@ module RailsERD
     def relationships_mapping
       @relationships_mapping ||= {}.tap do |mapping|
         relationships.each do |relationship|
-          (mapping[relationship.source.model] ||= []) << relationship
-          (mapping[relationship.destination.model] ||= []) << relationship
+          (mapping[relationship.source.name] ||= []) << relationship
+          (mapping[relationship.destination.name] ||= []) << relationship
+        end
+      end
+    end
+    
+    def specializations_mapping
+      @specializations_mapping ||= {}.tap do |mapping|
+        specializations.each do |specialization|
+          (mapping[specialization.generalized.name] ||= []) << specialization
+          (mapping[specialization.specialized.name] ||= []) << specialization
         end
       end
     end
     
+    def models
+      @models ||= @source_models.reject(&:abstract_class?).select { |model| check_model_validity(model) }
+    end
+    
     def associations
-      @associations ||= @models.collect(&:reflect_on_all_associations).flatten.select { |assoc| check_association_validity(assoc) }
+      @associations ||= models.collect(&:reflect_on_all_associations).flatten.select { |assoc| check_association_validity(assoc) }
+    end
+    
+    def check_model_validity(model)
+      model.table_exists? or raise "table #{model.table_name} does not exist"
+    rescue => e
+      warn "Ignoring invalid model #{model.name} (#{e.message})"
     end
     
     def check_association_validity(association)
       # Raises an ActiveRecord::ActiveRecordError if the association is broken.
       association.check_validity!
 
-      # Raises NameError if the associated class cannot be found.
-      model = association.klass
-      
-      # Raises error if model is not in the domain.
-      entity_for model
+      if association.options[:polymorphic]
+        entity_name = association.class_name
+        entity_by_name(entity_name) or raise "polymorphic interface #{entity_name} does not exist"
+      else
+        entity_name = association.klass.name # Raises NameError if the associated class cannot be found.
+        entity_by_name(entity_name) or raise "model #{entity_name} exists, but is not included in domain"
+      end
     rescue => e
       warn "Ignoring invalid association #{association_description(association)} (#{e.message})"
     end

data/lib/rails_erd/domain/attribute.rb

@@ -0,0 +1,102 @@
+# encoding: utf-8
+module RailsERD
+  class Domain
+    # Describes an entity's attribute. Attributes correspond directly to
+    # database columns.
+    class Attribute
+      TIMESTAMP_NAMES = %w{created_at created_on updated_at updated_on} # @private :nodoc:
+
+      class << self
+        def from_model(domain, model) # @private :nodoc:
+          model.columns.collect { |column| new(domain, model, column) }.sort
+        end
+      end
+      
+      extend Inspectable
+      inspection_attributes :name, :type
+
+      attr_reader :column # @private :nodoc:
+  
+      def initialize(domain, model, column) # @private :nodoc:
+        @domain, @model, @column = domain, model, column
+      end
+    
+      # The name of the attribute, equal to the column name.
+      def name
+        column.name
+      end
+    
+      # The type of the attribute, equal to the Rails migration type. Can be any
+      # of +:string+, +:integer+, +:boolean+, +:text+, etc.
+      def type
+        column.type
+      end
+    
+      # Returns +true+ if this attribute is a content column, that is, if it
+      # is not a primary key, foreign key, timestamp, or inheritance column.
+      def content?
+        !primary_key? and !foreign_key? and !timestamp? and !inheritance?
+      end
+    
+      # Returns +true+ if this attribute is mandatory. Mandatory attributes
+      # either have a presence validation (+validates_presence_of+), or have a
+      # <tt>NOT NULL</tt> database constraint.
+      def mandatory?
+        !column.null or @model.validators_on(name).map(&:kind).include?(:presence)
+      end
+    
+      # Returns +true+ if this attribute is the primary key of the entity.
+      def primary_key?
+        column.primary
+      end
+  
+      # Returns +true+ if this attribute is used as a foreign key for any
+      # relationship.
+      def foreign_key?
+        @domain.relationships_by_entity_name(@model.name).map(&:associations).flatten.map(&:primary_key_name).include?(name)
+      end
+
+      # Returns +true+ if this attribute is used for single table inheritance.
+      # These attributes are typically named +type+.
+      def inheritance?
+        @model.inheritance_column == name
+      end
+
+      # Returns +true+ if this attribute is one of the standard 'magic' Rails
+      # timestamp columns, being +created_at+, +updated_at+, +created_on+ or
+      # +updated_on+.
+      def timestamp?
+        TIMESTAMP_NAMES.include? name
+      end
+    
+      def <=>(other) # @private :nodoc:
+        name <=> other.name
+      end
+  
+      def to_s # @private :nodoc:
+        name
+      end
+  
+      # Returns a description of the attribute type. If the attribute has
+      # a non-standard limit or if it is mandatory, this information is included.
+      #
+      # Example output:
+      # <tt>:integer</tt>:: integer
+      # <tt>:string, :limit => 255</tt>:: string
+      # <tt>:string, :limit => 128</tt>:: string (128)
+      # <tt>:boolean, :null => false</tt>:: boolean *
+      def type_description
+        type.to_s.tap do |desc|
+          desc << " (#{limit})" if limit
+          desc << " ∗" if mandatory? # Add a hair space + low asterisk (Unicode characters).
+        end
+      end
+    
+      # Returns any non-standard limit for this attribute. If a column has no
+      # limit or uses a default database limit, this method returns +nil+.
+      def limit
+        column.limit if column.limit != @model.connection.native_database_types[type][:limit]
+      end
+    end
+  end
+end