schema_comments 0.1.0

data/.gitignore

@@ -0,0 +1,4 @@
+*.log
+*~
+/pkg
+/selectable_attr_test.sqlite3.db

data/LICENSE.txt

@@ -0,0 +1,60 @@
+Ruby License
+http://www.ruby-lang.org/en/LICENSE.txt
+ 
+Ruby is copyrighted free software by Yukihiro Matsumoto <matz@netlab.co.jp>.
+You can redistribute it and/or modify it under either the terms of the GPL
+(see COPYING.txt file), or the conditions below:
+ 
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+ 
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+ 
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+	  modifications to Usenet or an equivalent medium, or by allowing
+	  the author to include your modifications in the software.
+ 
+       b) use the modified software only within your corporation or
+          organization.
+ 
+       c) rename any non-standard executables so the names do not conflict
+	  with standard executables, which must also be provided.
+ 
+       d) make other distribution arrangements with the author.
+ 
+  3. You may distribute the software in object code or executable
+     form, provided that you do at least ONE of the following:
+ 
+       a) distribute the executables and library files of the software,
+	  together with instructions (in the manual page or equivalent)
+	  on where to get the original distribution.
+ 
+       b) accompany the distribution with the machine-readable source of
+	  the software.
+ 
+       c) give non-standard executables non-standard names, with
+          instructions on where to get the original software distribution.
+ 
+       d) make other distribution arrangements with the author.
+ 
+  4. You may modify and include the part of the software into any other
+     software (possibly commercial).  But some files in the distribution
+     are not written by the author, so that they are not under this terms.
+ 
+     They are gc.c(partly), utils.c(partly), regex.[ch], st.[ch] and some
+     files under the ./missing directory.  See each file for the copying
+     condition.
+ 
+  5. The scripts and library files supplied as input to or produced as 
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whomever generated them, 
+     and may be sold commercially, and may be aggregated with this
+     software.
+ 
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.

data/README

