jw-rails-erd 1.4.5

data/lib/rails_erd/diagram/graphviz.rb

@@ -0,0 +1,295 @@
+# encoding: utf-8
+require "rails_erd/diagram"
+require "graphviz"
+require "erb"
+
+# Fix bad RegEx test in Ruby-Graphviz.
+GraphViz::Types::LblString.class_eval do
+  def output # @private :nodoc:
+    if /^<.*>$/m =~ @data
+      @data
+    else
+      @data.to_s.inspect.gsub("\\\\", "\\")
+    end
+  end
+  alias_method :to_gv, :output
+  alias_method :to_s, :output
+end
+
+module RailsERD
+  class Diagram
+    # Create Graphviz-based diagrams based on the domain model. For easy
+    # command line graph generation, you can use:
+    #
+    #   % rake erd
+    #
+    # === 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
+    #            +: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
+    #               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_TEMPLATES = {
+        html:   "node.html.erb",
+        record: "node.record.erb"
+      } # @private :nodoc:
+
+      NODE_WIDTH = 130 # @private :nodoc:
+
+      FONTS = Config.font_names_based_on_os
+
+      # Default graph attributes.
+      GRAPH_ATTRIBUTES = {
+        rankdir:     :LR,
+        ranksep:     0.5,
+        nodesep:     0.4,
+        pad:         "0.4,0.4",
+        margin:      "0,0",
+        concentrate: true,
+        labelloc:    :t,
+        fontsize:    13,
+        fontname:    FONTS[:bold]
+      }
+
+      # Default node attributes.
+      NODE_ATTRIBUTES = {
+        shape:    "Mrecord",
+        fontsize: 10,
+        fontname: FONTS[:normal],
+        margin:   "0.07,0.05",
+        penwidth: 1.0
+      }
+
+      # Default edge attributes.
+      EDGE_ATTRIBUTES = {
+        fontname:      FONTS[:normal],
+        fontsize:      7,
+        dir:           :both,
+        arrowsize:     0.9,
+        penwidth:      1.0,
+        labelangle:    32,
+        labeldistance: 1.8,
+      }
+
+      module Simple
+        def entity_style(entity, attributes)
+          {}.tap do |options|
+            options[:fontcolor] = options[:color] = :grey60 if entity.virtual?
+          end
+        end
+
+        def relationship_style(relationship)
+          {}.tap do |options|
+            options[:style] = :dotted if relationship.indirect?
+
+            # Closed arrows for to/from many.
+            options[:arrowhead] = relationship.to_many? ? "normal" : "none"
+            options[:arrowtail] = relationship.many_to? ? "normal" : "none"
+          end
+        end
+
+        def specialization_style(specialization)
+          { color:     :grey60,
+            arrowtail: :onormal,
+            arrowhead: :none,
+            arrowsize: 1.2 }
+        end
+      end
+
+      module Crowsfoot
+        include Simple
+        def relationship_style(relationship)
+          {}.tap do |options|
+            options[:style] = :dotted if relationship.indirect?
+
+            # Cardinality is "look-across".
+            dst = relationship.to_many? ? "crow" : "tee"
+            src = relationship.many_to? ? "crow" : "tee"
+
+            # Participation is "look-across".
+            dst << (relationship.destination_optional? ? "odot" : "tee")
+            src << (relationship.source_optional? ? "odot" : "tee")
+
+            options[:arrowsize] = 0.6
+            options[:arrowhead], options[:arrowtail] = dst, src
+          end
+        end
+      end
+
+      module Bachman
+        include Simple
+        def relationship_style(relationship)
+          {}.tap do |options|
+            options[:style] = :dotted if relationship.indirect?
+
+            # Participation is "look-here".
+            dst = relationship.source_optional? ? "odot" : "dot"
+            src = relationship.destination_optional? ? "odot" : "dot"
+
+            # 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?
+
+            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 == Domain::Relationship::N ? "∗" : range.max}"
+              end
+            end
+            options[:headlabel], options[:taillabel] = *ranges
+          end
+        end
+      end
+
+      attr_accessor :graph
+
+      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!\nOutput directory '#{File.dirname(filename)}' does not exist." unless File.directory?(File.dirname(filename))
+
+        begin
+          # GraphViz doesn't like spaces in the filename
+          graph.output(filetype => filename.gsub(/\s/,"_"))
+          filename
+        rescue RuntimeError => e
+          raise "Saving diagram failed!\nGraphviz produced errors. Verify it " +
+                  "has support for filetype=#{options.filetype}, or use " +
+                  "filetype=dot.\nOriginal error: #{e.message.split("\n").last}"
+        rescue StandardError => e
+          raise "Saving diagram failed!\nVerify that Graphviz is installed " +
+                  "and in your path, or use 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)
+          from.children.each do |child|
+            draw_edge child.name, to.name, relationship_options(relationship)
+          end
+          to.children.each do |child|
+            draw_edge from.name, child.name, relationship_options(relationship)
+          end
+        end
+      end
+
+      private
+
+      def node_exists?(name)
+        !!graph.get_node(escape_name(name))
+      end
+
+      def draw_node(name, options)
+        graph.add_nodes escape_name(name), options
+      end
+
+      def draw_edge(from, to, options)
+        graph.add_edges graph.get_node(escape_name(from)), graph.get_node(escape_name(to)), options if node_exists?(from) and node_exists?(to)
+      end
+
+      def escape_name(name)
+        "m_#{name}"
+      end
+
+      # Returns the title to be used for the graph.
+      def title
+        case options.title
+        when false then nil
+        when true
+          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 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
+
+      def entity_options(entity, attributes)
+        label = options[:markup] ? "<#{read_template(:html).result(binding)}>" : "#{read_template(:record).result(binding)}"
+        entity_style(entity, attributes).merge :label => label
+      end
+
+      def relationship_options(relationship)
+        relationship_style(relationship).tap do |options|
+          # Edges with a higher weight are optimized to be shorter and straighter.
+          options[:weight] = relationship.strength
+
+          # Indirect relationships should not influence node ranks.
+          options[:constraint] = false if relationship.indirect?
+        end
+      end
+
+      def specialization_options(specialization)
+        specialization_style(specialization)
+      end
+
+      def read_template(type)
+        ERB.new(File.read(File.expand_path("templates/#{NODE_LABEL_TEMPLATES[type]}", File.dirname(__FILE__))), nil, "<>")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+<% 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="<%= FONTS[: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 %>">
+<%   attributes.each do |attribute| %>
+  <tr><td align="left" width="<%= NODE_WIDTH %>" port="<%= attribute %>"><%= attribute %> <font face="<%= FONTS[:italic] %>" color="grey60"><%= attribute.type_description %></font></td></tr>
+<%   end %>
+</table>
+<% else %>
+<% end %>
+<% if options.orientation == :vertical %>}<% end %>

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

