rare_map 2.1.1 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 35d4ce6e64d68bef4eb2893fa6468d8b854b2c32
-  data.tar.gz: c2a4f131953a569b8a5fd4484ff069fefed37644
+  metadata.gz: d2a5bcbd97c37310f2e809a4328490c44076bd06
+  data.tar.gz: f7fb2de31bbf07022673ad8a3e4655351f902e8a
 SHA512:
-  metadata.gz: 0c5132d0e2da33a6bb4048165baaf4e8974bc3488bf0915434ffbfe78570235d316634518af8a0c5037d3180ab0c9c01d0f674f70f30761f3d714af6205d5a1a
-  data.tar.gz: 78f48e16fdf5c9c7880cfc447d324d3bf1ef4dca2f217846e835cd1a31a07ccd327e685e9047c5c89cc94618fcb185968c9104e59ffba5e9d11d5dbacea69181
+  metadata.gz: 839fb36c3ea95902213b7b2507ba2231b1238cee119fc9703a44af158b948d9add23725f2208f992623e7f472e7c1eefb94c23cce6e108435733f2da77044d1c
+  data.tar.gz: 8c1f2ccfe9102b00e9b43f03004a16a5f8e2e141e79cd107f7b0d5e3bd16c7fda53122dc2e4abd92d37d920e5c0976817bfa3c8c8b888b24297188cc4ec44186

data/Rakefile

@@ -4,24 +4,9 @@ begin
 rescue LoadError
   puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
 end
-begin
-  require 'rdoc/task'
-rescue LoadError
-  require 'rdoc/rdoc'
-  require 'rake/rdoctask'
-  RDoc::Task = Rake::RDocTask
-end
-
-RDoc::Task.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'RareMap'
-  rdoc.options << '--line-numbers'
-  rdoc.rdoc_files.include('README.rdoc')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
-
-
 
+require 'yard'
+YARD::Rake::YardocTask.new
 
 Bundler::GemHelper.install_tasks
 
@@ -34,5 +19,4 @@ Rake::TestTask.new(:test) do |t|
   t.verbose = false
 end
 
-
-task :default => :test
+task :default => :test

data/lib/rare_map.rb

@@ -5,20 +5,29 @@ require 'rare_map/schema_parser'
 require 'rare_map/model_builder'
 require 'rare_map/model_generator'
 
+# RareMap
+# @author Wei-Ming Wu
 module RareMap
+  # A class method to make RareMap::Mapper#mapping easy to be called.
   def self.mapping
     Mapper.new.mapping
   end
   
+  # RareMap::Mapper converts relational databases into ActiveRecord files.
+  # @author Wei-Ming Wu
   class Mapper
     include RailsLocator, ConfigLoader, SchemaReader, SchemaParser, ModelBuilder, ModelGenerator
     
+    # Creates a Mapper.
+    #
+    # @return [Mapper] a Mapper object
     def initialize
       @rails_root = locate_rails_root
     end
     
+    # Converts relational databases into ActiveRecord files by given RareMap config yaml file.
     def mapping
-      @db_profiles = load_config @rails_root ? @rails_root + 'config/' : './'
+      @db_profiles = load_config @rails_root ? File.join(@rails_root, 'config') : '.'
       @db_profiles.each do |profile|
         profile.schema = read_schema profile
         profile.tables = parse_schema profile.schema
@@ -37,11 +46,12 @@ module RareMap
       end
       @models
       
-      rescue ConfigNotFoundError => e
-        puts "Please put your database config in `#{'config/' if @rails_root}rare_map.yml`."
+    rescue ConfigNotFoundError => e
+      puts "Please put your database config in `#{'config/' if @rails_root}rare_map.yml`."
     end
     
     private
+    
     def generate_demo
       f = File.new('demo.rb', 'w')
       f.write "require 'active_record'\n"

data/lib/rare_map/column.rb

