rails-erd 0.1.0

data/.gitignore

@@ -0,0 +1 @@
+doc

data/CHANGES.rdoc

@@ -0,0 +1,4 @@
+=== 0.1.0
+
+* Released on September 20th, 2010.
+* First public release.

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2010 Voormedia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,56 @@
+= Rails ERD - Generate Entity-Relationship Diagrams for Rails applications
+
+Rails ERD is a Rails plugin that allows you to easily generate diagrams based
+on your ActiveRecord models. The diagrams give a great overview of how your
+models are related. Having a diagram that describes your models is perfect
+documentation for your application.
+
+Rails ERD was created specifically for Rails 3. It uses ActiveRecord reflection
+to figure out how your models are associated.
+
+== Getting started
+
+In its most simple form, Rails ERD is a plugin for Rails 3 that provides you
+with a Rake task to create an Entity-Relationship Diagram. It depends on the
+Graphviz visualisation library. You have to install Graphviz before using
+Rails ERD. In order to create PDF files (the default), you should install
+or compile Graphviz with Pango/Cairo.
+
+For example, to install Graphviz with MacPorts:
+
+  % sudo port install graphviz
+
+Or with Homebrew:
+
+  % brew install cairo pango graphviz
+
+Next, install Rails ERD. Open your +Gemfile+, and add the following:
+
+  group :development do
+    gem 'rails-erd'
+  end
+
+Tell Bundler to install Rails ERD:
+
+  % bundle install
+
+You now have access to Rails ERD through Rake. Generate a new
+Entity-Relationship Diagram for your Rails application:
+
+  % rake erd
+
+All done! You will now have a file named +ERD.pdf+ in your application root.
+
+== Advanced use
+
+Rails ERD has several options that you can use to customise its behaviour.
+All options can be provided on the command line. For example:
+
+  % rake erd exclude_timestamps=false
+
+For an overview of all available options, see the documentation of RailsERD:
+http://rails-erd.rubyforge.org/doc/
+
+== License
+
+Rails ERD is released under the MIT license.

data/Rakefile

@@ -0,0 +1,38 @@
+# encoding: utf-8
+require "jeweler"
+require "rake/testtask"
+
+Jeweler::Tasks.new do |spec|
+  spec.name = "rails-erd"
+  spec.rubyforge_project = "rails-erd"
+  spec.summary = "Entity-relationship diagram for your Rails models."
+  spec.description = "Automatically generate an entity-relationship diagram (ERD) for the models in your Rails application."
+
+  spec.authors = ["Rolf Timmermans"]
+  spec.email = "r.timmermans@voormedia.com"
+  spec.homepage = "http://rails-erd.rubyforge.org/"
+
+  spec.add_runtime_dependency "activesupport", "~> 3.0.0"
+  spec.add_runtime_dependency "ruby-graphviz", "~> 0.9.17"
+end
+
+Jeweler::GemcutterTasks.new
+
+Jeweler::RubyforgeTasks.new do |rubyforge|
+  rubyforge.doc_task = "rdoc"
+end
+
+Rake::TestTask.new do |test|
+  test.pattern = "test/unit/**/*_test.rb"
+end
+
+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_dir = "doc"
+  end
+rescue => e
+  puts e.message
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/rails-erd.rb

@@ -0,0 +1 @@
+require "rails_erd"

data/lib/rails_erd.rb

@@ -0,0 +1,38 @@
+require "active_support/ordered_options"
+require "rails_erd/railtie" if defined? Rails
+
+# Rails ERD provides several options that allow you to customise the
+# generation of the diagram and the domain model itself. Currently, the
+# following options are supported:
+#
+# type:: 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.
+# orientation:: The direction of the hierarchy of entities. Either +:horizontal+
+#               or +:vertical+. Defaults to +:horizontal+.
+# suppress_warnings:: When set to +true+, no warnings are printed to the
+#                     command line while processing the domain model. Defaults
+#                     to +false+.
+# exclude_timestamps:: Excludes timestamp columns (<tt>created_at/on</tt> and
+#                      <tt>updated_at/on</tt>) from attribute lists. Defaults
+#                      to +true+.
+# exclude_primary_keys:: Excludes primary key columns from attribute lists.
+#                        Defaults to +true+.
+# exclude_foreign_keys:: Excludes foreign key columns from attribute lists.
+#                        Defaults to +true+.
+module RailsERD
+  class << self
+    # Access to default options. Any instance of RailsERD::Domain and
+    # RailsERD::Diagram will use these options unless overridden.
+    attr_accessor :options
+  end
+
+  self.options = ActiveSupport::OrderedOptions[
+    :type, :pdf,
+    :orientation, :horizontal,
+    :exclude_timestamps, true,
+    :exclude_primary_keys, true,
+    :exclude_foreign_keys, true,
+    :suppress_warnings, false
+  ]
+end

