rails-erd 0.1.0 → 0.1.1

data/.gitignore

@@ -1 +1,3 @@
 doc
+pkg
+rdoc

data/CHANGES.rdoc

@@ -1,3 +1,8 @@
+=== 0.1.1
+
+* Fixed small errors in Ruby 1.8.7.
+* Abort generation of diagrams when there are no models.
+
 === 0.1.0
 
 * Released on September 20th, 2010.

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2010 Voormedia
+Copyright (c) 2010 Voormedia B.V.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.rdoc

@@ -1,28 +1,61 @@
 = 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
+Rails ERD is a Rails plugin that allows you to easily generate a diagram based
+on your ActiveRecord 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 ActiveRecord reflection
-to figure out how your models are associated.
+to figure out how your models are associated. For older Rails applications,
+you may want to try Railroad[http://railroad.rubyforge.org/].
+
+== Links
+
+Current documentation:
+http://rails-erd.rubyforge.org/doc/
+
+Source code at Github:
+http://github.com/voormedia/rails-erd
+
+Homepage:
+http://rails-erd.rubyforge.org/
+
+== Example output
+
+This is an example diagram from an actual Rails application.
+
+http://rails-erd.rubyforge.org/examples/event-forms.png
+
+{Download generated PDF}[http://rails-erd.rubyforge.org/examples/event-forms.pdf]
+
+Typo is a blogging application built in Rails. This is an excerpt from the
+diagram that was generated from the Rails 3 branch (which is currently still
+in development).
+
+http://rails-erd.rubyforge.org/examples/typo-blog.png
+
+{Download complete diagram as PDF}[http://rails-erd.rubyforge.org/examples/typo-blog.pdf]
+
 
 == 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.
+Graphviz[http://www.graphviz.org/] visualisation library. In order to create
+PDF files (the default), you should install or compile Graphviz with support
+for Pango and Cairo.
 
-For example, to install Graphviz with MacPorts:
+For example, to install Graphviz with Homebrew:
 
-  % sudo port install graphviz
+  % brew install cairo pango graphviz
 
-Or with Homebrew:
+Or with MacPorts:
 
-  % brew install cairo pango graphviz
+  % sudo port install graphviz
 
 Next, install Rails ERD. Open your +Gemfile+, and add the following:
 
@@ -39,18 +72,110 @@ Entity-Relationship Diagram for your Rails application:
 
   % rake erd
 
-All done! You will now have a file named +ERD.pdf+ in your application root.
+All done! You will now have a file named <tt>ERD.pdf</tt> in your application root.
 
-== Advanced use
+== Customisation
 
 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
+  % rake erd orientation=vertical exclude_timestamps=false
+
+exclude_foreign_keys:: Excludes foreign key columns from attribute lists.
+                       Defaults to +true+.
+exclude_primary_keys:: Excludes primary key columns from attribute lists.
+                       Defaults to +true+.
+exclude_timestamps:: Excludes timestamp columns (<tt>created_at/on</tt> and
+                     <tt>updated_at/on</tt>) from attribute lists. Defaults
+                     to +true+.
+exclude_unconnected:: Excludes entities that are not connected to other
+                      entities from the diagram. Defaults to +true+.
+file_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. The available formats depend on your installation
+            of Graphviz.
+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.
+suppress_warnings:: When set to +true+, no warnings are printed to the
+                    command line while processing the domain model. Defaults
+                    to +false+.
+
+== Advanced use
+
+Rails ERD also allows you to use its internal API to inspect your Rails domain
+model. It is easy to generate alternative presentations of your Active Record
+models this way. If used outside of Rails, install Rails ERD as a gem:
+
+  % gem install rails-erd
 
-For an overview of all available options, see the documentation of RailsERD:
+Suppose we have the following models:
+
+  class User < ActiveRecord::Base
+    has_many :posts
+    has_many :comments
+  end
+  
+  class Post < ActiveRecord::Base
+    belongs_to :user
+    has_many :comments
+  end
+  
+  class Comment < ActiveRecord::Base
+    belongs_to :user
+    belongs_to :post
+  end
+
+Then you can inspect your domain model like this:
+
+  require "rails_erd/domain"
+
+  domain = RailsERD::Domain.generate
+  domain.entities
+  #=> [ #<RailsERD::Entity @model=Comment>,
+  #     #<RailsERD::Entity @model=Post>,
+  #     #<RailsERD::Entity @model=User> ]
+  
+  domain.entities.first.connected?
+  #=> true
+  
+  domain.relationships
+  #=> [ #<RailsERD::Relationship @source=Post @destination=Comment>,
+  #     #<RailsERD::Relationship @source=User @destination=Comment>,
+  #     #<RailsERD::Relationship @source=User @destination=Post> ]
+  
+  domain.relationships.first.destination
+  #=> Comment
+  
+  domain.relationships.first.mutual?
+  #=> true
+  
+  domain.relationships.first.cardinality
+  #=> RailsERD::Relationship::Cardinality::OneToMany
+
+The above is just a sample of what is possible. See the API documentation for
+more details:
 http://rails-erd.rubyforge.org/doc/
 
+If you wish to generate your own graphs, take a look at how the default
+diagrams are being generated. See the source of RailsERD::Diagram:
+http://github.com/voormedia/rails-erd/blob/master/lib/rails_erd/diagram.rb
+
+Please note that before the 1.0 release, the API may change subtly between
+minor versions.
+
+== About Rails ERD
+
+Author: Rolf Timmermans (r.timmermans <i>at</i> voormedia.com)
+
+Copyright 2010 Voormedia B.V.
+
 == License
 
-Rails ERD is released under the MIT license.
+Rails ERD is released under the MIT license. See the LICENSE.
+
+== Credits
+
+Rails ERD depends on the Ruby-Graphviz library to generate diagrams:
+http://github.com/glejeune/Ruby-Graphviz/

data/Rakefile

@@ -6,7 +6,7 @@ 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.description = "Automatically generate an entity-relationship diagram (ERD) for your Rails models."
 
   spec.authors = ["Rolf Timmermans"]
   spec.email = "r.timmermans@voormedia.com"
@@ -20,18 +20,21 @@ Jeweler::GemcutterTasks.new
 
 Jeweler::RubyforgeTasks.new do |rubyforge|
   rubyforge.doc_task = "rdoc"
+  rubyforge.remote_doc_path = "doc"
 end
 
 Rake::TestTask.new do |test|
   test.pattern = "test/unit/**/*_test.rb"
 end
 
+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_dir = "doc"
+    rdoc.rdoc_dir = "rdoc"
   end
 rescue => e
   puts e.message

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.1

data/lib/rails_erd.rb

@@ -5,21 +5,36 @@ require "rails_erd/railtie" if defined? Rails
 # 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.
+# exclude_foreign_keys:: Excludes foreign key columns from attribute lists.
+#                        Defaults to +true+.
+# exclude_primary_keys:: Excludes primary key columns from attribute lists.
+#                        Defaults to +true+.
+# exclude_timestamps:: Excludes timestamp columns (<tt>created_at/on</tt> and
+#                      <tt>updated_at/on</tt>) from attribute lists. Defaults
+#                      to +true+.
+# exclude_unconnected:: Excludes entities that are not connected to other
+#                       entities from the diagram. Defaults to +true+.
+# file_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+.
+#               or +:vertical+. Defaults to +:horizontal+. The orientation of the
+#               PDF that is generated depends on the amount of hierarchy
+#               in your models.
 # 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+.
+#
+# You can specify the option on the command line if you use Rails ERD with
+# Rake:
+#
+#   % rake erd orientation=vertical exclude_timestamps=false
+#
+# When using Rails ERD from within Ruby, you can set the options on the
+# RailsERD namespace module:
+#
+#   RailsERD.options.orientation = :vertical
+#   RailsERD.options.exclude_timestamps = false
 module RailsERD
   class << self
     # Access to default options. Any instance of RailsERD::Domain and
@@ -28,11 +43,12 @@ module RailsERD
   end
 
   self.options = ActiveSupport::OrderedOptions[
-    :type, :pdf,
-    :orientation, :horizontal,
-    :exclude_timestamps, true,
-    :exclude_primary_keys, true,
     :exclude_foreign_keys, true,
+    :exclude_primary_keys, true,
+    :exclude_timestamps, true,
+    :exclude_unconnected, true,
+    :file_type, :pdf,
+    :orientation, :horizontal,
     :suppress_warnings, false
   ]
 end

data/lib/rails_erd/attribute.rb

@@ -1,5 +1,7 @@
 # -*- encoding: utf-8
 module RailsERD
+  # Describes an entity's attribute. Attributes correspond directly to
+  # database columns.
   class Attribute
     TIMESTAMP_NAMES = %w{created_at created_on updated_at updated_on} #:nodoc:
 
@@ -11,30 +13,42 @@ module RailsERD
 
     attr_reader :column #:nodoc:
   
-    def initialize(domain, model, column)
+    def initialize(domain, model, column) #: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 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?
       @model.arel_table.primary_key == name
     end
   
+    # Returns +true+ if this attribute is used as a foreign key for any
+    # relationship.
     def foreign_key?
       @domain.relationships_for(@model).map(&:associations).flatten.map(&:primary_key_name).include?(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
@@ -51,6 +65,14 @@ module RailsERD
       name
     end
   
+    # Returns a short 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 *
     def type_description
       case type
       when :integer       then "int"

data/lib/rails_erd/diagram.rb

@@ -1,12 +1,23 @@
 require "rails_erd/domain"
 require "graphviz"
+require "erb"
 
 module RailsERD
+  # Create Graphviz-based diagrams based on the domain model. For easy
+  # command line graph generation, you can use rake:
+  #
+  #   % rake erd
+  #
+  # Please see the README.rdoc file for more details on how to use Rails ERD
+  # from the command line.
   class Diagram
     NODE_LABEL_TEMPLATE = File.read(File.expand_path("templates/node.erb", File.dirname(__FILE__))) #:nodoc:
     NODE_WIDTH = 130 #:nodoc:
     
     class << self
+      # Generate a new domain model based on all <tt>ActiveRecord::Base</tt>
+      # subclasses, and create a new diagram. Use the given options for both
+      # the domain generation and the diagram generation.
       def generate(options = {})
         new(Domain.generate(options), options).output
       end
@@ -14,10 +25,24 @@ module RailsERD
     
     attr_reader :options #:nodoc:
 
+    # Create a new diagram based on the given domain.
     def initialize(domain, options = {})
       @domain, @options = domain, RailsERD.options.merge(options)
     end
     
+    # Save the diagram.
+    def output
+      graph.output(options.file_type.to_sym => file_name)
+      self
+    end
+    
+    # Returns the file name that will be used when saving the diagram.
+    def file_name
+      "ERD.#{options.file_type}"
+    end
+    
+    private
+    
     def graph
       @graph ||= GraphViz.new(@domain.name, :type => :digraph) do |graph|
         graph[:rankdir] = horizontal? ? :LR : :TB
@@ -44,16 +69,23 @@ module RailsERD
         
         nodes = {}
 
-        @domain.entities.select(&:connected?).each do |entity|
+        @domain.entities.each do |entity|
+          if options.exclude_unconnected && !entity.connected?
+            warn "Skipping unconnected model #{entity.name} (use exclude_unconnected=false to include)"
+            next
+          end
+          
           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)
+          nodes[entity] = graph.add_node entity.name, :label => "<" + ERB.new(NODE_LABEL_TEMPLATE, nil, "<>").result(binding) + ">"
         end
-
+        
+        raise "No (connected) entities found; create your models first!" if nodes.empty?
+        
         @domain.relationships.each do |relationship|
           options = {}
           options[:arrowhead] = relationship.cardinality.one_to_one? ? :dot : :normal
@@ -66,17 +98,6 @@ module RailsERD
       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
@@ -84,5 +105,9 @@ module RailsERD
     def vertical?
       !horizontal?
     end
+
+    def warn(message)
+      puts "Warning: #{message}" unless options.suppress_warnings
+    end
   end
 end

data/lib/rails_erd/domain.rb

@@ -45,12 +45,12 @@ module RailsERD
       @relationships ||= Relationship.from_associations(self, associations)
     end
     
-    # Returns a specific entity object for the given +ActiveRecord+ model.
+    # Returns a specific entity object for the given Active Record 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.
+    # Returns an array of relationships for the given Active Record model.
     def relationships_for(model) #:nodoc:
       relationships_mapping[model] or []
     end

data/lib/rails_erd/entity.rb

@@ -1,11 +1,11 @@
 module RailsERD
-  # Entities represent your +ActiveRecord+ models. Entities may be connected
+  # Entities represent your Active Record 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.
+    # The Active Record model that this entity corresponds to.
     attr_reader :model
 
     def initialize(domain, model) #:nodoc:

data/lib/rails_erd/relationship.rb

@@ -1,4 +1,8 @@
 module RailsERD
+  # Describes a relationship between two entities. A relationship is detected
+  # based on Active Record associations. One relationship may represent more
+  # than one association, however. Associations that share the same foreign
+  # key are grouped together.
   class Relationship
     class << self
       def from_associations(domain, associations) #:nodoc:
@@ -14,16 +18,15 @@ module RailsERD
       end
     end
 
-    # Returns the domain in which this relationship is defined.
+    # The domain in which this relationship is defined.
     attr_reader :domain
 
-    # Returns the source entity. The source entity corresponds to the model
-    # that has defined a +has_one+ or +has_many+ association with the other
-    # model.
+    # The source entity. It corresponds to the model that has defined a
+    # +has_one+ or +has_many+ association with the other model.
     attr_reader :source
     
-    # Returns the destination entity. The destination entity corresponds to the
-    # model that has defined a +belongs_to+ association with the other model.
+    # The destination entity. It corresponds to the model that has defined
+    # a +belongs_to+ association with the other model.
     attr_reader :destination
   
     def initialize(domain, associations) #:nodoc:
@@ -35,7 +38,7 @@ module RailsERD
       @source, @destination = @destination, @source if assoc.belongs_to?
     end
     
-    # Returns all +ActiveRecord+ association objects that describe this
+    # Returns all Active Record association objects that describe this
     # relationship.
     def associations
       @forward_associations + @reverse_associations

data/lib/rails_erd/relationship/cardinality.rb

@@ -5,6 +5,7 @@ module RailsERD
       ORDER = {} #:nodoc:
 
       class << self
+        # Returns the cardinality as symbol.
         attr_reader :type
 
         def from_macro(macro) #:nodoc:

data/test/test_helper.rb

@@ -1,3 +1,4 @@
+require "rubygems"
 require "test/unit"
 require "active_support/test_case"
 
@@ -66,7 +67,7 @@ class ActiveSupport::TestCase
       ActiveRecord::Base.connection.drop_table table
     end
     ActiveRecord::Base.direct_descendants.clear
-    Arel::Relation.class_variable_set :@@connection_tables_primary_keys, {}
+    Arel::Relation.send :class_variable_set, :@@connection_tables_primary_keys, {}
     ActiveSupport::Dependencies::Reference.clear!
   end
 end

data/test/unit/diagram_test.rb

@@ -0,0 +1,34 @@
+require File.expand_path("../test_helper", File.dirname(__FILE__))
+
+require "rails_erd/diagram"
+
+class DiagramTest < ActiveSupport::TestCase
+  def teardown
+    FileUtils.rm "ERD.dot" rescue nil
+  end
+  
+  # Diagram generation =======================================================
+  test "generate should create output based on domain model" do
+    create_model "Foo", :bar => :references do
+      belongs_to :bar
+    end
+    create_model "Bar"
+    RailsERD::Diagram.generate(:file_type => :dot)
+    assert File.exists?("ERD.dot")
+  end
+
+  test "generate should not create output if there are no connected models" do
+    RailsERD::Diagram.generate(:file_type => :dot) rescue nil
+    assert !File.exists?("ERD.dot")
+  end
+
+  test "generate should abort and complain if there are no connected models" do
+    message = nil
+    begin
+      RailsERD::Diagram.generate(:file_type => :dot)
+    rescue => e
+      message = e.message
+    end
+    assert_match /No \(connected\) entities found/, message
+  end
+end

metadata

@@ -1,12 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: rails-erd
 version: !ruby/object:Gem::Version 
+  hash: 25
   prerelease: false
   segments: 
   - 0
   - 1
-  - 0
-  version: 0.1.0
+  - 1
+  version: 0.1.1
 platform: ruby
 authors: 
 - Rolf Timmermans
@@ -25,6 +26,7 @@ dependencies:
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
+        hash: 7
         segments: 
         - 3
         - 0
@@ -40,6 +42,7 @@ dependencies:
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
+        hash: 25
         segments: 
         - 0
         - 9
@@ -47,7 +50,7 @@ dependencies:
         version: 0.9.17
   type: :runtime
   version_requirements: *id002
-description: Automatically generate an entity-relationship diagram (ERD) for the models in your Rails application.
+description: Automatically generate an entity-relationship diagram (ERD) for your Rails models.
 email: r.timmermans@voormedia.com
 executables: []
 
@@ -95,6 +98,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
@@ -103,6 +107,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"