From 8aeafd151782f12fc672b63d81fca324b54d245f Mon Sep 17 00:00:00 2001
From: Matt Millsaps-Brewer <matt@madebylotus.com>
Date: Wed, 17 Jan 2018 09:20:46 -0500
Subject: [PATCH] Allow accessing a hash of metadata on ColumnDefinition

---
 README.md                                   | 29 +++++++++++++++++++++
 lib/csv_importer/column_definition.rb       |  4 +++
 spec/csv_importer/column_definition_spec.rb | 18 +++++++++++++
 3 files changed, 51 insertions(+)

diff --git a/README.md b/README.md
index bb3e8b2..573a011 100644
--- a/README.md
+++ b/README.md
@@ -336,6 +336,35 @@ UserImport.new(file: csv_file) do
 end
 ```
 
+### Store metadata on the column description
+
+You may find yourself wanting to store arbitrary metadata about a column.
+
+For example, you may want to pull the schema for the importer dynamically and list out the
+supported fields along with a description, to help guide users through an import
+process on valid content.
+
+This can be accomplished using the metadata Hash.
+
+```ruby
+class ImportUserCSV
+  model User
+
+  column :active, to: ->(value) { %w(y yes true active).include?(value.downcase) }, meta: { description: %q{Indicate if active using "Y", "yes", "true", "active" or just "no"} }
+
+  # optionally use I18n
+  column :active, to: ->(value) {}, meta: { description: I18n.t('my.custom.scope.active') }
+end
+```
+
+To access this information and potentially display to users before uploading a
+file to import:
+
+```ruby
+ImportUserCSV.config.column_definitions.each do |column|
+  puts "#{ column.name.to_s.titleize } - #{ column.metadata[:description] }"
+end
+```
 
 ### Validate the header
 
diff --git a/lib/csv_importer/column_definition.rb b/lib/csv_importer/column_definition.rb
index efcfc1d..231dcf4 100644
--- a/lib/csv_importer/column_definition.rb
+++ b/lib/csv_importer/column_definition.rb
@@ -18,6 +18,9 @@ module CSVImporter
   #   # email will be downcased
   #   column :email, to: ->(email) { email.downcase }
   #
+  #   # column defined with metadata
+  #   column :active, meta: { description: %q{Can provide "Y", "Yes", "true" or simply "no"} }
+  #
   #   # transform `confirmed` to `confirmed_at`
   #   column :confirmed, to: ->(confirmed, model) do
   #     model.confirmed_at = confirmed == "true" ? Time.new(2012) : nil
@@ -30,6 +33,7 @@ class ColumnDefinition
     attribute :to # Symbol or Proc
     attribute :as # Symbol, String, Regexp, Array
     attribute :required, Boolean
+    attribute :meta, Hash, default: {}
 
     # The model attribute that this column targets
     def attribute
diff --git a/spec/csv_importer/column_definition_spec.rb b/spec/csv_importer/column_definition_spec.rb
index 720a290..f608128 100644
--- a/spec/csv_importer/column_definition_spec.rb
+++ b/spec/csv_importer/column_definition_spec.rb
@@ -2,6 +2,24 @@
 
 module CSVImporter
   describe ColumnDefinition do
+    describe '.meta' do
+      it 'defaults to an empty Hash' do
+        expect(subject.meta).to eq(Hash.new)
+      end
+
+      it 'does not transform values' do
+        subject.meta[:key] = 19.0
+
+        expect(subject.meta[:key]).to eq(19.0)
+      end
+
+      it 'does not transform keys' do
+        subject.meta['key'] = 19.0
+
+        expect(subject.meta[:key]).to eq(nil)
+      end
+    end
+
     describe "#match?" do
 
       matcher :match do |name|