data/lib/rails_erd/attribute.rb

@@ -0,0 +1,74 @@
+# -*- encoding: utf-8
+module RailsERD
+  class Attribute
+    TIMESTAMP_NAMES = %w{created_at created_on updated_at updated_on} #:nodoc:
+
+    class << self
+      def from_model(domain, model) #:nodoc:
+        model.arel_table.columns.collect { |column| Attribute.new(domain, model, column) }.sort
+      end
+    end
+
+    attr_reader :column #:nodoc:
+  
+    def initialize(domain, model, column)
+      @domain, @model, @column = domain, model, column
+    end
+    
+    def name
+      column.name
+    end
+    
+    def type
+      column.type
+    end
+    
+    def mandatory?
+      !column.null or @model.validators_on(name).map(&:kind).include?(:presence)
+    end
+    
+    def primary_key?
+      @model.arel_table.primary_key == name
+    end
+  
+    def foreign_key?
+      @domain.relationships_for(@model).map(&:associations).flatten.map(&:primary_key_name).include?(name)
+    end
+    
+    def timestamp?
+      TIMESTAMP_NAMES.include? name
+    end
+    
+    def <=>(other) #:nodoc:
+      name <=> other.name
+    end
+    
+    def inspect #:nodoc:
+      "#<#{self.class.name}:0x%.14x @column=#{name.inspect} @type=#{type.inspect}>" % (object_id << 1)
+    end
+  
+    def to_s #:nodoc:
+      name
+    end
+  
+    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]
+        desc << " ∗" if mandatory? # Add a hair space + low asterisk (Unicode characters).
+      end
+    end
+  end
+end

data/lib/rails_erd/diagram.rb

@@ -0,0 +1,88 @@
+require "rails_erd/domain"
+require "graphviz"
+
+module RailsERD
+  class Diagram
+    NODE_LABEL_TEMPLATE = File.read(File.expand_path("templates/node.erb", File.dirname(__FILE__))) #:nodoc:
+    NODE_WIDTH = 130 #:nodoc:
+    
+    class << self
+      def generate(options = {})
+        new(Domain.generate(options), options).output
+      end
+    end
+    
+    attr_reader :options #:nodoc:
+
+    def initialize(domain, options = {})
+      @domain, @options = domain, RailsERD.options.merge(options)
+    end
+    
+    def graph
+      @graph ||= GraphViz.new(@domain.name, :type => :digraph) do |graph|
+        graph[:rankdir] = horizontal? ? :LR : :TB
+        graph[:ranksep] = 0.5
+        graph[:nodesep] = 0.35
+        graph[:margin] = "0.4,0.4"
+        graph[:concentrate] = true
+        graph[:label] = "#{@domain.name} domain model\\n\\n"
+        graph[:labelloc] = :t
+        graph[:fontsize] = 13
+        graph[:fontname] = "Arial Bold"
+        graph[:remincross] = true
+        graph[:outputorder] = :edgesfirst
+
+        graph.node[:shape] = "Mrecord"
+        graph.node[:fontsize] = 10
+        graph.node[:fontname] = "Arial"
+        graph.node[:margin] = "0.07,0.05"
+
+        graph.edge[:fontname] = "Arial"
+        graph.edge[:fontsize] = 8
+        graph.edge[:dir] = :both
+        graph.edge[:arrowsize] = 0.8
+        
+        nodes = {}
+
+        @domain.entities.select(&:connected?).each do |entity|
+          attributes = 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?
+          }
+          
+          nodes[entity] = graph.add_node entity.name, :html => ERB.new(NODE_LABEL_TEMPLATE, nil, "<>").result(binding)
+        end
+
+        @domain.relationships.each do |relationship|
+          options = {}
+          options[:arrowhead] = relationship.cardinality.one_to_one? ? :dot : :normal
+          options[:arrowtail] = relationship.cardinality.many_to_many? ? :normal : :dot
+          options[:weight] = relationship.strength
+          options.merge! :style => :dashed, :constraint => false if relationship.indirect?
+
+          graph.add_edge nodes[relationship.source], nodes[relationship.destination], options
+        end
+      end
+    end
+    
+    def output
+      graph.output(options.type.to_sym => file_name)
+      self
+    end
+    
+    def file_name
+      "ERD.#{options.type}"
+    end
+    
+    private
+    
+    def horizontal?
+      options.orientation == :horizontal
+    end
+
+    def vertical?
+      !horizontal?
+    end
+  end
+end

