rails-erd 0.2.0 → 0.3.0

data/lib/rails_erd/attribute.rb

@@ -28,6 +28,12 @@ module RailsERD
       column.type
     end
     
+    # Returns +true+ if this attribute has no special meaning, that is, if it
+    # is not a primary key, foreign key, or timestamp.
+    def regular?
+      !primary_key? and !foreign_key? and !timestamp?
+    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.
@@ -65,32 +71,25 @@ module RailsERD
       name
     end
   
-    # Returns a short description of the attribute type. If the attribute has
+    # 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>:: int
-    # <tt>:string, :limit => 255</tt>:: str
-    # <tt>:string, :limit => 128</tt>:: str (128)
-    # <tt>:boolean, :null => false</tt>:: bool *
+    # <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
-      case type
-      when :integer       then "int"
-      when :float         then "float"
-      when :decimal       then "dec"
-      when :datetime      then "datetime"
-      when :date          then "date"
-      when :timestamp     then "timest"
-      when :time          then "time"
-      when :text          then "txt"
-      when :string        then "str"
-      when :binary        then "blob"
-      when :boolean       then "bool"
-      else type.to_s
-      end.tap do |desc|
-        desc << " (#{column.limit})" if column.limit != @model.connection.native_database_types[type][:limit]
+      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

data/lib/rails_erd/diagram.rb

@@ -12,25 +12,21 @@ module RailsERD
   #   require "rails_erd/diagram"
   #
   #   class YumlDiagram < RailsERD::Diagram
-  #     def process_relationship(rel)
-  #       return if rel.indirect?
+  #     def process_relationship(relationship)
+  #       return if relationship.indirect?
   #
   #       arrow = case
-  #       when rel.cardinality.one_to_one?   then "1-1>"
-  #       when rel.cardinality.one_to_many?  then "1-*>"
-  #       when rel.cardinality.many_to_many? then "*-*>"
+  #       when relationship.one_to_one?   then "1-1>"
+  #       when relationship.one_to_many?  then "1-*>"
+  #       when relationship.many_to_many? then "*-*>"
   #       end
   #
-  #       instructions << "[#{rel.source}] #{arrow} [#{rel.destination}]"
+  #       (@edges ||= []) << "[#{relationship.source}] #{arrow} [#{relationship.destination}]"
   #     end
   #
   #     def save
   #       instructions * "\n"
   #     end
-  #
-  #     def instructions
-  #       @instructions ||= []
-  #     end
   #   end
   #
   # Then, to generate the diagram (example based on the domain model of Gemcutter):
@@ -48,6 +44,22 @@ module RailsERD
   #
   # For another example implementation, see Diagram::Graphviz, which is the
   # default (and currently only) diagram type that is used by Rails ERD.
+  #
+  # === Options
+  #
+  # The following options are available and will by automatically used by any
+  # diagram generator inheriting from this class.
+  #
+  # attributes:: Selects which attributes to display. Can be any combination of
+  #              +:regular+, +:primary_keys+, +:foreign_keys+, or +:timestamps+.
+  # 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.
+  # warn:: When set to +false+, no warnings are printed to the
+  #        command line while processing the domain model. Defaults
+  #        to +true+.
   class Diagram
     class << self
       # Generates a new domain model based on all <tt>ActiveRecord::Base</tt>
@@ -108,46 +120,34 @@ module RailsERD
     def process_relationship(relationship)
     end
     
-    # Returns +true+ if the layout or hierarchy of the diagram should be
-    # horizontally oriented.
-    def horizontal?
-      options.orientation == :horizontal
-    end
-
-    # Returns +true+ if the layout or hierarchy of the diagram should be
-    # vertically oriented.
-    def vertical?
-      !horizontal?
-    end
-    
     private
     
     def filtered_entities
-      @domain.entities.collect do |entity|
-        if options.exclude_unconnected && !entity.connected?
-          warn "Skipping unconnected model #{entity.name} (use exclude_unconnected=false to include)"
-        else
-          entity
-        end
-      end.compact.tap do |entities|
-        raise "No (connected) entities found; create your models first!" if entities.empty?
+      @domain.entities.reject { |entity|
+        entity.descendant? or
+        !options.disconnected && entity.disconnected?
+      }.compact.tap do |entities|
+        raise "No entities found; create your models first!" if entities.empty?
       end
     end
     
     def filtered_relationships
