activerecord-bixformer 0.2.5 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1372a26753e6dc7dc2d178f00a9d3e54aed1973a
-  data.tar.gz: 9089e7d6d4b0344409a6f59a8d5a28e97fa4708d
+  metadata.gz: a0fefe763e939aad7ff7e50f2961962e24164a4d
+  data.tar.gz: 435fbfa1250fa0f8cb11c6c1b97c678e0a808e02
 SHA512:
-  metadata.gz: 0935d90425fe726f56de126f08671a1807959b6a62f1aa0572aef5ff1356e4b33526c1b903c9f6065ac9f89718053111f77f8df26a5eb50be1efc5a4c4bfcd26
-  data.tar.gz: 850006053e33be9a96a827b0c16b88aecafffeea36e126ebe0589612ee93a47cae24c436fbbe3fed7ddf25f0a0ec381c015b6d28b1857091d1416e197c208599
+  metadata.gz: bb7926a45c574069f491893edc80ece85d8a0782976bcb21bbd22d2f0b7b912d87c351bc7335d198c875bfa8576ba2dcb9d4ceab159a6cbda826734e529f0b6d
+  data.tar.gz: f9bfe143d8be2fe6c0101f9703f3fe219ba4cc8cc239a108004a6687f5ba539a8d445644f91b88e6d5c297a8dbc64acd5810534e944116842acf7f53ee17f001

data/README-ja.md

@@ -4,10 +4,9 @@
 
 以下のような特徴があります。  
 
-* `accepts_nested_attributes_for` で定義された関連モデルを同時にインポート/エクスポート可能
-* インポートデータに `primary_key` が含まれる場合、それが正当な値かどうかをチェック
+* `accepts_nested_attributes_for` で定義された関連モデルを同時に扱える
+* インポートデータに `primary_key` が含まれる場合、それが正当な値かどうかをチェックできる
 * 設定用クラスを定義して使い、モデル、属性単位で処理をカスタマイズ可能
-* その設定用クラスを複数定義して、実行時に切り替え可能
 
 現在のところ、インポート/エクスポート可能なデータ形式は
 
@@ -33,18 +32,11 @@ gem 'activerecord-bixformer'
 
 ## 構成要素
 
-本フレームワークの構成要素と役割は以下のようになっています。
+本フレームワークには以下のような概念を持った構成要素があります。
 
 ### Plan
 
 インポート/エクスポートの一連の処理をどのように処理するかを定義する設定ファイルの役割です。  
-処理実行時に、複数登録された本クラスのインスタンス群から採用するものを決定するフローになっていて、
-バージョンや条件による処理内容の切り替えを容易にできます。  
-
-### Runner
-
-インポート/エクスポートの一連の処理を実行するクラスです。  
-本クラスをそのまま利用するだけでも、インポート/エクスポートが可能です。  
 
 ### Model
 
@@ -60,206 +52,272 @@ ActiveRecord のモデルの持つ属性に対応して、その属性のイン
 ActiveRecord::Bixformer::Attribute::Base を継承した独自クラスを定義し、  
 Planを適切に定義することで、それを使用して処理内容を切り替えることができます。  
 
-# 使い方
-
-## 1. Planの実装
-
-ActiveRecord::Bixformer::Plan::Base を継承して、以下のメソッドを適切に設定して下さい。  
-
-### model_name
-
-インポート/エクスポート対象のモデル名を返して下さい。  
-例えばusersテーブルのデータが対象であれば、 `:user` です。  
+## 使い方
 
-### entry
+### 1. Planの実装
 