data/lib/rails_erd/domain.rb

@@ -0,0 +1,102 @@
+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.
+  class Domain
+    class << self
+      # Generates a domain model object based on all loaded subclasses of
+      # <tt>ActiveRecord::Base</tt>. Make sure your models are loaded before calling
+      # this method.
+      #
+      # The +options+ hash allows you to override the default options. For a
+      # list of available options, see RailsERD.
+      def generate(options = {})
+        new ActiveRecord::Base.descendants, options
+      end
+    end
+    
+    attr_reader :options #:nodoc:
+
+    # 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)
+    end
+
+    # Returns the domain model name, which is the name of your Rails
+    # application or +nil+ outside of Rails.
+    def name
+      defined? Rails and Rails.application and Rails.application.class.parent.name
+    end
+    
+    # Returns all entities of your domain model.
+    def entities
+      @entities ||= entity_mapping.values.sort
+    end
+    
+    # Returns all relationships in your domain model.
+    def relationships
+      @relationships ||= Relationship.from_associations(self, associations)
+    end
+    
+    # Returns a specific entity object for the given +ActiveRecord+ model.
+    def entity_for(model) #:nodoc:
+      entity_mapping[model] or raise "model #{model} exists, but is not included in the domain"
+    end
+    
+    # Returns an array of relationships for the given +ActiveRecord+ model.
+    def relationships_for(model) #:nodoc:
+      relationships_mapping[model] or []
+    end
+  
+    def inspect #:nodoc:
+      "#<#{self.class} {#{relationships.map { |rel| "#{rel.from} => #{rel.to}" } * ", "}}>"
+    end
+    
+    private
+    
+    def entity_mapping
+      @entity_mapping ||= Hash[@models.collect { |model| [model, Entity.new(self, model)] }]
+    end
+    
+    def relationships_mapping
+      @relationships_mapping ||= {}.tap do |mapping|
+        relationships.each do |relationship|
+          (mapping[relationship.source.model] ||= []) << relationship
+          (mapping[relationship.destination.model] ||= []) << relationship
+        end
+      end
+    end
+    
+    def associations
+      @associations ||= @models.collect(&:reflect_on_all_associations).flatten.select { |assoc| check_association_validity(assoc) }
+    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
+    rescue => e
+      warn "Invalid association #{association_description(association)} (#{e.message})"
+    end
+    
+    def warn(message)
+      puts "Warning: #{message}" unless options.suppress_warnings
+    end
+    
+    def association_description(association)
+      "#{association.name.inspect} on #{association.active_record}"
+    end
+  end
+end

data/lib/rails_erd/entity.rb

@@ -0,0 +1,50 @@
+module RailsERD
+  # Entities represent your +ActiveRecord+ models. Entities may be connected
+  # to other entities.
+  class Entity
+    # The domain in which this entity resides.
+    attr_reader :domain
+    
+    # The +ActiveRecord+ model that this entity corresponds to.
+    attr_reader :model
+
+    def initialize(domain, model) #:nodoc:
+      @domain, @model = domain, model
+    end
+    
+    # Returns an array of attributes for this entity.
+    def attributes
+      @attributes ||= Attribute.from_model @domain, @model
+    end
+    
+    # Returns an array of all relationships that this entity has with other
+    # entities in the domain model.
+    def relationships
+      @domain.relationships_for(@model)
+    end
+    
+    # Returns +true+ if this entity has any relationships with other models,
+    # +false+ otherwise.
+    def connected?
+      relationships.any?
+    end
+  
+    # Returns the name of this entity, which is the class name of the
+    # corresponding model.
+    def name
+      model.name
+    end
+  
+    def inspect #:nodoc:
+      "#<#{self.class}:0x%.14x @model=#{name}>" % (object_id << 1)
+    end
+    
+    def to_s #:nodoc:
+      name
+    end
+  
+    def <=>(other) #:nodoc:
+      self.name <=> other.name
+    end
+  end
+end