@@ -0,0 +1,42 @@
+module RareMap
+  # RareMap::Column defines a column of a database table.
+  # @author Wei-Ming Wu
+  # @!attribute [r] name
+  #   @return [String] the name of this Column
+  # @!attribute [r] type
+  #   @return [String] the type of this Column
+  # @!attribute unique
+  #   @return [true, false] the uniqueness of this Column
+  # @!attribute ref_table
+  #   @return [String] the reference table of this Column
+  class Column
+    attr_reader :name, :type
+    attr_accessor :unique
+    attr_accessor :ref_table
+    
+    # Creates a Column.
+    #
+    # @param name [String] the name of column
+    # @param type [String] the type of column
+    # @return [Column] a Column object
+    def initialize(name, type, opts = {})
+      @name = name
+      @type = type
+      @unique = opts[:unique] == true
+    end
+    
+    # Checks if this Column is unique.
+    #
+    # @return [true, false] true if it's unique, false otherwise 
+    def unique?
+      @unique
+    end
+    
+    # Checks if this Column is a foreign key.
+    #
+    # @return [true, false] true if it's a foreign key, false otherwise 
+    def foreign_key?
+      @ref_table ? true : false
+    end
+  end
+end

data/lib/rare_map/config_loader.rb

@@ -1,17 +1,29 @@
 require 'yaml'
 require 'rare_map/errors'
+require 'rare_map/database_profile'
+require 'rare_map/options'
 
 module RareMap
+  # RareMap::ConfigLoader translates a rare_map.yml into DatabaseProfile.
+  # @author Wei-Ming Wu
   module ConfigLoader
+    # The key of rare map options inside a config YAML.
     OPTS_KEY = 'rare_map_opts'
-    
-    def load_config(path, file_name = 'rare_map.yml')
-      raise ConfigNotFoundError unless File.exist? "#{path}#{file_name}"
-      config = YAML.load_file "#{path}#{file_name}"
+    include Errors
+    
+    # Translates a rare_map.yaml into an Array of DatabaseProfile.
+    #
+    # @param [String] path the folder which contains the RareMap config
+    # @param [String] file_name the name of the RareMap config
+    # @return [Array] an Array of DatabaseProfile
+    def load_config(path = '.', file_name = 'rare_map.yml')
+      raise ConfigNotFoundError unless File.exist? File.join(path, file_name)
+      config = YAML.load_file File.join(path, file_name)
       organize_config_properties config['rare_map'] || config || {}
     end
     
     private
+    
     def organize_config_properties(raw_config)
       db_profiles = []
       global_opts = Options.new(raw_config.delete OPTS_KEY)
@@ -26,11 +38,11 @@ module RareMap
           end
         when 'Array'
           v = v.reduce(:merge)
-          group_opts = Options.new(v.delete(OPTS_KEY) || global_opts.opts, k)
+          group_opts = Options.new((v.delete(OPTS_KEY) || global_opts.opts).merge(group: k))
           
           v.each do |db, config|
             if config[OPTS_KEY]
-              db_profiles << DatabaseProfile.new(db, remove_opts(config), Options.new(config[OPTS_KEY], k))
+              db_profiles << DatabaseProfile.new(db, remove_opts(config), Options.new(config[OPTS_KEY].merge(group: k)))
             else
               db_profiles << DatabaseProfile.new(db, config, group_opts)
             end
@@ -45,67 +57,4 @@ module RareMap
       db.select { |k, _| k != OPTS_KEY }
     end
   end
-  
-  class DatabaseProfile
-    attr_reader :name, :connection, :options
-    attr_accessor :schema, :tables
-    
-    def initialize(name, connection, options)
-      @name, @connection = name, connection
-      @options = options || Options.new
-      @tables = []
-    end
-  end
-  
-  class Options
-    attr_reader :opts
-    
-    def initialize(raw_opts = nil, group = nil)
-      @opts = { 'group'       => 'default',
-                'primary_key' => {},
-                'foreign_key' => { 'suffix' => nil, 'alias' => {} } }
-                
-      if raw_opts and raw_opts.kind_of? Hash
-        if raw_opts['group']
-          @opts['group'] = raw_opts['group']
-        end
-        if raw_opts['primary_key'].kind_of? Hash
-          @opts['primary_key'] = raw_opts['primary_key'].select { |k, v| k.kind_of? String and v.kind_of? String }
-        end
-        if raw_opts['foreign_key'] and raw_opts['foreign_key']['suffix'].kind_of? String
-           @opts['foreign_key']['suffix'] = raw_opts['foreign_key']['suffix']
-        end
-        if raw_opts['foreign_key'] and raw_opts['foreign_key']['alias'].kind_of? Hash
-           @opts['foreign_key']['alias'] = raw_opts['foreign_key']['alias'].select { |k, v| k.kind_of? String and v.kind_of? String }
-        end
-      end
-      @opts['group'] = group if group.kind_of? String
-    end
-    
-    def group?
-      @opts['group'] != 'default'
-    end
-    
-    def group
-      @opts['group'] || 'default'
-    end
-    
-    def find_primary_key_by_table(table_name)
-      @opts['primary_key'].each { |k, v| return v if k == table_name }
-      nil
-    end
-    
-    def find_table_by_foreign_key(column_name)
-      @opts['foreign_key']['alias'].each { |k, v| return v if k == column_name }
-      nil
-    end
-    
-    def fk_suffix
-      @opts['foreign_key']['suffix']
-    end
-    
-    def to_s
-      @opts.to_s
-    end
-  end
 end