-インポート/エクスポート対象の属性と、それをどのように処理するかを定義した以下のようなハッシュを返して下さい。  
+ActiveRecord::Bixformer::Plan の機能を持ったクラスを以下のように定義して下さい。  
 
 ```ruby
-{
-  # 対象モデル（上の例なら user ）の処理を担当するModelクラス名
-  # 省略可能で、省略された場合は :base が指定される
-  # 指定可能な値については、「本フレームワークに定義されたModel一覧」を参照
-  # または、独自クラスを定義し、 module_load_namespaces を設定
-  type: :base,
-  
-  # 処理対象の属性名をキー、その処理を担当するAttributeクラス名を値に持つハッシュ
-  attributes: {
-    # 指定可能な値については、「本フレームワークに定義されたAttribute一覧」を参照
-    # または、独自クラスを定義し、 module_load_namespaces を設定
-    name: :base,
-    # クラス名を配列にすると、2番目以降の要素はAttributeクラスに渡される
-    joined_at: [:time, format: :ymdhms]
-  },
-  
-  # 処理対象の関連名をキー、その処理を定義したハッシュを値に持つハッシュ
-  associations: {
-    posts: {
-      # 同じように、 type, attributes, associations が定義可能
+class SamplePlan
+  include ActiveRecord::Bixformer::Plan
+
+  # [bixformer_for] インポート/エクスポート対象のモデル名の指定
+  #
+  #   - 文字列/シンボルで指定
+  #
+  #   例えば、usersテーブルのデータが対象であれば、 user です
+  #
+  bixformer_for :user
+
+
+  # [bixformer_entry] インポート/エクスポート対象の属性/関連モデルと、それらの処理方法の定義
+  #
+  #   - ハッシュを返すProcオブジェクトかメソッド名/シンボルで指定
+  #   - ここで指定された属性/関連モデルのみが処理対象となる
+  #   - キーに指定可能な値は、 type, attributes, associations のいずれか
+  #
+  bixformer_entry -> do
+    {
+      # 対象モデル（上の例なら user ）の処理を担当するModelクラス名
+      # 省略可能で、省略された場合は :base が指定される
+      # 指定可能な値については、「本フレームワークに定義されたModel一覧」を参照
+      # または、独自クラスを定義し、 bixformer_load_namespace を設定して
+      type: :base,
       
-      # 配列にすると、2番目以降の要素はModelクラスに渡される
-      type: [:indexed, size: 3]
+      # 処理対象の属性名をキー、その処理を担当するAttributeクラス名を値に持つハッシュ
+      attributes: {
+      
+        # 指定可能な値については、「本フレームワークに定義されたAttribute一覧」を参照
+        # または、独自クラスを定義し、 module_load_namespaces を設定
+        name: :base,
+        
+        # クラス名を配列にすると、2番目以降の要素は
+        # Attributeインスタンス（この場合は、 ActiveRecord::Bixformer::Attribute::Time ）に渡される
+        # 指定可能な値については、「本フレームワークに定義されたAttribute一覧」を参照
+        joined_at: [:time, format: :ymdhms]
+        
+      },
+      
+      # 処理対象の関連名をキー、その処理を定義したハッシュを値に持つハッシュ
+      associations: {
+
+        # 関連名（例えば、 user.posts で関連レコードが辿れるなら posts ）で指定
+        posts: {
+        
+          # 関連モデルの定義は、同じように、 type, attributes, associations が定義可能
+          
+          # type も、配列にすると、2番目以降の要素は
+          # Modelインスタンス（この場合は、 ActiveRecord::Bixformer::Model::XXX::Indexed ）に渡される
+          # XXX には処理対象のデータ形式（例えば、 Csv ）が入ります
+          # 指定可能な値については、「本フレームワークに定義されたModel一覧」を参照
+          type: [:indexed, size: 3]
+          
+        }
+      }
     }
-  }
-}
-```
+  end
 
-### preferred_skip_attributes
 
