Permalink
Browse files

Changed rdoc to markdown.

  • Loading branch information...
1 parent 33929c2 commit db932fc21c36e8e6b14e3a19e8c7e7e449f28115 quaternion committed Feb 15, 2012
Showing with 151 additions and 96 deletions.
  1. +151 −0 README.md
  2. +0 −96 README.rdoc
View
151 README.md
@@ -0,0 +1,151 @@
+## Transfer Gem
+Transfer data from source database to ActiveRecord, SequelModel or Mongoid models.
+
+### Installation
+ gem install transfer
+or if used bundler, insert to Gemfile
+ gem 'transfer'
+
+
+### Compatibility
+Source database: all, supported by [Sequel](http://sequel.rubyforge.org/documentation.html).
+
+Destination: *ActiveRecord*, *SequelModel*, *Mongoid*.
+
+
+## Configure
+Set connection options of source database and global parameters.
+
+ Transfer.configure do |c|
+ c.host = "localhost"
+ c.adapter = "postgres"
+ c.database = "source_database"
+ c.user = "username"
+ c.password = "password"
+ end
+
+Available options:
+
+* `validate` on/off model validations. Values: `true` or `false`, default is `false`.
+* `failure_strategy` sets strategy if save of model is not successfully. Values: `:ignore` or `:rollback`, defult is `:ignore`.
+* `before` [global callback](#global_callbacks).
+* `success` [global callback](#global_callbacks).
+* `failure` [global callback](#global_callbacks).
+* `after` [global callback](#global_callbacks).
+* another options interpreted as [Sequel database connection options](http://sequel.rubyforge.org/rdoc/files/doc/opening_databases_rdoc.html).
+
+
+## Usage
+Direct transfer from source table `:users` to `User` model. All columns, existing in source table and destination model, will transferred.
+
+ transfer :users => User
+
+If in source `:users` table not exists column `country`, simple add it.
+
+ transfer :users => User do
+ country "England"
+ end
+
+Transfer `:name` column from source table into `first_name` method of User model.
+
+ transfer :users => User do
+ first_name :name
+ end
+
+To produce, dynamic value (e.g. `dist_name`), you can pass a block and access the row of source table.
+
+ transfer :users => User do
+ dist_name {|row| "Mr. #{row[:first_name]}"}
+ end
+
+
+### Global callbacks <a name="global_callbacks"/>
+This callbacks called for each `transfer`.
+
+ Transfer.configure do |c|
+ c.before do |klass, dataset|
+ #...
+ end
+ c.success do |model, row|
+ #...
+ end
+ c.failure do |model, row, exception|
+ #...
+ end
+ c.after do |klass, dataset|
+ #...
+ end
+ end
+
+Available global callbacks:
+
+* `before` called before an transfer started. Parameters: `klass`, `dataset`.
+* `success` called if save model is successfully. Parameters: `model`, `row`.
+* `failure` called if save model is not successfully. Parameters: `row`, `exception`.
+* `after` called after an transfer finished. Parameters: `klass`, `dataset`.
+
+Description of parameters:
+
+* `dataset` source table dataset, instance of [Sequel::Dataset](http://sequel.rubyforge.org/rdoc/classes/Sequel/Dataset.html).
+* `klass` is destination class.
+* `model` builded model, instance of `klass`.
+* `row` of source table. Type: `Hash`.
+* `exception` if save of model is not successfull.
+
+
+### Local transfer callbacks
+This called for
+This callbacks called in model context, therefore `self` keyword points to model.
+
+ transfer :users => User do
+ before_save do |row|
+ self.messages << Message.build(:title => "Transfer", :description => "Welcome to new site, #{row[:fname]}!")
+ end
+ end
+
+Available callbacks:
+
+* `before_save` called before save model. Paramaters: `row`.
+* `after_save` called after save model. Parameters: `row`.
+
+where `row` is row of source table, type: `Hash`.
+
+
+### Filter columns
+`only` filter passes source columns, specified in parameters.
+
+ transfer :users => User do
+ only :name
+ end
+
+`except` filter passes all source columns, except for those that are specified in the parameters:
+
+ transfer :users => User do
+ except :name
+ end
+
+
+### Replace global options
+Global options can be replaced global options, if it passed to `transfer`.
+
+ transfer :users => User, :validate => false, :failure_strategy => :rollback
+
+Available options for replace:
+
+* `validate`
+* `failure_strategy`
+
+
+### Integrate with [progressbar](https://github.com/peleteiro/progressbar)
+If you also want see progress of transfer in console, use e.g. progressbar gem.
+
+ require 'progressbar'
+
+ Transfer.configure do |c|
+ c.before {|klass, dataset| @pbar = ProgressBar.new(klass, dataset.count) }
+ c.success { @pbar.inc }
+ c.failure { @pbar.halt }
+ c.after { @pbar.finish }
+ end
+
+ transfer :users => User
View
@@ -1,96 +0,0 @@
-== Transfer Gem
-Transfer data from source database to ActiveRecord, SequelModel or Mongoid models.
-
-=== Installation
- gem install transfer
-or if used bundler, insert to Gemfile
- gem 'transfer'
-
-=== Compatibility
-ActiveRecord, SequelModel, Mongoid.
-
-== Configure
- Transfer.configure do |c|
- c.host = "localhost"
- c.adapter = "postgres"
- c.database = "source_database"
- c.user = "username"
- c.password = "password"
- end
-Available options:
-* +validate+ on/off model validations. Values: +true+ or +false+, default is +false+.
-* +failure_strategy+ set strategy if save of model is not successfully. Values: +:ignore+ or +:rollback+, defult is +:ignore+.
-* +failure+ global failure callback.
-* another options interpreted as Sequel database connection options, see http://sequel.rubyforge.org/rdoc/files/doc/opening_databases_rdoc.html
-
-== Usage
-Direct transfer from source table +:users+ to +User+ model. All columns, existing in source table and destination model, will transferred.
-
- transfer :users => User
-
-If in source +:users+ table not exists column +country+, simple add it.
-
- transfer :users => User do
- country "England"
- end
-
-Transfer +:name+ column from source table into +first_name+ method of User model.
-
- transfer :users => User do
- first_name :name
- end
-
-To produce, dynamic value (e.g. +dist_name+), you can pass a block and access the row of source table.
-
- transfer :users => User do
- dist_name {|row| "Mr. #{row[:first_name]}"}
- end
-
-=== Filters
-+only+ filter passes source columns, specified in parameters.
-
- transfer :users => User do
- only :name
- end
-
-+except+ filter passes all source columns, except for those that are specified in the parameters:
-
- transfer :users => User do
- except :name
- end
-
-=== Callbacks
-All callbacks called in model context, therefore +self+ keyword points to model.
-
- transfer :users => User do
- before_save do |row|
- self.country = "Hello"
- end
- end
-
-Available callbacks:
-* +before_save+ called before save model. Paramaters: +row+.
-* +after_save+ called after save model. Parameters: +row+.
-* +failure+ called if save model is not successfully or save process raise exception. Parameters: +row+, +exception+.
-
-=== Global callbacks
-This callbacks analogy callbacks from +transfer+, they are invoked if +transfer+ callback not defined.
-
- Transfer.configure do |config|
- config.failure do |row, exception|
- #...
- end
- end
-
-Available global callbacks:
-* +failure+ called if save model is not successfully. Parameters: +row+, +exception+.
-
-=== Replace global options
-Global options can be replaced model options, if it passed to +transfer+.
-
- transfer :users => User, :validate => false, :failure_strategy => :rollback
-
-Available options for replace:
-* +validate+
-* +failure_strategy+
-* +failure+

0 comments on commit db932fc

Please sign in to comment.