data/lib/rare_map/database_profile.rb

@@ -0,0 +1,32 @@
+require 'rare_map/options'
+
+module RareMap
+  # RareMap::DatabaseProfile defines all metadata of a database.
+  # @author Wei-Ming Wu
+  # @!attribute [r] name
+  #   @return [String] the name of this DatabaseProfile
+  # @!attribute [r] connection
+  #   @return [Hash] the connection config of this DatabaseProfile
+  # @!attribute [r] options
+  #   @return [Options] the Options of this DatabaseProfile
+  # @!attribute schema
+  #   @return [String] the schema dump of this DatabaseProfile
+  # @!attribute tables
+  #   @return [Array] an Array of Table of this DatabaseProfile
+  class DatabaseProfile
+    attr_reader :name, :connection, :options
+    attr_accessor :schema, :tables
+    
+    # Creates a DatabaseProfile.
+    #
+    # @param [String] name the name of this DatabaseProfile
+    # @param [Hash] connection the connection config of this DatabaseProfile
+    # @param [Options] options the Options of this DatabaseProfile
+    # @return [DatabaseProfile] a DatabaseProfile object
+    def initialize(name, connection, options = nil)
+      @name, @connection = name, connection
+      @options = options || Options.new
+      @tables = []
+    end
+  end
+end

data/lib/rare_map/errors.rb

@@ -1,4 +1,10 @@
 module RareMap
-  class ConfigNotFoundError < Exception
+  # RareMap::Errors defines all kinds of errors of RareMap.
+  # @author Wei-Ming Wu
+  module Errors
+    # ConfigNotFoundError is an Exception.
+    class ConfigNotFoundError < Exception ; end
+    # RelationNotDefinedError is an Exception.
+    class RelationNotDefinedError < Exception ; end
   end
 end

data/lib/rare_map/model.rb

@@ -0,0 +1,48 @@
+require 'active_support/inflector'
+require 'active_support/core_ext/hash'
+
+module RareMap
+  # RareMap::Model defines the details of an ActiveRecord model.
+  # @author Wei-Ming Wu
+  # @!attribute [r] db_name
+  #   @return [String] the name of the database
+  # @!attribute [r] connection
+  #   @return [Hash] the connection config of this Model
+  # @!attribute [r] table
+  #   @return [Table] the Table of this Model
+  # @!attribute [r] group
+  #   @return [String] the group of this Model
+  # @!attribute relations
+  #   @return [Array] an Array of Relation of this Model
+  class Model
+    include Errors
+    attr_reader :db_name, :connection, :table, :group
+    attr_accessor :relations
+    
+    # Creates a Model.
+    #
+    # @param db_name [String] the name of database
+    # @param connection [Hash] the connection config of ActiveRecord
+    # @param table [Table] the database table
+    # @param group [String] the group name of this Model
+    # @return [Model] a Model object
+    def initialize(db_name, connection, table, group = 'default')
+      @db_name, @connection, @table, @group = db_name, connection, table, group
+      @relations = []
+    end
+    
+    # Checks if this Model belongs to a group.
+    #
+    # @return [true, false] true if this Model contains a group, false otherwise
+    def group?
+      group != 'default'
+    end
+    
+    # Returns the class name of this Model.
+    #
+    # @return [String] the class name of this Model
+    def classify
+      "#{table.name}".pluralize.classify
+    end
+  end
+end

data/lib/rare_map/model_builder.rb

@@ -1,7 +1,14 @@
 require 'active_support/inflector'