-インポート時に、有効な値でない場合に、登録対象としない属性を定義した以下のような配列を返して下さい。  
+  # [bixformer_preferred_skip_attributes] インポート時に、有効な値でない場合に、登録対象としない属性の定義
+  #
+  #   - 配列を返すProcオブジェクトかメソッド名/シンボルで指定
+  #   - 有効な値については、「インポート時に有効な値」を参照
+  #
+  bixformer_preferred_skip_attributes -> do
+    [
+      # ルートの要素は、対象モデル（上の例なら user ）への指定
+      # bixformer_entry で定義されている属性で指定
+      :name,
+      
+      # 関連名でも指定可能
+      # この場合は、その関連モデルの処理対象の属性全てが有効な値でない場合に登録対象から外れる
+      :posts,
+      
+      # 関連モデルの持つ要素を個別指定したい場合は、最後にハッシュで定義
+      posts: [
+      
+        # ここは、postsに対する指定
+        # 上の階層と同じようにネストして定義可能
+        :title
+        
+      ]
+    ]
+  end
 
-```ruby
-[
-  # 対象モデル（上の例なら user ）の属性名。 entry で定義されていること
-  :name,
-  
-  # 関連名も指定可能。この場合は、その関連モデルの処理対象の属性全てが有効な値でない場合
-  :posts,
-  
-  # 関連モデルの持つ要素を個別指定したい場合は、ハッシュで定義
-  posts: [
-    # 同じように定義可能
-    :title
-  ]
-]
-```
 
-#### 有効な値
+  # [bixformer_required_attributes] インポート時に、有効な値でない場合に、インポート自体を行わない属性の定義
+  #
+  #   - 配列を返すProcオブジェクトかメソッド名/シンボルで指定
+  #   - データ構成は、 bixformer_preferred_skip_attributes と同様
+  #
+  bixformer_required_attributes -> do
+    [
+      # joined_atが有効な値でないデータは無視されて、インポートされない
+      :joined_at
+    ]
+  end
 
-有効な値かどうかの判定は、現在、以下の実装となっています。  
 
-```ruby
-def presence_value?(value)
-  case value
-  when ::Hash
-    value.values.any? { |v| presence_value?(v) }
-  when ::Array
-    value.any? { |v| presence_value?(v) }
-  when ::String
-    ! value.blank?
-  when ::TrueClass, ::FalseClass
-    true
-  else
-    value ? true : false
+  # [bixformer_unique_attributes] インポート時に、 primary_key 以外で更新処理を行う属性の定義
+  #
+  #   インポートは、対象の ActiveRecord モデルの primary_key （通常は id ）に対応するインポートデータの有無によって、
+  #   追加か更新かを判定しますが、 primary_key の属性がインポートデータに含まれていない場合でも、
+  #   更新処理を行いたい場合に、対象レコードを特定できる属性を設定するためのものです。
+  #
+  #   - 配列を返すProcオブジェクトかメソッド名/シンボルで指定
+  #   - データ構成は、 bixformer_preferred_skip_attributes と同様
+  #
+  bixformer_unique_attributes -> do
+    [
+      :name, :birthday,
+      
+      posts: [:user_id, :title]
+      
+      # 上記の場合、 user は name, birthday で特定され、 user.posts は user_id, title で特定されます
+      
+      # foreign_key（上記の場合、 user_id ）は、bixformer_entry で指定されていなくても構いません
+      # 自動で、データベースの正しい値で補完されます
+      
+      # それ以外のもので、インポートデータに有効な値がなかった場合は、更新はせず、追加になります
+      
+      # モデルやDBに、実際にユニークインデックスが定義されていなくても指定可能です
+      # ただし、その場合は、条件に合致したレコードが複数あった場合、どれが更新されるか保証できません
+    ]
   end
-end
-```
 
-### required_attributes
 
