mongify 0.0.9 → 0.1.0

data/lib/mongify/database/sql_connection.rb

@@ -3,19 +3,43 @@ module Mongify
     #
     # Sql connection configuration
     #
+    # 
+    # Basic format should look something like this:
+    # 
+    #   sql_connection do
+    #     adaptor   "mysql"
+    #     host      "localhost"
+    #     username  "root"
+    #     password  "passw0rd"
+    #     database  "my_database"
+    #   end
+    # Possible attributes:
+    # 
+    #   adapter
+    #   host
+    #   database
+    #   username
+    #   password
+    #   port
+    #   encoding
+    #   socket
+    # 
     class SqlConnection < Mongify::Database::BaseConnection
-
-      REQUIRED_FIELDS = %w{host adapter database encoding}
+      
+      # List of required fields to bulid a valid sql connection
+      REQUIRED_FIELDS = %w{host adapter database}
       
       def initialize(options=nil)
         @prefixed_db = false
         super(options)
       end
 
+      # Setups up an active_record connection
       def setup_connection_adapter
         ActiveRecord::Base.establish_connection(self.to_hash)
       end
-
+      
+      # Returns true or false depending if the record is valid
       def valid?
         return false unless @adapter
         if sqlite_adapter?
@@ -25,27 +49,32 @@ module Mongify
         end
         false
       end
-
+      
+      # Returns true or false depending if the connction actually talks to the database server.
       def has_connection?
         setup_connection_adapter
         connection.send(:connect) if ActiveRecord::Base.connection.respond_to?(:connect)
         true
       end
       
+      # Returns the active_record connection
       def connection
         return nil unless has_connection?
         ActiveRecord::Base.connection
       end
       
+      # Returns all the tables in the database server
       def tables
         return nil unless has_connection?
         self.connection.tables
       end
 
+      # Returns all the columns for a given table
       def columns_for(table_name)
         self.connection.columns(table_name)
       end
       
+      # Returns an array with hash values of all the records in a given table
       def select_rows(table_name)
         self.connection.select_all("SELECT * FROM #{table_name}")
       end
@@ -53,6 +82,7 @@ module Mongify
       #######
       private
       #######
+      # Used to check if this is a sqlite connection 
       def sqlite_adapter?
         @adapter && (@adapter.downcase == 'sqlite' || @adapter.downcase == 'sqlite3')
       end

data/lib/mongify/database/table.rb

@@ -1,8 +1,42 @@
 module Mongify
   module Database
     #
-    #  A representation of a sql table and how it should map to a no_sql system 
+    #  A representation of a sql table and how it should map to a no_sql collection 
     #
+    # ==== Structure
+    # 
+    # Structure for defining a table is as follows:
+    #   table "table_name", {options} do
+    #     # columns go here...
+    #   end
+    # 
+    # ==== Options
+    # 
+    # Table Options are as follow:
+    #   table "table_name"                                        # Does a straight copy of the table
+    #   table "table_name", :embed_in => :users                   # Embeds table_name into users, assuming a user_id is present in table_name.
+    #                                                             # This will also assume you want the table embedded as an array.
+    #   table "table_name", :embed_in => :users, :on => 'owner_id'# Embeds table_name into users, linking it via a owner_id
+    #                                                             # This will also assume you want the table embedded as an array.
+    #   table "table_name", :embed_in => :users, :as => :object   # Embeds table_name into users as a one to one relationship
+    #                                                             # This also assumes you have a user_id present in table_name
+    #   table "table_name", :embed_in => :posts, :on => 'post_id', :as => 'array'
+    #                                                             # You can also do both :on and :as
+    # 
+    # <b>NOTE: If you rename the owner_id column, make sure you update the :on to the new column name</b>
+    # 
+    #   table "table_name", :rename_to => 'my_table'              # This will allow you to rename the table as it's getting process
+    #                                                             # Just remember that columns that use :reference need to
+    #                                                             # reference the new name.
+    # 
+    #   table "table_name", :ignore => true                       # This will ignore the whole table (like it doesn't exist)
+    #                                                             # This option is good for tables like: schema_migrations
+    # 
+    #   table "table_name" do                                     # A table can take a before_save block that will be called just
+    #     before_save do |row|                                    # before the row is saved to the no sql database.
+    #       row.admin = row.delete('permission').to_i > 50        # This gives you the ability to do very powerful things like:
+    #     end                                                     # Moving records around, renaming records, changing values in row based on
+    #   end                                                       # some values! Checkout {Mongify::Database::DataRow} to learn more
     class Table
       
       attr_accessor :name, :sql_name
@@ -21,80 +55,108 @@ module Mongify
         self
       end
       
+      # Returns the no_sql collection name
       def name
         @name ||= @options['rename_to']
         @name ||= self.sql_name
       end
       
+      # Returns true if table is ignored
       def ignored?
         @options['ignore']
       end
       
-      #Add a Database Column
+      # Add a Database Column to the table
+      # This expects to get a {Mongify::Database::Column} or it will raise {Mongify::DatabaseColumnExpected} otherwise
       def add_column(column)
         raise Mongify::DatabaseColumnExpected, "Expected a Mongify::Database::Column" unless column.is_a?(Mongify::Database::Column)
         add_and_index_column(column)
       end
       