+require 'rare_map/model'
+require 'rare_map/relation'
 
 module RareMap
+  # RareMap::ModelBuilder converts an Array of DatabaseProfile into an Array of Model.
+  # @author Wei-Ming Wu
   module ModelBuilder
+    # Creaetes an Array of Model by given DatabaseProfile(s).
+    #
+    # @return [Array] an Array of Model
     def build_models(db_profiles)
       models = []
       
@@ -12,9 +19,9 @@ module RareMap
           set_foreign_keys_by_options(table, opts)
           set_fk_suffix_by_options(table, opts)
           if opts.group?
-            models << Model.new(db_prof.connection, table, opts.group, db_prof.name)
+            models << Model.new(db_prof.name, db_prof.connection, table, opts.group)
           else
-            models << Model.new(db_prof.connection, table, 'default', db_prof.name)
+            models << Model.new(db_prof.name, db_prof.connection, table)
           end
         end
       end
@@ -25,6 +32,7 @@ module RareMap
     end
     
     private
+    
     def build_relations(models)
       models.each do |model|
         if model.group?
@@ -87,7 +95,7 @@ module RareMap
     def set_foreign_keys_by_options(table, options)
       table.columns.each do |col|
         ref = options.find_table_by_foreign_key col.name
-        col.references = ref if ref
+        col.ref_table = ref if ref
       end
     end
     
@@ -96,29 +104,4 @@ module RareMap
       table.primary_key = pk if pk
     end
   end
-  
-  class Model
-    attr_reader :connection, :table, :group, :relations, :db_name
-    
-    def initialize(connection, table, group = 'default', db_name)
-      @connection, @table, @group, @db_name = connection, table, group, db_name
-      @relations = []
-    end
-    
-    def group?
-      group != 'default'
-    end
-    
-    def classify
-      "#{table.name}".pluralize.classify
-    end
-  end
-  
-  class Relation
-    attr_reader :type, :foreign_key, :table, :through
-    
-    def initialize(type, foreign_key, table, through = nil)
-      @type, @foreign_key, @table, @through = type, foreign_key, table, through
-    end
-  end
-end
+end

data/lib/rare_map/model_generator.rb

@@ -1,11 +1,14 @@
 require 'active_support/inflector'
 
 module RareMap
+  # RareMap::ModelGenerator converts an Array of Model into ActiveRecord files.
+  # @author Wei-Ming Wu
   module ModelGenerator
-    def generate_models(models, root = './')
-      root ||= './'
-      path = root + 'app/models/'
-      Dir.mkdir root + 'app' unless Dir.exist? root + 'app'
+    # Creaetes ActiveRecord files by given Model(s) under app/models directory.
+    def generate_models(models, root = '.')
+      root ||= '.'
+      path = File.join(root, 'app', 'models')
+      Dir.mkdir File.join(root, 'app') unless Dir.exist? File.join(root, 'app')
       Dir.mkdir path unless Dir.exist? path
       
       group_db2conn = generate_connection_models(models, path)
@@ -53,8 +56,8 @@ module RareMap
         output << "  end\n"
         output << 'end'
         
-        Dir.mkdir path + "#{model.group.underscore}" unless Dir.exist? path + "#{model.group}"
-        f = File.new(path + "#{model.group.underscore}/#{model.classify.underscore}.rb", 'w')
+        Dir.mkdir File.join(path, "#{model.group.underscore}") unless Dir.exist? File.join(path, "#{model.group}")
+        f = File.new File.join(path, "#{model.group.underscore}", "#{model.classify.underscore}.rb"), 'w'
         f.write output
         f.close
       end
@@ -63,6 +66,7 @@ module RareMap
     end
     
     private
+    
     def classify_by_table(table, model, models)
       if model.group?
         model = models.find { |m| m.table.name == table &&
@@ -93,8 +97,8 @@ module RareMap
         'end'
         
         
-        Dir.mkdir path + "#{group.underscore}" unless Dir.exist? path + "#{group}"
-        f = File.new(path + "#{group.underscore}/#{model.underscore}.rb", 'w')
+        Dir.mkdir File.join(path, "#{group.underscore}") unless Dir.exist? File.join(path, "#{group}")
+        f = File.new File.join(path, "#{group.underscore}", "#{model.underscore}.rb"), 'w'
         f.write output
         f.close