-インポート時に、有効な値でない場合に、インポート自体を行わない属性を定義した配列を返して下さい。  
-データ構成は、 `preferred_skip_attributes` と同様です。  
+  # [bixformer_required_condition] インポート時に、インポートデータに必ず追加する条件の定義
+  #
+  #   - ハッシュを返すProcオブジェクトかメソッド名/シンボルで指定
+  #   - bixformer_for で指定されたモデル（上記の場合、 user ）のインポートデータに自動で追加されます
+  #
+  bixformer_required_condition -> do
+    {
+      # 対象モデル（上の例なら user ）は、現在処理対象になっている group に属している
+      group_id: current_group.id
+      
+      # インポートデータに primary_key や bixformer_unique_attributes がある場合、
+      # 更新レコードをデータベース検索しますが、その際にも条件に追加されます
+      
+      # 関連モデルの場合は、この設定の有無に関わらず、親レコードの foreign_key が使用されるため、
+      # 関連モデルへの指定はできません
+      
+      # primary_key が指定されているのに、データベース検索に失敗した場合には、
+      # ActiveRecord::RecordNotFound 例外が raise されます
+    }
+  end
 
-### unique_attributes
 
-インポートは、対象の ActiveRecord モデルの `primary_key` に対応するインポートデータの有無によって、  
-追加か更新かを判定しますが、 `primary_key` の属性がインポートデータに含まれていない場合でも、  
-更新処理を行いたい場合に、対象レコードを特定できる属性を定義した配列を返して下さい。  
-データ構成は、 `preferred_skip_attributes` と同様です。  
+  # [bixformer_default_values] インポート時に、有効な値でない場合に、代わりにインポートする値の定義
+  #
+  #   - ハッシュを返すProcオブジェクトかメソッド名/シンボルで指定
+  #   - この設定は、他の設定項目が全て処理された後のインポートデータに対して処理されます
+  #   - インポートデータに対象のキー自体が存在していない（ bixformer_preferred_skip_attributes で指定されてる）属性には何もしません
+  #
+  bixformer_default_values -> do
+    {
+      # 単純な値のみ指定可能
+      name: '名無しの権兵衛',
+
+      # 関連モデルに対する指定
+      posts: {
+        title: '無題'
+      }
+    }
+  end
 
-```ruby
-[
-  :name, :birthday,
-  posts: [:user_id, :title]
-]
-```
 
-* 上記の場合、 user は name, birthday で特定され、 user.posts は user_id, title で特定されます
-* foreign_key（上記の場合、 user_id ）は、インポートデータの有無に関わらず、データベースの正しい値で補完されます
-* それ以外のもので、インポートデータに有効な値がなかった場合は、更新はせず、追加になります
-* モデルやDBに、実際にユニークインデックスが定義されていなくても指定可能です
-* ただし、その場合は、条件に合致したレコードが複数あった場合、どれが更新されるか保証できません
+  # [bixformer_translation_config] インポート/エクスポートで行われる translation の設定の定義
+  #
+  #   - CSVでは
+  #     - カラム名に使用されます
+  #
+  #   - ハッシュを返すProcオブジェクトかメソッド名/シンボルで指定
+  #   - キーに指定可能な値は、 scope, extend_scopes のいずれか
+  #
+  bixformer_translation_config -> do
+    {
+      # 基点のスコープ
+      scope: :bixformer,
+      
+      # translation を検索するスコープを、基点のスコープ配下に増やしたい場合に指定
+      extend_scopes: [:version1, :version2]
+      
+      # 上記の場合、ユーザが投稿したタイトルは
+      #
+      # bixformer.version2.user/posts.title
+      # bixformer.version1.user/posts.title
+      # bixformer.user/posts.title
+      #
+      # の順で検索され、最初に見つかった translation を実行します
+      
+      # translation が見つからなかったり、失敗した場合は、エラーになります
+    }
+  end
 
-### required_condition
 
-インポート時に、 `model_name` のインポートデータに追加する条件を定義した以下のようなハッシュを返して下さい。  
+  # [bixformer_load_namespace] 独自クラスを探索する namespace の定義
+  #
+  #   - 文字列で指定
+  #   - bixformer_entry で指定された独自クラスは、 "ここで指定した値::クラス種別::クラス名" で検索されます
+  #   - クラス種別は、 Model, Attribute のいずれかです
+  #   - クラス名は、bixformer_entry で指定した値を camelize した値です
+  #
+  bixformer_load_namespace "MyModule::Bixformer"
 