-      @domain.relationships
+      @domain.relationships.reject { |relationship|
+        relationship.source.descendant? or
+        relationship.destination.descendant? or
+        !options.indirect && relationship.indirect?
+      }
     end
     
     def filtered_attributes(entity)
-      entity.attributes.reject { |attribute|
-        options.exclude_primary_keys && attribute.primary_key? or
-        options.exclude_foreign_keys && attribute.foreign_key? or
-        options.exclude_timestamps && attribute.timestamp?
+      entity.attributes.select { |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')}?") }
       }
     end
 
     def warn(message)
-      puts "Warning: #{message}" unless options.suppress_warnings
+      puts "Warning: #{message}" if options.warn
     end
   end
 end

data/lib/rails_erd/diagram/graphviz.rb

@@ -1,3 +1,4 @@
+# encoding: utf-8
 require "rails_erd/diagram"
 require "graphviz"
 require "erb"
@@ -24,6 +25,26 @@ module RailsERD
     #
     # 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:
+    #
+    # filename:: The file basename of the generated diagram. Defaults to +ERD+,
+    #            or any other extension based on the file type.
+    # filetype:: The file type of the generated diagram. Defaults to +pdf+, which
+    #            is the recommended format. Other formats may render significantly
+    #            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
+    #            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
+    #               PDF that is generated depends on the amount of hierarchy
+    #               in your models.
+    # title:: The title to add at the top of the diagram. Defaults to 
+    #         <tt>"YourApplication domain model"</tt>.
     class Graphviz < Diagram
       NODE_LABEL_TEMPLATE = ERB.new(File.read(File.expand_path("templates/node.erb", File.dirname(__FILE__))), nil, "<>") # @private :nodoc:
 
@@ -33,14 +54,16 @@ module RailsERD
       GRAPH_ATTRIBUTES = {
         :rankdir => :LR,
         :ranksep => 0.5,
-        :nodesep => 0.35,
-        :margin => "0.4,0.4",
+        :nodesep => 0.4,
+        :pad => "0.4,0.4",
+        :margin => "0,0",
         :concentrate => true,
         :labelloc => :t,
         :fontsize => 13,
         :fontname => "Arial Bold",
         :remincross => true,
-        :outputorder => :edgesfirst }
+        :outputorder => :edgesfirst
+      }
 
       # Default node attributes.
       NODE_ATTRIBUTES = {
@@ -48,15 +71,54 @@ module RailsERD
         :fontsize => 10,
         :fontname => "Arial",
         :margin => "0.07,0.05",
-        :penwidth => 0.8 }
+        :penwidth => 1.0
+      }
 
       # Default edge attributes.
       EDGE_ATTRIBUTES = {
         :fontname => "Arial",
         :fontsize => 8,
         :dir => :both,
-        :arrowsize => 0.7,
-        :penwidth => 0.8 }
+        :arrowsize => 0.9,
+        :penwidth => 1.0,
+        :labelangle => 32,
+        :labeldistance => 1.8,
+        :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
+          end
+          options[:headlabel], options[:taillabel] = *ranges
+        },
+        
+        # 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 graph
         @graph ||= GraphViz.digraph(@domain.name) do |graph|
@@ -65,19 +127,20 @@ module RailsERD
           NODE_ATTRIBUTES.each  { |attribute, value| graph.node[attribute] = value }
           EDGE_ATTRIBUTES.each  { |attribute, value| graph.edge[attribute] = value }
 
-          # Switch rank direction if we're told to create a vertically
-          # oriented graph.
+          # Switch rank direction if we're creating a vertically oriented graph.
           graph[:rankdir] = :TB if vertical?
           
           # Title of the graph itself.
-          graph[:label] = "#{@domain.name} domain model\\n\\n"
+          graph[:label] = "#{title}\\n\\n" if title
         end
       end
       
       # Save the diagram and return the file name that was written to.
       def save
-        graph.output(options.file_type.to_sym => file_name)
-        file_name
+        graph.output(filetype => filename)
+        filename
+      rescue StandardError => e
+        raise "Saving diagram failed. Verify that Graphviz is installed or select filetype=dot."
       end
 
       protected
@@ -90,12 +153,39 @@ module RailsERD
         graph.add_edge graph.get_node(relationship.source.name), graph.get_node(relationship.destination.name),
           relationship_options(relationship)
       end
-      
+
+      # Returns +true+ if the layout or hierarchy of the diagram should be
+      # horizontally oriented.
+      def horizontal?
+        options.orientation == :horizontal
+      end
+
+      # Returns +true+ if the layout or hierarchy of the diagram should be
+      # vertically oriented.
+      def vertical?
+        !horizontal?
+      end
+
       private
       