-      
+      # Lets you build a column in the table
       def column(name, type=nil, options={})
         options, type = type, nil if type.is_a?(Hash)
         type = type.to_sym if type
         add_and_index_column(Mongify::Database::Column.new(name, type, options))
       end
       
+      # Returns the column if found by the sql_name
       def find_column(name)
         return nil unless (index = @column_lookup[name.to_s.downcase])
         @columns[index]
       end
       
-      
+      # Returns a array of Columns which reference other columns
       def reference_columns
         @columns.reject{ |c| !c.referenced? } 
       end
       
+      # Returns a translated row
+      # Takes in a hash of values
       def translate(row)
         new_row = {}
         row.each do |key, value|
           c = find_column(key)
           new_row.merge!(c.present? ? c.translate(value) : {"#{key}" => value})
         end
-        new_row
+        run_before_save(new_row)
       end
       
+      
+      # Returns the name of the embed_in collection
       def embed_in
         @options['embed_in'].to_s unless @options['embed_in'].nil?
       end
       
+      # Returns the type of embed it will be [object or array]
       def embed_as
         return nil unless embed?
         return 'object' if @options['as'].to_s.downcase == 'object'
         'array'
       end
-      
+
+      # Returns true if table is being embed as an object
       def embed_as_object?
         embed_as == 'object'
       end
       
+      # Returns true if this is an embedded table
       def embed?
         embed_in.present?
       end
       
+      # Returns the name of the target column to embed on
       def embed_on
         return nil unless embed?
         (@options['on'] || "#{@options['embed_in'].to_s.singularize}_id").to_s
       end
+      
+      # Used to save a block to be ran after the row has been processed but before it's saved to the no sql database
+      def before_save(&block)
+        @before_save = block
+      end
             
       #######
       private
       #######
       
+      # Runs the before save
+      # Returns: a new modified row
+      def run_before_save(row)
+        return row unless @before_save
+        datarow = Mongify::Database::DataRow.new(row)
+        @before_save.call(datarow)
+        datarow.to_hash
+      end
+      
+      # Indexes the column on the sql_name and adds column to the array
       def add_and_index_column(column)
         @column_lookup[column.sql_name] = @columns.size
         @columns << column
         column
       end
-
+      
+      # Imports colunms that are sent in via the options['columns']
       def import_columns
         return unless import_columns = @options.delete('columns')
         import_columns.each { |c| add_column(c) }

data/lib/mongify/exceptions.rb

@@ -1,13 +1,20 @@
 module Mongify
   # File Not Found Exception
   class FileNotFound < RuntimeError; end
+  # Raise when configuration file is missing
   class ConfigurationFileNotFound < FileNotFound; end
+  # Raised when Translation file is missing
   class TranslationFileNotFound < FileNotFound; end
   
+  # Basic Configuration Error Exception
   class ConfigurationError < RuntimeError; end
+  # Raise when a sqlConnection is required but not given
   class SqlConnectionRequired < ConfigurationError; end
+  # Raised when a noSqlConnection is required but not given
   class NoSqlConnectionRequired < ConfigurationError; end
+  # Raised when a Mongify::Database::Column is expected but not given
   class DatabaseColumnExpected < ConfigurationError; end
   
+  # Raised when application has no root folder set
   class RootMissing < RuntimeError; end
 end

data/lib/mongify/translation.rb

@@ -4,16 +4,52 @@ module Mongify
   #
   # Actually runs the translation from sql to no sql
   #
+  # Basic translation file should look like this:
+  #   table "users" do
+  #     column "id", :key
+  #     column "first_name", :string
+  #     column "last_name", :string
+  #     column "created_at", :datetime
+  #     column "updated_at", :datetime
+  #   end
+  #   
+  #   table "posts" do
+  #     column "id", :key
+  #     column "title", :string
+  #     column "owner_id", :integer, :references => :users
+  #     column "body", :text
+  #     column "published_at", :datetime
+  #     column "created_at", :datetime
+  #     column "updated_at", :datetime
+  #   end
+  #   
+  #   table "comments", :embed_in => :posts, :on => :post_id do
+  #     column "id", :key
+  #     column "body", :text
+  #     column "post_id", :integer, :referneces => :posts
+  #     column "user_id", :integer, :references => :users
+  #     column "created_at", :datetime
+  #     column "updated_at", :datetime
+  #   end
+  #   
+  #   table "preferences", :embed_in => :users, :as => :object do
+  #     column "id", :key
+  #     column "user_id", :integer, :references => "users"
+  #     column "notify_by_email", :boolean
+  #   end
   class Translation
     include Printer
     include Process
     class << self
+      # Returns an instance of a translation object
+      # Takes a location of a translation file
       def parse(file_name)
         translation = self.new
         translation.instance_eval(File.read(file_name))
         translation
       end
       