-```ruby
-{
-  # 対象モデル（上の例なら user ）は、現在処理対象になっている group に属している
-  group_id: current_group.id
-}
+end
 ```
 
-* `primary_key` や `unique_attributes` が指定されている場合のデータベース検索の条件に追加されます
-* 関連モデルの場合は、親レコードの foreign_key が代わりに使用されます
-* `primary_key` が指定されているのに、データベース検索に失敗した場合には、 `ActiveRecord::RecordNotFound` 例外が raise されます
-
-### default_values
+### 2. インポート/エクスポートの実装
 
-インポート時に、有効な値でない場合に、代わりにインポートする値を定義した以下のようなハッシュを返して下さい。  
-
-```ruby
-{
-  name: '名無しの権兵衛',
-  posts: {
-    title: '無題'
-  }
-}
-```
+インポート/エクスポートの処理を定義した Plan と、 ActiveRecord::Bixformer::From/To 配下に  
+定義された各データ形式のインポート/エクスポート用クラスを使います。  
 
-### translation_config
+以下に、各データ形式の簡単なサンプルを示します。  
 
-インポート/エクスポートで行われる translation の設定を定義した以下のようなハッシュを返して下さい。  
+#### CSVの場合
 
 ```ruby
-{
-  # 基点のスコープ
-  scope: :bixformer,
-  
-  # translation を試みるスコープを、基点のスコープ配下に増やしたい場合に指定
-  extend_scopes: [:version1, :version2]
-}
-```
-
-上記の場合、ユーザが投稿したタイトルは
-
-`bixformer.version2.user/posts.title`  
-`bixformer.version1.user/posts.title`  
-`bixformer.user/posts.title`  
+plan = SamplePlan.new
 
-の順で検索されます。translation が見つからなかった場合は、エラーになります。  
+# エクスポート
+bixformer = ActiveRecord::Bixformer::To::Csv.new(plan)
 
-* CSVでは
-    * カラム名に使用されます
+csv_data = CSV.generate do |csv|
+  csv << bixformer.csv_title_row
 
-### module_load_namespaces
-
-`entry` で指定されたクラス名のクラスを探索する namespace を定義した配列を返して下さい。  
-ActiveRecord::Bixformer::Plan::Base には、以下のように定義されています。  
-
-```ruby
-def module_load_namespaces(module_type)
-  [
-    "::ActiveRecord::Bixformer::#{module_type.to_s.camelize}::#{format.to_s.camelize}",
-    "::ActiveRecord::Bixformer::#{module_type.to_s.camelize}",
-  ]
+  User.all.each do |user|
+    csv << bixformer.csv_body_row(user)
+  end
 end
-```
 
-* 要素の先頭から、 `要素::クラス名.to_s.classify.constantize` を試し、成功したものを採用します
-* `module_type` には、 `:model` / `:attribute` / `:generator` のいずれかが渡されます
-* `format` は、対象のデータ形式（ `:csv` ）になります
+# インポート
+bixformer = ActiveRecord::Bixformer::From::Csv.new(plan)
 
-## 2. Runner を実装
+CSV.parse(csv_data).each do |csv_row|
 
-CSVを扱う簡単なサンプルコードは以下のような感じになります。  
+  if csv_row.header_row?
 
-```ruby
-runner = ActiveRecord::Bixformer::Runner::Csv.new
+    raise ArgumentError unless bixformer.verify_csv_titles(csv_row)
 
-runner.add_plan(Your::Plan.new)
+  else
 
-csv_data = runner.export(User.all, force_quotes: true)
+    attributes = bixformer.assignable_attributes(csv_row)
+    user       = User.new
+    
+    user.assign_attributes(attributes)
+    user.save!
 
-runner.import(csv_data)
+  end
+end
 ```
 
 ## その他
 
 ### 本フレームワークに定義されたModel一覧
 
