remi-activerecord-comments 0.1.0

data/README.markdown

@@ -0,0 +1,79 @@
+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"
+
+    >> Fox.columns
+    => [#<ActiveRecord::...>, #<ActiveRecord::...>]
+
+    >> Fox.column_names
+    => ["id", "name", "has_had_truck_stolen"]
+
+    >> Fox.column_comments
+    => ["Primary Key", "Fox's name", "Whether or not this Fox has had his/her truck stolen"]
+
+    >> 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"
+
+
+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]
+
+
+[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/lib/activerecord-comments/base_ext.rb

@@ -0,0 +1,111 @@
+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
+      adapter = connection.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, 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
+      adapter = connection.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 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,7 @@
+module ActiveRecord::Comments::ColumnExt
+  attr_reader :table_name
+
+  def comment
+    ActiveRecord::Base.column_comment name, table_name
+  end
+end

data/lib/activerecord-comments/mysql_adapter.rb

@@ -0,0 +1,72 @@
+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

data/lib/activerecord-comments.rb

@@ -0,0 +1,25 @@
+$:.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)
+  
+  # require and include our modules which add the 'comment' functionality to ActiveRecord
+
+  require 'activerecord-comments/base_ext'
+  require 'activerecord-comments/column_ext'
+
+  ActiveRecord::Base.send                       :include, ActiveRecord::Comments::BaseExt
+  ActiveRecord::ConnectionAdapters::Column.send :include, ActiveRecord::Comments::ColumnExt
+
+end

data/spec/mysql_comments_spec.rb

@@ -0,0 +1,76 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe ActiveRecord::Comments, 'MySQL support' 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
+
+  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
+
+  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

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,63 @@
+--- !ruby/object:Gem::Specification 
+name: remi-activerecord-comments
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- remi
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-02-02 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/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/remi/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: []
+