+      #Returns an instence of a translation object with a given sql connection layout loaded
       def load(connection)
         raise Mongify::SqlConnectionRequired, "Can only read from Mongify::Database::SqlConnection" unless connection.is_a?(Mongify::Database::SqlConnection)
         return unless connection.valid? && connection.has_connection?
@@ -21,7 +57,7 @@ module Mongify
         connection.tables.each do |t|
           columns = []
           connection.columns_for(t).each do |ar_col|
-            columns << Mongify::Database::Column.new(ar_col.name, ar_col.type)
+            columns << Mongify::Database::Column.new(ar_col.name, ar_col.type, :auto_detect => true)
           end
           translation.table(t, :columns => columns)
         end
@@ -33,27 +69,34 @@ module Mongify
       @all_tables = []
     end
     
+    # Creates a {Mongify::Database::Table} from the given input and adds it to the list of tables
     def table(table_name, options={}, &block)
       table = Mongify::Database::Table.new(table_name, options, &block)
-      @all_tables << table
+      add_table(table)
     end
     
+    # Adds a {Mongify::Database::Table} to the list of tables
     def add_table(table)
       @all_tables << table
+      table
     end
     
+    # Returns an array of all tables in the translation
     def all_tables
       @all_tables
     end
     
+    # Returns an array of all tables that have not been ingored
     def tables
       all_tables.reject{ |t| t.ignored? }
     end
     
+    # Returns an array of all tables that have not been ignored and are just straight copy tables
     def copy_tables
       tables.reject{|t| t.embed?}
     end
     
+    # Returns an array of all tables that have not been ignored and are to be embedded
     def embed_tables
       tables.reject{|t| !t.embed?}
     end

data/lib/mongify/translation/printer.rb

@@ -1,9 +1,10 @@
 module Mongify
-  #
-  # Actually runs the translation from sql to no sql
-  #
   class Translation
+    #
+    # Actually runs the translation from sql to no sql
+    #
     module Printer
+      # Outputs a translation into a string format
       def print
         ''.tap do |output|
           all_tables.each do |t|

data/lib/mongify/translation/process.rb

@@ -1,11 +1,13 @@
 module Mongify
-  #
-  # This will take the Translation and do the processing on it
-  #
   class Translation
+    #
+    # This module does the processing on the translation object
+    #
     module Process
       attr_accessor :sql_connection, :no_sql_connection
-
+      
+      # Does the actual act of processing the translation.
+      # Takes in boht a sql connection and a no sql connection
       def process(sql_connection, no_sql_connection)
         raise Mongify::SqlConnectionRequired, "Can only read from Mongify::Database::SqlConnection" unless sql_connection.is_a?(Mongify::Database::SqlConnection)
         raise Mongify::NoSqlConnectionRequired, "Can only write to Mongify::Database::NoSqlConnection" unless no_sql_connection.is_a?(Mongify::Database::NoSqlConnection)
@@ -26,6 +28,7 @@ module Mongify
       private
       #######
       
+      # Does the straight copy (of tables)
       def copy_data
         self.copy_tables.each do |t|
           sql_connection.select_rows(t.sql_name).each do |row|
@@ -34,6 +37,7 @@ module Mongify
         end
       end
       
+      # Does a copy of the embedded tables
       def copy_embedded_tables
         self.embed_tables.each do |t|
           sql_connection.select_rows(t.sql_name).each do |row|
@@ -49,6 +53,7 @@ module Mongify
         end
       end
       
+      # Updates the reference ids in the no sql database
       def update_reference_ids
         self.tables.each do |t|
           no_sql_connection.select_rows(t.name).each do |row|
@@ -59,6 +64,7 @@ module Mongify
         end
       end
       
+      # Fetches the new _id from a collection
       def fetch_reference_ids(table, row)
         attributes = {}
         table.reference_columns.each do |c|
@@ -68,6 +74,7 @@ module Mongify
         attributes
       end
       
+      # Removes 'pre_mongiifed_id's from all collection
       def remove_pre_mongified_ids
         self.copy_tables.each { |t| no_sql_connection.remove_pre_mongified_ids(t.name) }
       end

data/lib/mongify/ui.rb

@@ -4,39 +4,48 @@ module Mongify
   #
   class UI
     class << self
+      # Outputs to stream using puts method
       def puts(msg)
         out_stream.puts(msg) if out_stream
       end
-    
+      
+      # Outputs to stream using print method
       def print(msg)
         out_stream.print(msg) if out_stream
       end
     
+      # Gets input from user
       def gets
         in_stream ? in_stream.gets : ''
       end
     
+      # Outputs a question and gets input
       def request(msg)
         print(msg)
         gets.chomp
       end
     
+      # Asks a yes or no question and waits for reply
       def ask(msg)
         request("#{msg} [yn] ") == 'y'
       end
       
+      # Outputs a Warning (using puts command)
       def warn(msg)
         puts "WARNING: #{msg}"
       end
       
+      # Outputs a message and aborts execution of app
       def abort(message)
         UI.puts "PROGRAM HALT: #{message}"
         Kernel.abort message
       end
       
+      # Incoming stream
       def in_stream
         Configuration.in_stream
       end
+      # Output stream
       def out_stream
         Configuration.out_stream
       end