@@ -0,0 +1,4 @@
+<% if options.orientation == :vertical %>{<% end %><%= entity.name %><% if attributes.any? %>
+|<%  attributes.each do |attribute| %><%=
+       attribute %> (<%= attribute.type_description %>)
+<%   end %><% end %><% if options.orientation == :vertical %>}<% end %>

data/lib/rails_erd/diagram.rb

@@ -0,0 +1,188 @@
+require "rails_erd/domain"
+
+module RailsERD
+  # This class is an abstract class that will process a domain model and
+  # allows easy creation of diagrams. To implement a new diagram type, derive
+  # from this class and override +process_entity+, +process_relationship+,
+  # and (optionally) +save+.
+  #
+  # As an example, a diagram class that generates code that can be used with
+  # yUML (http://yuml.me) can be as simple as:
+  #
+  #   require "rails_erd/diagram"
+  #
+  #   class YumlDiagram < RailsERD::Diagram
+  #     setup { @edges = [] }
+  #
+  #     each_relationship do |relationship|
+  #       return if relationship.indirect?
+  #
+  #       arrow = case
+  #       when relationship.one_to_one?   then "1-1>"
+  #       when relationship.one_to_many?  then "1-*>"
+  #       when relationship.many_to_many? then "*-*>"
+  #       end
+  #
+  #       @edges << "[#{relationship.source}] #{arrow} [#{relationship.destination}]"
+  #     end
+  #
+  #     save { @edges * "\n" }
+  #   end
+  #
+  # Then, to generate the diagram (example based on the domain model of Gemcutter):
+  #
+  #   YumlDiagram.create
+  #   #=> "[Rubygem] 1-*> [Ownership]
+  #   #    [Rubygem] 1-*> [Subscription]
+  #   #    [Rubygem] 1-*> [Version]
+  #   #    [Rubygem] 1-1> [Linkset]
+  #   #    [Rubygem] 1-*> [Dependency]
+  #   #    [Version] 1-*> [Dependency]
+  #   #    [User] 1-*> [Ownership]
+  #   #    [User] 1-*> [Subscription]
+  #   #    [User] 1-*> [WebHook]"
+  #
+  # 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
+  #              +: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+.
+  class Diagram
+    class << self
+      # Generates a new domain model based on all <tt>ActiveRecord::Base</tt>
+      # subclasses, and creates a new diagram. Use the given options for both
+      # the domain generation and the diagram generation.
+      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.
+    attr_reader :options
+
+    # The domain that this diagram represents.
+    attr_reader :domain
+
+    # Create a new diagram based on the given domain.
+    def initialize(domain, options = {})
+      @domain, @options = domain, RailsERD.options.merge(options)
+    end
+
+    # Generates and saves the diagram, returning the result of +save+.
+    def create
+      generate
+      save
+    end
+
+    # 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|
+        instance_exec entity, filtered_attributes(entity), &callbacks[:each_entity]
+      end
+
+      filtered_specializations.each do |specialization|
+        instance_exec specialization, &callbacks[:each_specialization]
+      end
+
+      filtered_relationships.each do |relationship|
+        instance_exec relationship, &callbacks[:each_relationship]
+      end
+    end
+
+    def save
+      instance_eval &callbacks[:save]
+    end
+
+    private
+
+    def callbacks
+      @callbacks ||= self.class.send(:callbacks)
+    end
+
+    def filtered_entities
+      @domain.entities.reject { |entity|
+        options.exclude && entity.model && [options.exclude].flatten.map(&:to_sym).include?(entity.name.to_sym) or
+        options.only && entity.model && ![options.only].flatten.map(&:to_sym).include?(entity.name.to_sym) 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?
+      end
+    end
+
+    def filtered_relationships
+      @domain.relationships.reject { |relationship|
+        !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.reject { |attribute|
+        # Select attributes that satisfy the conditions in the :attributes option.
+        !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
+  end
+end

data/lib/rails_erd/domain/attribute.rb

@@ -0,0 +1,160 @@
+# 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:
+          attributes = model.columns.collect { |column| new(domain, model, column) }
+          attributes.sort! if RailsERD.options[:sort]
+
+          if RailsERD.options[:prepend_primary]
+            attributes = prepend_primary(model, attributes)
+          end
+
+          attributes
+        end
+
+        def prepend_primary(model, attributes)
+          primary_key = ActiveRecord::Base.get_primary_key(model)
+          primary = attributes.index { |column| column.name == primary_key }
+
+          if primary
+            attributes[primary], attributes[0] = attributes[0], attributes[primary]
+          end
+
+          attributes
+        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 or column.sql_type.downcase.to_sym
+      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
+
+       def unique?
+         @model.validators_on(name).map(&:kind).include?(:uniqueness)
+       end
+
+      # Returns +true+ if this attribute is the primary key of the entity.
+      def primary_key?
+        @model.primary_key.to_s == name.to_s
+      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 { |associaton|
+          associaton.send(Domain.foreign_key_method_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
+
+      # Method allows false to be set as an attributes option when making custom graphs.
+      # It rejects all attributes when called from Diagram#filtered_attributes method
+      def false?
+        false
+      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>:decimal, :precision => 5, :scale => 2/tt>:: decimal (5,2)
+      # <tt>:boolean, :null => false</tt>:: boolean *
+      def type_description
+        type.to_s.tap do |desc|
+          desc << " #{limit_description}" if limit_description
+          desc << " ∗" if mandatory? && !primary_key? # Add a hair space + low asterisk (Unicode characters)
+          desc << " U" if unique? && !primary_key? && !foreign_key? # Add U if unique but non-key
+          desc << " PK" if primary_key?
+          desc << " FK" if foreign_key?
+        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
+        return if native_type == 'geometry' || native_type == 'geography'
+        return column.limit.to_i if column.limit != native_type[:limit] and column.limit.respond_to?(:to_i)
+        column.precision.to_i if column.precision != native_type[:precision] and column.precision.respond_to?(:to_i)
+      end
+
+      # Returns any non-standard scale for this attribute (decimal types only).
+      def scale
+        return column.scale.to_i if column.scale != native_type[:scale] and column.scale.respond_to?(:to_i)
+        0 if column.precision
+      end
+
+      # Returns a string that describes the limit for this attribute, such as
+      # +(128)+, or +(5,2)+ for decimal types. Returns nil if no non-standard
+      # limit was set.
+      def limit_description # @private :nodoc:
+        return "(#{limit},#{scale})" if limit and scale
+        return "(#{limit})" if limit
+      end
+
+      private
+
+      def native_type
+        @model.connection.native_database_types[type] or {}
+      end
+    end
+  end
+end