-For CSV
+#### For CSV
 
 * base
     * has_one な関連モデル用。 has_many な関連モデルには使えない
@@ -271,8 +329,8 @@ For CSV
 
 ### 本フレームワークに定義されたAttribute一覧
 
-* base
-    * エクスポートでは `to_s` し、インポートでは `presence` する
+* string
+    * エクスポートでは `to_s` し、インポートでは `strip` して `presence` する
 * boolean
     * `true` / `false` オプションに、それぞれに対応する文字列を指定。デフォルトは、 `"true"` / `"false"`
     * インポート時、合致しない値は `nil` になる
@@ -294,3 +352,24 @@ For CSV
     * インポートでは、インポートデータ、エクスポートでは、 ActiveRecord の属性値が引数となる
     * インポート/エクスポートする値を返すこと
 
+### インポート時に有効な値
+
+有効な値かどうかの判定は、現在、以下の実装となっています。  
+
+```ruby
+def presence_value?(value)
+  case value
+  when ::Hash
+    value.values.any? { |v| presence_value?(v) }
+  when ::Array
+    value.any? { |v| presence_value?(v) }
+  when ::String
+    ! value.blank?
+  when ::TrueClass, ::FalseClass
+    true
+  else
+    value ? true : false
+  end
+end
+```
+

data/lib/activerecord-bixformer/model/base.rb

@@ -38,7 +38,7 @@ module ActiveRecord
           end
 
           @preferred_skip_attributes = @plan.pickup_value_for(self, :preferred_skip_attributes, [])
-          @default_values      = @plan.pickup_value_for(self, :default_values, {})
+          @default_values            = @plan.pickup_value_for(self, :default_values, {})
 
           # At present, translation function is only i18n
           @translator = ::ActiveRecord::Bixformer::Translator::I18n.new
@@ -95,16 +95,26 @@ module ActiveRecord
           @attributes.each do |attr|
             attribute_value = block.call(attr)
 
-            attribute_value = @default_values[attr.name] unless presence_value?(attribute_value)
-
-            # 取り込み時は、オプショナルな属性では、空と思われる値は取り込まない
+            # 取り込み時は、 preferred_skip な属性では、有効でない値は取り込まない
             next if ! presence_value?(attribute_value) &&
                     @preferred_skip_attributes.include?(attr.name.to_s)
 
             values[attr.name] = attribute_value
           end
 
-          normalizer.normalize(values)
+          # データの検証と正規化
+          normalizer.normalize(values).tap do |normalized_values|
+            # デフォルト値の補完
+            @default_values.each do |attribute_name, default_value|
+              # 結果にキーが存在していない（ preferred_skip_attributes で指定されてる）場合は補完しない
+              next unless normalized_values.key?(attribute_name)
+
+              # 有効な値が既に格納されている場合も補完しない
+              next if presence_value?(normalized_values[attribute_name])
+
+              normalized_values[attribute_name] = default_value
+            end
+          end
         end
 
         def make_each_association_import_value(values, &block)
@@ -118,7 +128,7 @@ module ActiveRecord
               association_value = association_value.reject { |v| ! presence_value?(v) }
             end
 
-            # 取り込み時は、オプショナルな関連では、空と思われる値は取り込まない
+            # 取り込み時は、 preferred_skip な関連では、有効でない値は取り込まない
             next if ! presence_value?(association_value) &&
                     @preferred_skip_attributes.include?(association.name.to_s)
 

data/lib/activerecord-bixformer/version.rb

@@ -1,5 +1,5 @@
 module ActiveRecord
   module Bixformer
-    VERSION = "0.2.5"
+    VERSION = "0.2.6"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-bixformer
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.6
 platform: ruby
 authors:
 - Hiroaki Otsu