+      # 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
+        else options.title
+        end
+      end
+      
       # Returns the file name that will be used when saving the diagram.
-      def file_name
-        "ERD.#{options.file_type}"
+      def filename
+        "#{options.filename}.#{options.filetype}"
+      end
+      
+      # Returns the default file extension to be used when saving the diagram.
+      def filetype
+        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.
@@ -105,14 +195,23 @@ module RailsERD
       
       # Returns an options hash 
       def relationship_options(relationship)
-        {}.tap do |options|
-          options[:arrowhead] = relationship.cardinality.one_to_one?   ? :dot : :normal
-          options[:arrowtail] = relationship.cardinality.many_to_many? ? :normal : :dot
-          options[:weight] = relationship.strength
-          if relationship.indirect?
-            options[:style] = :dotted
-            options[:constraint] = false
-          end
+        relationship_style_options(relationship).tap do |opts|
+          # Edges with a higher weight are optimised to be shorter and straighter.
+          opts[:weight] = relationship.strength
+          
+          # Indirect relationships should not influence node ranks.
+          opts[: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
       end
     end

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

@@ -2,16 +2,13 @@
 <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>
+<% if attributes.any? %>
 |
 <table border="0" align="left" cellspacing="2" cellpadding="0" width="<%= NODE_WIDTH + 4 %>">
-  <% if attributes.any? %>
-    <% attributes.each do |attribute| %>
-      <tr>
-        <td align="left" width="<%= NODE_WIDTH %>" port="<%= attribute %>"><%= attribute %> <font face="Arial Italic" color="grey60"><%= attribute.type_description %></font></td>
-      </tr>
-    <% end %>
-  <% else %>
-    <tr><td height="6"></td></tr>
-  <% end %>
+<%   attributes.each do |attribute| %>
+  <tr><td align="left" width="<%= NODE_WIDTH %>" port="<%= attribute %>"><%= attribute %> <font face="Arial Italic" color="grey60"><%= attribute.type_description %></font></td></tr>
+<%   end %>
 </table>
+<% else %>
+<% end %>
 <% if vertical? %>}<% end %>

data/lib/rails_erd/domain.rb

@@ -2,12 +2,19 @@ require "set"
 require "rails_erd"
 require "rails_erd/entity"
 require "rails_erd/relationship"
-require "rails_erd/relationship/cardinality"
 require "rails_erd/attribute"
 
 module RailsERD
   # The domain describes your Rails domain model. This class is the starting
   # point to get information about your models.
+  #
+  # === Options
+  #
+  # The following options are available:
+  #
+  # warn:: When set to +false+, no warnings are printed to the
+  #        command line while processing the domain model. Defaults
+  #        to +true+.
   class Domain
     class << self
       # Generates a domain model object based on all loaded subclasses of
@@ -38,7 +45,7 @@ module RailsERD
     
     # Returns all entities of your domain model.
     def entities
-      @entities ||= entity_mapping.values.sort
+      @entities ||= Entity.from_models(self, @models)
     end
     
     # Returns all relationships in your domain model.
@@ -48,7 +55,7 @@ module RailsERD
     
     # 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 the domain"
+      entity_mapping[model] or raise "model #{model} exists, but is not included in domain"
     end
     
     # Returns an array of relationships for the given Active Record model.
@@ -61,10 +68,18 @@ module RailsERD
         [object_id << 1, relationships.map { |rel| "#{rel.source} => #{rel.destination}" } * ", "]
     end
     
+    def warn(message) # @private :nodoc:
+      puts "Warning: #{message}" if options.warn
+    end
+    
     private
     
     def entity_mapping
-      @entity_mapping ||= Hash[@models.collect { |model| [model, Entity.new(self, model)] }]
+      @entity_mapping ||= {}.tap do |mapping|
+        entities.each do |entity|
+          mapping[entity.model] = entity
+        end
+      end
     end
     
     def relationships_mapping
@@ -90,11 +105,7 @@ module RailsERD
       # Raises error if model is not in the domain.
       entity_for model
     rescue => e
-      warn "Invalid association #{association_description(association)} (#{e.message})"
-    end
-    
-    def warn(message)
-      puts "Warning: #{message}" unless options.suppress_warnings
+      warn "Ignoring invalid association #{association_description(association)} (#{e.message})"
     end
     
     def association_description(association)