@@ -0,0 +1,149 @@
+SchemaComments 
+==========
+
+== Install ==
+
+=== as a plugin
+ ruby script/plugin install git://github.com/akm/schema_comments.git
+
+=== as a gem
+insert following line to config/environment.rb
+  config.gem 'schema_comments', :version => '0.1.0'
+and 
+ $ sudo rake gems:install
+
+Or install gem manually
+
+ $ sudo gem install gemcutter
+ $ sudo gem tumble
+ $ sudo gem install schema_comments
+
+== Configuration
+If you install schema_comments as a gem, must create config/initializers/schema_comments.rb like this:
+ require 'schema_comments'
+ SchemaComments.setup
+
+
+== overview ==
+schema_commentsプラグインを使うと、テーブルとカラムにコメントを記述することができます。
+
+ class CreateProducts < ActiveRecord::Migration
+   def self.up
+     create_table "products", :comment => '商品' do |t|
+       t.string   "product_type_cd", :comment => '種別コード'
+       t.integer  "price", :comment => "価格"
+       t.string   "name", :comment => "商品名"
+       t.datetime "created_at", :comment => "登録日時"
+       t.datetime "updated_at", :comment => "更新日時"
+     end
+   end
+
+   def self.down
+     drop_table "products"
+   end
+ end
+
+こんな感じ。
+
+でこのようなマイグレーションを実行すると、db/schema.rb には、
+コメントが設定されているテーブル、カラムは以下のように出力されます。
+
+ActiveRecord::Schema.define(:version => 0) do
+  create_table "products", :force => true, :comment => '商品' do |t|
+    t.string   "product_type_cd", :comment => '種別コード'
+    t.integer  "price", :comment => "価格"
+    t.string   "name", :comment => "商品名"
+    t.datetime "created_at", :comment => "登録日時"
+    t.datetime "updated_at", :comment => "更新日時"
+  end
+end
+
+
+コメントは、以下のメソッドで使用することが可能です。
+
+columns, create_table, drop_table, rename_table
+remove_column, add_column, change_column
+
+
+== コメントはどこに保存されるのか ==
+db/schema_comments.yml にYAML形式で保存されます。
+あまり推奨しませんが、もしマイグレーションにコメントを記述するのを忘れてしまった場合、db/schema_comments.yml
+を直接編集した後、rake db:schema:dumpやマイグレーションを実行すると、db/schema.rbのコメントに反映されます。
+
+
+== I18nへの対応 ==
+rake i18n:schema_comments:update_config_localeタスクを実行すると、i18n用のYAMLを更新できます。
+
+rake i18n:schema_comments:update_config_locale LOCALE=ja でデフォルトではconfig/locales/ja.ymlを更新します。
+
+毎回LOCALEを指定するのが面倒な場合は、config/initializers/locale.rb に
+I18n.default_locale = 'ja'
+という記述を追加しておくと良いでしょう。
+
+また出力先のYAMLのPATHを指定したい場合、YAML_PATHで指定が可能です。
+rake i18n:schema_comments:update_config_locale LOCALE=ja YAML_PATH=/path/to/yaml
+
+=== コメント内コメント ===
+コメント中の ((( から ))) は反映されませんので、モデル名／属性名に含めたくない箇所は ((( と ))) で括ってください。
+((( ))) と同様に[[[ ]]]も使用できます。
+例えば以下のようにdb/schema.rbに出力されている場合、
+ActiveRecord::Schema.define(:version => 0) do
+  create_table "products", :force => true, :comment => '商品' do |t|
+    t.string   "product_type_cd", :comment => '種別コード(((01:書籍, 02:靴, 03:パソコン)))'
+    t.integer  "price", :comment => "価格"
+    t.string   "name", :comment => "商品名"
+    t.datetime "created_at", :comment => "登録日時"
+    t.datetime "updated_at", :comment => "更新日時"
+  end
+end
+
+rake i18n:schema_comments:update_config_locale LOCALE=ja
+とすると、以下のように出力されます。
+ja:
+  activerecord:
+    attributes:
+      product: 
+        product_type_cd: "種別コード"
+        price: "価格"
+        name: "商品名"
+        created_at: "登録日時"
+        updated_at: "更新日時"
+
+
+
+== MySQLのビュー ==
+MySQLのビューを使用した場合、元々MySQLではSHOW TABLES でビューも表示してしまうため、
+ビューはテーブルとしてSchemaDumperに認識され、development環境ではMySQLのビューとして作成されているのに、
+test環境ではテーブルとして作成されてしまい、テストが正しく動かないことがあります。
+これを避けるため、schema_commentsでは、db/schema.rbを出力する際、テーブルに関する記述の後に、CREATE VIEWを行う記述を追加します。
+
+
+== annotate_models ==
+rake db:annotate で以下のようなコメントを、モデル、テスト、フィクスチャといったモデルに関係の強いファイルの
+先頭に追加します。
+  # == Schema Info ==
+  # 
+  # Schema version: 20090721185959
+  #
+  # Table name: books # 書籍
+  #
+  #  id         :integer         not null, primary key
+  #  title      :string(100)     not null               # タイトル
+  #  size       :integer         not null, default(1)   # 判型
+  #  price      :decimal(17, 14) not null, default(0.0) # 価格
+  #  created_at :datetime                               # 登録日時
+  #  updated_at :datetime                               # 更新日時
+  # 
+  # =================
+  # 
+
+また、rake db:updateで、rake db:migrateとrake db:annotateを実行します。
+
+annotate_modelsは、達人プログラマーのDave Thomasさんが公開しているプラグインです。
+http://repo.pragprog.com/svn/Public/plugins/annotate_models/
+
+本プラグインでは、それを更に拡張したDave Boltonさんのプラグイン(
+http://github.com/rotuka/annotate_models )をベースに拡張を加えています。
+
+
+Copyright (c) 2008 Takeshi AKIMA, released under the Ruby License

data/Rakefile

@@ -0,0 +1,46 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "schema_comments"
+    gem.summary  = "schema_comments generates extra methods dynamically"
+    gem.description  = "schema_comments generates extra methods dynamically for attribute which has options"
+    gem.email = "akm2000@gmail.com"
+    gem.homepage = "http://github.com/akm/schema_comments"
+    gem.authors = ["akimatter"]
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "schema_comments #{version}"
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.options = ["--charset", "utf-8", "--line-numbers"]
+end

data/VERSION

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

data/autotest/discover.rb

@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+$KCODE='u'
+
+# Autotestを実行するためのスクリプトです。
+# see http://rails.aizatto.com/2007/11/19/autotest-ing-your-rails-plugin/
+# $:.push(File.join(File.dirname(__FILE__), %w[.. .. rspec]))
+
+Autotest.add_discovery do
+  "rspec"
+end

data/init.rb

@@ -0,0 +1,4 @@
+unless ENV['SCHEMA_COMMENTS_DISABLED']
+  require 'schema_comments'
+  SchemaComments.setup
+end

data/lib/annotate_models.rb

@@ -0,0 +1,224 @@
+
+# fork from
+# http://github.com/rotuka/annotate_models/blob/d2afee82020dbc592b147d92f9beeadbf665a9e0/lib/annotate_models.rb
+
+require "config/environment" if File.exist?("config/environment")
+
+MODEL_DIR         = File.join(RAILS_ROOT, "app/models" )
+UNIT_TEST_DIR     = File.join(RAILS_ROOT, "test/unit"  )
+SPEC_MODEL_DIR    = File.join(RAILS_ROOT, "spec/models")
+FIXTURES_DIR      = File.join(RAILS_ROOT, "test/fixtures")
+SPEC_FIXTURES_DIR = File.join(RAILS_ROOT, "spec/fixtures")
+
+module AnnotateModels
+  
+  PREFIX_AT_BOTTOM = "== Schema Info"
+  SUFFIX_AT_BOTTOM = ""
+  PREFIX_ON_TOP = "== Schema Info =="
+  SUFFIX_ON_TOP = "=================\n# "
+
+  # ENV options
+  {:position => 'top', :model_dir => MODEL_DIR}.each do |name, default_value|
+    mattr_accessor name.to_sym
+    self.send("#{name}=", ENV[name.to_s.upcase] || default_value)
+  end
+
+  def self.models
+    (ENV['MODELS'] || '').split(',')
+  end
+
+  def self.sort_columns
+    ENV['SORT'] =~ /yes|on|true/i
+  end
+
+  def self.output_prefix
+    bottom? ? PREFIX_AT_BOTTOM : PREFIX_ON_TOP
+  end
+
+  def self.output_suffix
+    bottom? ? SUFFIX_AT_BOTTOM : SUFFIX_ON_TOP
+  end
+
+  def self.bottom?
+    self.position =~ /bottom/i
+  end
+
+  def self.separate?
+    ENV['SEPARATE'] =~ /yes|on|true/i
+  end
+
+
+  # Simple quoting for the default column value
+  def self.quote(value)
+    case value
+    when NilClass                 then "NULL"
+    when TrueClass                then "TRUE"
+    when FalseClass               then "FALSE"
+    when Float, Fixnum, Bignum    then value.to_s
+      # BigDecimals need to be output in a non-normalized form and quoted.
+    when BigDecimal               then value.to_s('F')
+    else
+      value.inspect
+    end
+  end
+  
+  # Use the column information in an ActiveRecord class
+  # to create a comment block containing a line for
+  # each column. The line contains the column name,
+  # the type (and length), and any optional attributes
+  def self.get_schema_info(klass)
+    table_info = "# Table name: #{klass.table_name}"
+    table_info << " # #{klass.table_comment}" unless klass.table_comment.blank?
+    table_info << "\n#\n"
+    max_size = klass.column_names.collect{|name| name.size}.max + 1
+    
+    columns = klass.columns
+
+    cols = if self.sort_columns
+             pk    = columns.find_all { |col| col.name == klass.primary_key }.flatten
+             assoc = columns.find_all { |col| col.name.match(/_id$/) }.sort_by(&:name)
+             dates = columns.find_all { |col| col.name.match(/_on$/) }.sort_by(&:name)
+             times = columns.find_all { |col| col.name.match(/_at$/) }.sort_by(&:name)
+             pk + assoc + (columns - pk - assoc - times - dates).compact.sort_by(&:name) + dates + times
+           else
+             columns
+           end
+    
+    col_lines = append_comments(cols.map{|col| [col, annotate_column(col, klass, max_size)]})
+    cols_text = col_lines.join("\n")
+    
+    result = "# #{self.output_prefix}\n# \n# Schema version: #{get_schema_version}\n#\n"
+    result << table_info
+    result << cols_text
+    result << "\n# \n# #{self.output_suffix}" unless self.output_suffix.blank?
+    result << "\n"
+    result
+  end
+  
+  def self.annotate_column(col, klass, max_size)
+    attrs = []
+    attrs << "not null" unless col.null
+    attrs << "default(#{quote(col.default)})" if col.default
+    attrs << "primary key" if col.name == klass.primary_key
+    
+    col_type = col.type.to_s
+    if col_type == "decimal"
+      col_type << "(#{col.precision}, #{col.scale})"
+    else
+      col_type << "(#{col.limit})" if col.limit
+    end
+    sprintf("#  %-#{max_size}s:%-15s %s", col.name, col_type, attrs.join(", ")).rstrip
+  end
+
+  def self.append_comments(col_and_lines)
+    max_length = col_and_lines.map{|(col, line)| line.length}.max
+    col_and_lines.map do |(col, line)|
+      if col.comment.blank?
+        line
+      else
+        "%-#{max_length}s # %s" % [line, col.comment]
+      end
+    end
+  end
+  
+  # Add a schema block to a file. If the file already contains
+  # a schema info block (a comment starting
+  # with "Schema as of ..."), remove it first.
+  # Mod to write to the end of the file
+  def self.annotate_one_file(file_name, info_block)
+    if File.exist?(file_name)
+      content = File.read(file_name)
+      
+      encoding_comment = content.scan(/^\#\s*-\*-(.+?)-\*-/).flatten.first
+      content.sub!(/^\#\s*-\*-(.+?)-\*-/, '')
+
+      # Remove old schema info
+      content.sub!(/(\n)*^# #{PREFIX_ON_TOP}.*?\n(#.*\n)*# #{SUFFIX_ON_TOP}/, '')
+      content.sub!(/(\n)*^# #{PREFIX_AT_BOTTOM}.*?\n(#.*\n)*#.*(\n)*/, '')
+      content.sub!(/^[\n\s]*/, '')
+      
+      # Write it back
+      File.open(file_name, "w") do |f|
+        f.print "# -*- #{encoding_comment.strip} -*-\n\n" unless encoding_comment.blank?
+        if self.bottom?
+          f.print content
+          f.print "\n\n"
+          f.print info_block
+        else
+          f.print info_block
+          f.print "\n" if self.separate?
+          f.print content
+        end
+      end
+    end
+  end
+
+  
+  # Given the name of an ActiveRecord class, create a schema
+  # info block (basically a comment containing information
+  # on the columns and their types) and put it at the front
+  # of the model and fixture source files.  
+  def self.annotate(klass)
+    info = get_schema_info(klass)
+    model_name = klass.name.underscore
+    fixtures_name = "#{klass.table_name}.yml"
+    
+    [
+      File.join(self.model_dir,     "#{model_name}.rb"),      # model
+      File.join(UNIT_TEST_DIR,      "#{model_name}_test.rb"), # test
+      File.join(FIXTURES_DIR,       fixtures_name),           # fixture
+      File.join(SPEC_MODEL_DIR,     "#{model_name}_spec.rb"), # spec
+      File.join(SPEC_FIXTURES_DIR,  fixtures_name),           # spec fixture
+      File.join(RAILS_ROOT,         'test', 'factories.rb'),  # factories file
+      File.join(RAILS_ROOT,         'spec', 'factories.rb'),  # factories file
+    ].each { |file| annotate_one_file(file, info) }
+  end
+  
+  # Return a list of the model files to annotate. If we have
+  # command line arguments, they're assumed to be either
+  # the underscore or CamelCase versions of model names.
+  # Otherwise we take all the model files in the
+  # app/models directory.
+  def self.get_model_names
+    result = nil
+    if self.models.empty?
+      Dir.chdir(self.model_dir) do
+        result = Dir["**/*.rb"].map do |filename| 
+          filename.sub(/\.rb$/, '').camelize
+        end
+      end
+    else
+      result = self.models.dup
+    end
+    result 
+  end
+  
+  # We're passed a name of things that might be
+  # ActiveRecord models. If we can find the class, and
+  # if its a subclass of ActiveRecord::Base,
+  # then pas it to the associated block
+  def self.do_annotations
+    annotated = self.get_model_names.inject([]) do |list, class_name|
+      begin
+        # klass = class_name.split('::').inject(Object){ |klass,part| klass.const_get(part) }
+        klass = class_name.constantize
+        if klass < ActiveRecord::Base && !klass.abstract_class?
+          list << class_name
+          self.annotate(klass)
+        end
+      rescue Exception => e
+        puts "Unable to annotate #{class_name}: #{e.message}"
+      end
+      list
+    end
+    puts "Annotated #{annotated.join(', ')}"
+  end
+  
+  def self.get_schema_version
+    unless @schema_version
+      version = ActiveRecord::Migrator.current_version rescue 0
+      @schema_version = version > 0 ? version : ''
+    end
+    @schema_version
+  end
+end