openrain-activerecord-comments 0.1.1

data/README.markdown

@@ -0,0 +1,85 @@
+activerecord-comments
+=====================
+
+Super-duper simple gem for getting table/column comments defined in the database.
+
+Background
+----------
+
+I wanted a way to easily get to the comments defined in the database, via ActiveRecord. 
+While the underlying implementation may change to become faster and more database agnostic, 
+the public API should remain the same.
+
+Install
+-------
+
+    $ sudo gem install remi-activerecord-comments -s http://gems.github.com
+
+Usage
+-----
+
+    >> require 'activerecord-comments'
+    
+    >> Fox.comment
+    => "Represents a Fox, a creature that craves chunky bacon"
+
+    >> ActiveRecord::Base.comment :foxes
+    => "Represents a Fox, a creature that craves chunky bacon"
+
+    >> ActiveRecord::Base.connection.comment :foxes
+    => "Represents a Fox, a creature that craves chunky bacon"
+
+    >> Fox.columns
+    => [#<ActiveRecord::...>, #<ActiveRecord::...>]
+
+    >> Fox.columns.first.name
+    => "id"
+
+    >> Fox.columns.first.comment
+    => "Primary Key"
+
+    >> Fox.column_comment :id
+    => "Primary Key"
+
+    >> ActiveRecord::Base.column_comment :id, :foxes
+    => "Primary Key"
+
+    >> ActiveRecord::Base.connection.column_comment :id, :foxes
+    => "Primary Key"
+
+
+Database Support
+----------------
+
+For right now, I'm just supporting MySQL as it's the only database I'm currently using 
+that supports database comments.
+
+If you want to extend activerecord-comments to support comments for your favorite database, 
+the gem is coded in such a way that it should be really easy to extend.
+
+See [mysql_adapter.rb][mysql_adapter] for an example of the methods your database adapter 
+needs to support (just `#comment(table)` and `#column_comment(column,table)`).
+
+
+SQL
+---
+
+If you're unsure how to add comments to your MySQL tables/columns, most MySQL GUIs support 
+this, or you can add comments to your `CREATE TABLE` declarations ...
+
+    CREATE TABLE foo ( 
+      id INT COMMENT 'i am the primary key', 
+      foo VARCHAR(100) COMMENT 'foo!' 
+    ) COMMENT 'this table rocks'
+
+for more MySQL examples, see [spec/mysql_comments_spec.rb][mysql_spec]
+
+
+Future Ideas
+------------
+
+- create `db-doc` or (something) that provides a system for documenting your database schema, whether it be via .yml files or as database comments or whatever.  then make `activerecord-comments` an extension to that (basically just a different data store for your schema documentation).  there should always be a way to easily document your schema, regardless of whether or not your database(s) supports comments.  and, with or without database comments, there should be an easy way to see which tables/columns you have and haven't documented!
+
+
+[mysql_adapter]: http://github.com/remi/activerecord-comments/tree/master/lib/activerecord-comments/mysql_adapter.rb
+[mysql_spec]:    http://github.com/remi/activerecord-comments/tree/master/spec/mysql_comments_spec.rb

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 0
+:minor: 1
+:patch: 1

data/lib/activerecord-comments.rb

@@ -0,0 +1,29 @@
+$:.unshift File.dirname(__FILE__)
+
+if defined?(ActiveRecord)
+
+  # Main class for ActiveRecord::Comments ActiveRecord extension gem
+  #
+  # Used for global configuration options / etc for the extension
+  class ActiveRecord::Comments
+  end
+
+  class ActiveRecord::Comments::UnsupportedDatabase < Exception; end
+
+end
+
+if defined?(ActiveRecord::Base) && 
+   defined?(ActiveRecord::ConnectionAdapters::Column) && 
+   defined?(ActiveRecord::ConnectionAdapters::AbstractAdapter)
+  
+  # require and include our modules which add the 'comment' functionality to ActiveRecord
+
+  require 'activerecord-comments/base_ext'
+  require 'activerecord-comments/column_ext'
+  require 'activerecord-comments/abstract_adapter_ext'
+
+  ActiveRecord::Base.send                                 :include, ActiveRecord::Comments::BaseExt
+  ActiveRecord::ConnectionAdapters::Column.send           :include, ActiveRecord::Comments::ColumnExt
+  ActiveRecord::ConnectionAdapters::AbstractAdapter.send  :include, ActiveRecord::Comments::AbstractAdapterExt
+
+end

data/lib/activerecord-comments/abstract_adapter_ext.rb

@@ -0,0 +1,103 @@
+module ActiveRecord::Comments::AbstractAdapterExt
+
+  def self.included base
+    puts "including abstract adapter extensions in #{ base.inspect }"
+
+    base.instance_eval {
+      alias_method_chain :columns, :table_name # this is evil!!!  how to fix?  column needs to know its table  :(
+    }
+  end
+
+  # Get the database comment (if any) defined for a table
+  #
+  # ==== Parameters
+  # table<~to_s>::
+  #   The name of the table to get the comment for
+  #
+  # ==== Returns
+  # String:: The comment for the given table (or nil if no comment)
+  #
+  # :api: public
+  def comment table
+    adapter = adapter_name.downcase
+    database_specific_method_name = "#{ adapter }_comment"
+    
+    if self.respond_to? database_specific_method_name
+      send database_specific_method_name, table.to_s
+    else
+
+      # try requiring 'activerecord-comments/[name-of-adapter]_adapter'
+      begin
+
+        # see if there right method exists after requiring
+        require "activerecord-comments/#{ adapter }_adapter"
+        if self.respond_to? database_specific_method_name
+          send database_specific_method_name, table.to_s
+        else
+          raise ActiveRecord::Comments::UnsupportedDatabase.new("#{adapter} unsupported by ActiveRecord::Comments")
+        end
+
+      rescue LoadError
+        raise ActiveRecord::Comments::UnsupportedDatabase.new("#{adapter} unsupported by ActiveRecord::Comments")
+      end
+    end
+  end
+
+  # Get the database comment (if any) defined for a column
+  #
+  # ==== Parameters
+  # column<~to_s>::
+  #   The name of the column to get the comment for
+  #
+  # table<~to_s>::
+  #   The name of the table to get the column comment for
+  #
+  # ==== Returns
+  # String:: The comment for the given column (or nil if no comment)
+  #
+  # :api: public
+  def column_comment column, table
+    adapter = adapter_name.downcase
+    database_specific_method_name = "#{ adapter }_column_comment"
+    
+    if self.respond_to? database_specific_method_name
+      send database_specific_method_name, column.to_s, table.to_s
+    else
+
+      # try requiring 'activerecord-comments/[name-of-adapter]_adapter'
+      begin
+
+        # see if there right method exists after requiring
+        require "activerecord-comments/#{ adapter }_adapter"
+        if self.respond_to? database_specific_method_name
+          send database_specific_method_name, column.to_s, table.to_s
+        else
+          raise ActiveRecord::Comments::UnsupportedDatabase.new("#{adapter} unsupported by ActiveRecord::Comments")
+        end
+
+      rescue LoadError
+        raise ActiveRecord::Comments::UnsupportedDatabase.new("#{adapter} unsupported by ActiveRecord::Comments")
+      end
+    end
+  end
+
+  # Extends #columns, setting @table_name as an instance variable 
+  # on each of the column instances that are returned
+  #
+  # ==== Returns
+  # Array[ActiveRecord::ConnectionAdapters::Column]::
+  #   Returns an Array of column objects, each with @table_name set
+  #
+  # :api: private
+  def columns_with_table_name *args
+    puts "\n\n HELLO ???? HELLO ????? \n\n"
+    puts "asking adapter for columns for #{ args.inspect }"
+    columns = columns_without_table_name *args
+    table = self.table_name # make table_name available as variable in instanve_eval closure
+    columns.each do |column|
+      column.instance_eval { @table_name = table }
+    end
+    columns
+  end
+
+end

data/lib/activerecord-comments/base_ext.rb

@@ -0,0 +1,71 @@
+module ActiveRecord::Comments::BaseExt
+
+  def self.included base
+    base.extend ClassMethods
+
+    base.instance_eval {
+      class << self
+        alias_method_chain :columns, :table_name # this is evil!!!  how to fix?  column needs to know its table  :(
+      end
+    }
+  end
+
+  module ClassMethods
+
+    # Get the database comment (if any) defined for a table
+    #
+    # ==== Parameters
+    # table<~to_s>::
+    #   The name of the table to get the comment for, default is 
+    #   the #table_name of the ActiveRecord::Base class this is 
+    #   being called on, eg. +User.comment+
+    #
+    # ==== Returns
+    # String:: The comment for the given table (or nil if no comment)
+    #
+    # :api: public
+    def comment table = self.table_name
+      connection.comment table
+    end
+
+    # Get the database comment (if any) defined for a column
+    #
+    # TODO move into adapter!
+    #
+    # ==== Parameters
+    # column<~to_s>::
+    #   The name of the column to get the comment for
+    #
+    # table<~to_s>::
+    #   The name of the table to get the column comment for, default is 
+    #   the #table_name of the ActiveRecord::Base class this is 
+    #   being called on, eg. +User.column_comment 'username'+
+    #
+    # ==== Returns
+    # String:: The comment for the given column (or nil if no comment)
+    #
+    # :api: public
+    def column_comment column, table = self.table_name
+      connection.column_comment column, table
+    end
+
+    # Extends ActiveRecord::Base#columns, setting @table_name as an instance variable 
+    # on each of the column instances that are returned
+    #
+    # ==== Returns
+    # Array[ActiveRecord::ConnectionAdapters::Column]::
+    #   Returns an Array of column objects, each with @table_name set
+    #
+    # :api: private
+    def columns_with_table_name *args
+      columns = columns_without_table_name *args
+      table = self.table_name # make table_name available as variable in instanve_eval closure
+      columns.each do |column|
+        column.instance_eval { @table_name = table }
+      end
+      columns
+    end
+
+  end
+
+end

data/lib/activerecord-comments/column_ext.rb

@@ -0,0 +1,8 @@
+module ActiveRecord::Comments::ColumnExt
+  attr_reader :table_name
+
+  def comment
+    raise "table_name not set for column #{ self.inspect }" if table_name.nil? or table_name.empty?
+    ActiveRecord::Base.column_comment name, table_name
+  end
+end

data/lib/activerecord-comments/mysql_adapter.rb

@@ -0,0 +1,139 @@
+module ActiveRecord::Comments::MysqlAdapter
+
+  def self.included base
+    base.extend ClassMethods
+  end
+
+  module ClassMethods
+
+    # MySQL implementation of ActiveRecord::Comments::BaseExt#comment
+    def mysql_comment table
+      table_options = create_table_sql(table).split("\n").last
+      if table_options =~ /COMMENT='/
+        /COMMENT='(.*)'/.match(table_options).captures.first
+      else
+        nil
+      end
+    end
+
+    # MySQL implementation of ActiveRecord::Comments::BaseExt#column_comment
+    def mysql_column_comment column, table
+      column_creation_sql = create_column_sql(column, table)
+      if column_creation_sql =~ /COMMENT '/
+        /COMMENT '(.*)'/.match(column_creation_sql).captures.first
+      else
+        nil
+      end
+    end
+
+    private
+
+    # Returns the SQL used to create the given table
+    #
+    # ==== Parameters
+    # table<~to_s>::
+    #   The name of the table to get the 'CREATE TABLE' SQL for
+    #
+    # ==== Returns
+    # String:: the SQL used to create the table
+    #
+    # :api: private
+    def create_table_sql table = table_name
+      connection.execute("show create table `#{ table }`").all_hashes.first['Create Table']
+    end
+
+    # Returns the SQL used to create the given column for the given table
+    #
+    # ==== Parameters
+    # column<~to_s>::
+    #   The name of the column to get the creation SQL for
+    #
+    # table<~to_s>::
+    #   The name of the table to get the 'CREATE TABLE' SQL for
+    #
+    # ==== Returns
+    # String:: the SQL used to create the column
+    #
+    # :api: private
+    def create_column_sql column, table = table_name
+      full_table_create_sql = create_table_sql(table)
+      parts = full_table_create_sql.split("\n")
+      create_table = parts.shift # take off the first CREATE TABLE part
+      create_table_options = parts.pop # take off the last options for the table, leaving just the columns
+      sql_for_this_column = parts.find {|str| str =~ /^ *`#{ column }`/ }
+      sql_for_this_column.strip! if sql_for_this_column
+      sql_for_this_column
+    end
+
+  end
+
+end
+
+ActiveRecord::Base.send :include, ActiveRecord::Comments::MysqlAdapter
+
+################ WE SHOULD DO EVERYTHING ON THE CONNECTION (ADAPTER) INSTEAD!!!!!!
+
+module ActiveRecord::Comments::MysqlAdapterAdapter
+
+  # MySQL implementation of ActiveRecord::Comments::BaseExt#comment
+  def mysql_comment table
+    table_options = create_table_sql(table).split("\n").last
+    if table_options =~ /COMMENT='/
+      /COMMENT='(.*)'/.match(table_options).captures.first
+    else
+      nil
+    end
+  end
+
+  # MySQL implementation of ActiveRecord::Comments::BaseExt#column_comment
+  def mysql_column_comment column, table
+    column_creation_sql = create_column_sql(column, table)
+    if column_creation_sql =~ /COMMENT '/
+      /COMMENT '(.*)'/.match(column_creation_sql).captures.first
+    else
+      nil
+    end
+  end
+
+  private
+
+  # Returns the SQL used to create the given table
+  #
+  # ==== Parameters
+  # table<~to_s>::
+  #   The name of the table to get the 'CREATE TABLE' SQL for
+  #
+  # ==== Returns
+  # String:: the SQL used to create the table
+  #
+  # :api: private
+  def create_table_sql table = table_name
+    execute("show create table `#{ table }`").all_hashes.first['Create Table']
+  end
+
+  # Returns the SQL used to create the given column for the given table
+  #
+  # ==== Parameters
+  # column<~to_s>::
+  #   The name of the column to get the creation SQL for
+  #
+  # table<~to_s>::
+  #   The name of the table to get the 'CREATE TABLE' SQL for
+  #
+  # ==== Returns
+  # String:: the SQL used to create the column
+  #
+  # :api: private
+  def create_column_sql column, table = table_name
+    full_table_create_sql = create_table_sql(table)
+    parts = full_table_create_sql.split("\n")
+    create_table = parts.shift # take off the first CREATE TABLE part
+    create_table_options = parts.pop # take off the last options for the table, leaving just the columns
+    sql_for_this_column = parts.find {|str| str =~ /^ *`#{ column }`/ }
+    sql_for_this_column.strip! if sql_for_this_column
+    sql_for_this_column
+  end
+
+end
+
+ActiveRecord::ConnectionAdapters::AbstractAdapter.send :include, ActiveRecord::Comments::MysqlAdapterAdapter

data/spec/mysql_comments_spec.rb

@@ -0,0 +1,109 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe ActiveRecord::Comments, 'MySQL' do
+
+  # HELPERS
+  
+  def connection
+    ActiveRecord::Base.connection
+  end
+
+  def drop_table
+    connection.execute 'DROP TABLE IF EXISTS foxes;'
+  end
+
+  before do
+    drop_table
+    @foxes = Class.new(ActiveRecord::Base){ set_table_name 'foxes' }
+  end
+
+  # EXAMPLES
+
+  describe ActiveRecord::Base, 'extensions' do
+
+    it "should create table OK" do
+      connection.execute "CREATE TABLE foxes( id INT NOT NULL AUTO_INCREMENT PRIMARY KEY );"
+      @foxes.count.should == 0
+    end
+
+    it "Model#comment should return nil for a model that doesn't have a database comment" do
+      connection.execute "CREATE TABLE foxes( id INT NOT NULL AUTO_INCREMENT PRIMARY KEY );"
+      @foxes.comment.should be_nil
+      ActiveRecord::Base.comment(:foxes).should be_nil
+      ActiveRecord::Base.comment('foxes').should be_nil
+    end
+
+    it "Model#comment should return the database comment for a model that has a database comment" do
+      connection.execute "CREATE TABLE foxes( id INT NOT NULL AUTO_INCREMENT PRIMARY KEY ) COMMENT 'foxes Rule';"
+      @foxes.comment.should == 'foxes Rule'
+      ActiveRecord::Base.comment(:foxes).should == 'foxes Rule'
+      ActiveRecord::Base.comment('foxes').should == 'foxes Rule'
+    end
+
+    it "Model#comment should return the database comment for a model that has a database comment in different formats" do
+      pending
+      #[ 'foxes Rule', 'i has Numbers123', 'i have " double " quotes', "i have ' single quotes'" ].each do
+      #  connection.execute "CREATE TABLE foxes( id INT NOT NULL AUTO_INCREMENT PRIMARY KEY ) COMMENT 'foxes Rule';"
+      #@foxes.comment.should == 'foxes Rule'
+    end
+
+  end
+
+  describe ActiveRecord::ConnectionAdapters::Column, 'extensions' do
+
+    it 'Model#column_comment should return the comment for a column' do
+      connection.execute "CREATE TABLE foxes( id INT NOT NULL AUTO_INCREMENT PRIMARY KEY COMMENT 'i am the ID column' );"
+      @foxes.column_comment('id').should == 'i am the ID column'
+      @foxes.column_comment(:id).should == 'i am the ID column'
+      ActiveRecord::Base.column_comment(:id, :foxes).should == 'i am the ID column'
+      ActiveRecord::Base.column_comment(:id, 'foxes').should == 'i am the ID column'
+      ActiveRecord::Base.column_comment('id', 'foxes').should == 'i am the ID column'
+    end
+
+    it "@column#comment should return nil for a column that doesn't have a database comment" do
+      connection.execute "CREATE TABLE foxes( id INT NOT NULL AUTO_INCREMENT PRIMARY KEY );"
+      @foxes.columns.first.name.should == 'id'
+      @foxes.columns.first.comment.should be_nil
+    end
+
+    # need to add this extension (tho it's yucky) so a column can easily find its comment (needs its table name)
+    it "@column should know its #table_name" do
+      connection.execute "CREATE TABLE foxes( id INT NOT NULL AUTO_INCREMENT PRIMARY KEY );"
+      @foxes.columns.length.should == 1
+      @foxes.columns.first.table_name.should == 'foxes'
+    end
+
+    it "@column#comment should return the database comment for a column that has a database comment" do
+      connection.execute "CREATE TABLE foxes( id INT NOT NULL AUTO_INCREMENT PRIMARY KEY COMMENT 'i am the ID column' );"
+      @foxes.columns.first.name.should == 'id'
+      @foxes.columns.first.comment.should == 'i am the ID column'
+    end
+
+  end
+
+  describe 'Connection', 'extensions' do
+    
+    it "@connection#comment(table) should return the database comment for a table that has a database comment" do
+      connection.execute "CREATE TABLE foxes( id INT NOT NULL AUTO_INCREMENT PRIMARY KEY ) COMMENT 'foxes Rule';"
+      connection.comment('foxes').should == 'foxes Rule'
+      connection.comment(:foxes).should == 'foxes Rule'
+    end
+
+    it "@connection.columns(table) should inject the table name to column objects" do
+      pending "Not implementing this (for now?)"
+      connection.execute "CREATE TABLE foxes( id INT NOT NULL AUTO_INCREMENT PRIMARY KEY COMMENT 'i am the ID column' );"
+      connection.columns(:foxes).length.should == 1
+      connection.columns(:foxes).first.name.should == 'id'
+      connection.columns(:foxes).first.comment.should == 'i am the ID column'
+    end
+
+    it "@connection#column_comment should return the database comment for a column that has a database comment" do
+      connection.execute "CREATE TABLE foxes( id INT NOT NULL AUTO_INCREMENT PRIMARY KEY COMMENT 'i am the ID column' );"
+      connection.column_comment(:id, :foxes).should == 'i am the ID column'
+      connection.column_comment('id', :foxes).should == 'i am the ID column'
+      connection.column_comment('id', 'foxes').should == 'i am the ID column'
+    end
+
+  end
+
+end

data/spec/spec_database.yml

@@ -0,0 +1,6 @@
+--- 
+adapter: mysql
+database: activerecord_comments_test_db
+host: localhost
+username: root
+password: 

data/spec/spec_helper.rb

@@ -0,0 +1,26 @@
+require 'rubygems'
+require 'spec'
+require 'yaml'
+begin
+  require 'activerecord'
+rescue LoadError
+  raise "dependency ActiveRecord not found.  try: $ sudo gem install activerecord"
+end
+
+require File.dirname(__FILE__) + '/../lib/activerecord-comments'
+
+# right now, we run all tests against MySQL (I would also do sqlite but I don't think it supports comments!)
+database_hash = YAML::load File.read(File.dirname(__FILE__) + '/spec_database.yml')
+ActiveRecord::Base.establish_connection database_hash
+
+begin
+  # touch the connection to see if it's OK
+  ActiveRecord::Base.connection
+rescue Mysql::Error => ex
+  if ex.to_s =~ /unknown database/i
+    db = database_hash['database']
+    raise "\n\nMySQL database not found: #{db}.\ntry: $ mysqladmin create #{db}\n\n"
+  else
+    raise ex
+  end
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification 
+name: openrain-activerecord-comments
+version: !ruby/object:Gem::Version 
+  version: 0.1.1
+platform: ruby
+authors: 
+- remi
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-02-03 00:00:00 -08:00
+default_executable: 
+dependencies: []
+
+description: Provides an easy to access database table/column comments from ActiveRecord
+email: remi@remitaylor.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- VERSION.yml
+- README.markdown
+- lib/activerecord-comments
+- lib/activerecord-comments/column_ext.rb
+- lib/activerecord-comments/mysql_adapter.rb
+- lib/activerecord-comments/abstract_adapter_ext.rb
+- lib/activerecord-comments/base_ext.rb
+- lib/activerecord-comments.rb
+- spec/mysql_comments_spec.rb
+- spec/spec_database.yml
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/openrain/activerecord-comments
+post_install_message: 
+rdoc_options: 
+- --inline-source
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Provides an easy to access database table/column comments from ActiveRecord
+test_files: []
+