acts_as_table 0.0.1

data/lib/acts_as_table.rb

@@ -0,0 +1,288 @@
+require 'singleton'
+
+require 'active_record'
+require 'active_record/version'
+require 'active_support/core_ext/module'
+
+begin
+  require 'rails/engine'
+  require 'acts_as_table/engine'
+rescue ::LoadError
+  # void
+end
+
+require 'acts_as_table/version'
+
+# ActsAsTable is a Ruby on Rails plugin for working with tabular data.
+module ActsAsTable
+  extend ::ActiveSupport::Autoload
+
+  # ActsAsTable serialization.
+  autoload :Headers, 'acts_as_table/headers'
+  autoload :Reader,  'acts_as_table/reader'
+  autoload :Writer,  'acts_as_table/writer'
+
+  # ActsAsTable utilities.
+  autoload :Adapter, 'acts_as_table/adapter'
+  autoload :Mapper,  'acts_as_table/mapper'
+  autoload :Path,    'acts_as_table/path'
+
+  # Finds an ActsAsTable serialization format module based on a symbolic name.
+  #
+  # @param [Symbol] format
+  # @return [Module]
+  # @raise [ArgumentError] If the given symbolic name is invalid.
+  #
+  # @example Find the ActsAsTable serialization format module for CSV format.
+  #   ActsAsTable.for(:csv) #=> ActsAsTable::CSV
+  #
+  # @example Implement an ActsAsTable serialization format module.
+  #   require 'active_support/core_ext/module'
+  #
+  #   module ActsAsTable
+  #     # ActsAsTable serialization format module for "custom format."
+  #     module CustomFormat
+  #       extend ::ActiveSupport::Autoload
+  #
+  #       autoload :Reader, 'acts_as_table/custom_format/reader'
+  #       autoload :Writer, 'acts_as_table/custom_format/writer'
+  #
+  #       # Returns the symbolic name for this ActsAsTable serialization format module.
+  #       #
+  #       # @return [Symbol]
+  #       def format
+  #         :custom_format
+  #       end
+  #
+  #       # Returns a new ActsAsTable reader object for this serialization format module.
+  #       #
+  #       # @param [Array<Object>] args
+  #       # @yieldparam [ActsAsTable::CustomFormat::Reader] reader
+  #       # @yieldreturn [void]
+  #       # @return [ActsAsTable::CustomFormat::Reader]
+  #       def reader(*args, &block)
+  #         Reader.new(*args, &block)
+  #       end
+  #
+  #       # Returns a new ActsAsTable writer object for this serialization format module.
+  #       #
+  #       # @param [Array<Object>] args
+  #       # @yieldparam [ActsAsTable::CustomFormat::Writer] writer
+  #       # @yieldreturn [void]
+  #       # @return [ActsAsTable::CustomFormat::Writer]
+  #       def writer(*args, &block)
+  #         Writer.new(*args, &block)
+  #       end
+  #     end
+  #   end
+  #
+  def self.for(format)
+    # @return [Hash<Symbol, Module>]
+    module_by_format = self.config.formats.collect { |const_name|
+      self.const_get(const_name, false)
+    }.inject({}) { |acc, m|
+      acc[m.format] ||= m
+      acc
+    }
+
+    unless module_by_format.key?(format)
+      raise ::ArgumentError.new("invalid format - expected: #{module_by_format.keys.inspect}, found: #{format.inspect}")
+    end
+
+    module_by_format[format]
+  end
+
+  # Uses the given ActsAsTable adapter object within the scope of the execution of the given block.
+  #
+  # If block given, yield with no arguments and return the result. Otherwise, return `nil`.
+  #
+  # @param [ActsAsTable::Adapter] new_adapter
+  # @yieldreturn [Object]
+  # @return [Object, nil]
+  def self.use(new_adapter, &block)
+    # @return [Object, nil]
+    result = nil
+
+    if block_given?
+      # @return [ActsAsTable::Adapter]
+      orig_adapter = self.config.adapter
+
+      begin
+        self.config.adapter = new_adapter
+
+        result = block.call
+      ensure
+        self.config.adapter = orig_adapter
+      end
+    end
+
+    result
+  end
+
+  autoload :VERSION
+
+  # ActsAsTable configuration object.
+  class Configuration
+    include ::Singleton
+
+    # @!attribute [rw] adapter
+    #   Returns the ActsAsTable adapter object (default: `ActsAsTable::Adapter.new`).
+    #
+    #   @return [ActsAsTable::Adapter]
+    attr_accessor :adapter
+
+    # @!attribute [rw] formats
+    #   Returns the non-inherited constant names for available ActsAsTable serialization format modules (default: `[]`).
+    #
+    #   @return [Array<Symbol>]
+    attr_accessor :formats
+
+    # @!attribute [rw] belongs_tos_table
+    #   Returns the table name for the {ActsAsTable::BelongsTo} class (default: `:belongs_tos`).
+    #
+    #   @return [Symbol]
+    # @!attribute [rw] column_models_table
+    #   Returns the table name for the {ActsAsTable::ColumnModel} class (default: `:column_models`).
+    #
+    #   @return [Symbol]
+    # @!attribute [rw] foreign_key_maps_table
+    #   Returns the table name for the {ActsAsTable::ForeignKeyMap} class (default: `:foreign_key_maps`).
+    #
+    #   @return [Symbol]
+    # @!attribute [rw] foreign_keys_table
+    #   Returns the table name for the {ActsAsTable::ForeignKey} class (default: `:foreign_key`).
+    #
+    #   @return [Symbol]
+    # @!attribute [rw] has_manies_table
+    #   Returns the table name for the {ActsAsTable::HasMany} class (default: `:has_manies`).
+    #
+    #   @return [Symbol]
+    # @!attribute [rw] has_many_targets_table
+    #   Returns the table name for the {ActsAsTable::HasManyTarget} class (default: `:has_many_targets`).
+    #
+    #   @return [Symbol]
+    # @!attribute [rw] lenses_table
+    #   Returns the table name for the {ActsAsTable::Lense} class (default: `:lenses`).
+    #
+    #   @return [Symbol]
+    # @!attribute [rw] primary_keys_table
+    #   Returns the table name for the {ActsAsTable::PrimaryKey} class (default: `:primary_keys`).
+    #
+    #   @return [Symbol]
+    # @!attribute [rw] record_errors_table
+    #   Returns the table name for the {ActsAsTable::RecordError} class (default: `:record_errors`).
+    #
+    #   @return [Symbol]
+    # @!attribute [rw] record_models_table
+    #   Returns the table name for the {ActsAsTable::RecordModel} class (default: `:record_models`).
+    #
+    #   @return [Symbol]
+    # @!attribute [rw] records_table
+    #   Returns the table name for the {ActsAsTable::Record} class (default: `:records`).
+    #
+    #   @return [Symbol]
+    # @!attribute [rw] row_models_table
+    #   Returns the table name for the {ActsAsTable::RowModel} class (default: `:row_model`).
+    #
+    #   @return [Symbol]
+    # @!attribute [rw] tables_table
+    #   Returns the table name for the {ActsAsTable::Table} class (default: `:table`).
+    #
+    #   @return [Symbol]
+    # @!attribute [rw] values_table
+    #   Returns the table name for the {ActsAsTable::Value} class (default: `:value`).
+    #
+    #   @return [Symbol]
+    %w(BelongsTo ColumnModel ForeignKey ForeignKeyMap HasMany HasManyTarget Lense PrimaryKey Record RecordError RecordModel RowModel Table Value).each do |class_name|
+      attr_accessor :"#{class_name.pluralize.underscore}_table"
+    end
+
+    # Returns a new ActsAsTable configuration object.
+    #
+    # @return [ActsAsTable::Configuration]
+    def initialize
+      @adapter = ActsAsTable::Adapter.new
+
+      @formats = []
+
+      @belongs_tos_table = :belongs_tos
+      @column_models_table = :column_models
+      @foreign_key_maps_table = :foreign_key_maps
+      @foreign_keys_table = :foreign_keys
+      @has_manies_table = :has_manies
+      @has_many_targets_table = :has_many_targets
+      @lenses_table = :lenses
+      @primary_keys_table = :primary_keys
+      @record_errors_table = :record_errors
+      @record_models_table = :record_models
+      @records_table = :records
+      @row_models_table = :row_models
+      @tables_table = :tables
+      @values_table = :values
+    end
+  end
+
+  # Returns the ActsAsTable configuration object.
+  #
+  # @return [ActsAsTable::Configuration]
+  def self.config
+    Configuration.instance
+  end
+
+  # Configure ActsAsTable.
+  #
+  # @yieldreturn [void]
+  # @return [void]
+  #
+  # @example Set the ActsAsTable adapter object.
+  #   class CustomActsAsTableAdapter < ActsAsTable::Adapter
+  #     # ...
+  #   end
+  #
+  #   ActsAsTable.configure do
+  #     config.adapter = CustomActsAsTableAdapter.new
+  #   end
+  #
+  # @example Register an ActsAsTable serialization format module.
+  #   require 'acts_as_table_custom_format' # underscore
+  #
+  #   ActsAsTable.configure do
+  #     config.formats << :CustomFormat # constantize
+  #   end
+  #
+  # @example Prefix the table names for the ActsAsTable model classes.
+  #   ActsAsTable.configure do
+  #     config.methods.select { |method_name| method_name.to_s.ends_with?("_table") }.each do |method_name|
+  #       config.send(:"#{method_name}=", :"prefix_#{config.send(method_name)}")
+  #     end
+  #   end
+  #
+  def self.configure(&block)
+    if block_given?
+      self.instance_eval(&block)
+    end
+
+    return
+  end
+
+  # Delegates to ActsAsTable configuration object.
+  #
+  # @param [String] method_name
+  # @param [Array<Object>] args
+  # @yield [*args, &block]
+  # @yieldreturn [Object]
+  # @return [Object]
+  # @raise [NoMethodError]
+  def self.method_missing(method_name, *args, &block)
+    self.config.respond_to?(method_name, false) ? self.config.send(method_name, *args, &block) : super(method_name, *args, &block)
+  end
+
+  # Delegates to ActsAsTable configuration object.
+  #
+  # @param [String] method_name
+  # @param [Boolean] include_all
+  # @return [Boolean]
+  def self.respond_to?(method_name, include_all = false)
+    self.config.respond_to?(method_name, false) || super(method_name, include_all)
+  end
+end

data/lib/acts_as_table/adapter.rb

@@ -0,0 +1,81 @@
+module ActsAsTable
+  # ActsAsTable adapter object.
+  #
+  # @note The "adapter pattern" is a software design pattern that is used to make existing classes work with others without modifying their source code.
+  #
+  # @see ActsAsTable.use
+  # @see ActsAsTable::Configuration#adapter
+  # @see ActsAsTable::Configuration#adapter=
+  class Adapter
+    # Finds the first record with the given attributes, or creates a record with the attributes if one is not found.
+    #
+    # @param [ActsAsTable::RecordModel] record_model
+    # @param [#find_or_initialize_by] callee
+    # @param [Symbol] method_name
+    # @param [Array<Object>] args
+    # @yieldparam [ActiveRecord::Base] base
+    # @yieldreturn [void]
+    # @return [ActiveRecord::Base]
+    def find_or_initialize_by_for(record_model, callee, method_name = :find_or_initialize_by, *args, &block)
+      callee.send(method_name, *args, &block)
+    end
+
+    # Initializes new record from relation while maintaining the current scope.
+    #
+    # @param [ActsAsTable::RecordModel] record_model
+    # @param [#new] callee
+    # @param [Symbol] method_name
+    # @param [Array<Object>] args
+    # @yieldparam [ActiveRecord::Base] base
+    # @yieldreturn [void]
+    # @return [ActiveRecord::Base]
+    def new_for(record_model, callee, method_name = :new, *args, &block)
+      callee.send(method_name, *args, &block)
+    end
+
+    # Get the value for the given record using the given options.
+    #
+    # @param [#get_value] value_provider
+    # @param [ActiveRecord::Base, nil] base
+    # @param [Hash<Symbol, Object>] options
+    # @option options [Boolean] :default
+    # @return [ActsAsTable::ValueProvider::WrappedValue]
+    def get_value_for(value_provider, base = nil, **options)
+      value_provider.get_value(base, **options)
+    end
+
+    # Set the new value for the given record using the given options.
+    #
+    # @param [#set_value] value_provider
+    # @param [ActiveRecord::Base, nil] base
+    # @param [Object, nil] new_value
+    # @param [Hash<Symbol, Object>] options
+    # @option options [Boolean] :default
+    # @return [ActsAsTable::ValueProvider::WrappedValue]
+    def set_value_for(value_provider, base = nil, new_value = nil, **options)
+      value_provider.set_value(base, new_value, **options)
+    end
+
+    # Returns a new ActsAsTable wrapped value object.
+    #
+    # @param [ActsAsTable::ValueProvider::InstanceMethods] value_provider
+    # @param [ActiveRecord::Base, nil] base
+    # @param [Object, nil] source_value
+    # @param [Object, nil] target_value
+    # @param [Hash<Symbol, Object>] options
+    # @option options [Boolean] :changed
+    # @option options [Boolean] :default
+    # @return [ActsAsTable::ValueProvider::WrappedValue]
+    def wrap_value_for(value_provider, base = nil, source_value = nil, target_value = nil, **options)
+      ActsAsTable::ValueProvider::WrappedValue.new(value_provider, base, source_value, target_value, **options)
+    end
+
+    def classify_for(value_provider, table_name)
+      table_name.classify
+    end
+
+    def tableize_for(value_provider, class_name)
+      class_name.tableize
+    end
+  end
+end

data/lib/acts_as_table/engine.rb

@@ -0,0 +1,14 @@
+module ActsAsTable
+  class Engine < ::Rails::Engine
+    isolate_namespace ActsAsTable
+
+    initializer 'acts_as_table.active_record' do |app|
+      ::ActiveSupport.on_load(:active_record) do
+        ::ActiveRecord::Base.class_eval do
+          include ActsAsTable::ValueProvider
+          include ActsAsTable::ValueProviderAssociationMethods
+        end
+      end
+    end
+  end
+end

data/lib/acts_as_table/headers.rb

@@ -0,0 +1,196 @@
+module ActsAsTable
+  # ActsAsTable headers.
+  module Headers
+    # ActsAsTable headers array object.
+    #
+    # @!attribute [r] column_models
+    #   Returns the ActsAsTable column models for this ActsAsTable headers array object.
+    #
+    #   @return [Enumerable<ActsAsTable::ColumnModel>]
+    class Array < ::Array
+      attr_reader :column_models
+
+      # Returns a new ActsAsTable headers array object.
+      #
+      # @param [Enumerable<ActsAsTable::ColumnModel>] column_models
+      # @return [ActsAsTable::Headers::Array]
+      def initialize(column_models)
+        @column_models = column_models.to_a
+
+        # @return [Array<Array<String>>]
+        header_names_without_padding = @column_models.collect { |column_model|
+          column_model.name.split(column_model.separator)
+        }
+
+        # @return [Integer]
+        max_header_names_without_padding_size = header_names_without_padding.collect(&:size).max || 0
+
+        # @return [Array<Array<String, nil>>]
+        @header_names_with_padding = header_names_without_padding.collect { |split_name|
+          split_name + ::Array.new(max_header_names_without_padding_size - split_name.size) { nil }
+        }.collect { |header_names|
+          header_names.freeze
+        }.freeze
+
+        # @return [Array<Array<String, nil>>]
+        headers = @header_names_with_padding.transpose.collect(&:freeze)
+
+        super(headers)
+
+        self.freeze
+      end
+
+      # Returns a 3-level array indexed by the header index, the header name index and the pair index.
+      #
+      # The elements in the 3rd level are pairs, where the first element is the header name and the second element is the ActsAsTable column models count for the header name.
+      #
+      # @note This method is intended to be used to render tables with merged cells in the header rows (where the ActsAsTable column models count is the column span).
+      #
+      # @return [Array<Array<Array<Object>>>]
+      #
+      # @example Render HTML "thead" element with merged "th" elements.
+      #   <thead>
+      #     <% @row_model.to_headers.with_column_models_count.each do |header| %>
+      #       <tr>
+      #         <% header.each do |pair| %>
+      #           <%= content_tag(:th, pair[0], colspan: pair[1], scope: 'col') %>
+      #         <% end %>
+      #       </tr>
+      #     <% end %>
+      #   </thead>
+      #
+      def with_column_models_count
+        # Drop the last row (the corresponding instances of the {ActsAsTable::ColumnModel} class).
+        @with_column_models_count ||= Hash.for(@column_models, @header_names_with_padding).to_array[0..-2]
+      end
+    end
+
+    # ActsAsTable headers hash object.
+    #
+    # @!attribute [r] column_models_count
+    #   Returns the ActsAsTable column models count for this ActsAsTable headers hash object.
+    #
+    #   @return [Integer]
+    class Hash < ::Hash
+      # Returns a new ActsAsTable headers hash object for the given ActsAsTable column models and header names.
+      #
+      # @param [Enumerable<ActsAsTable::ColumnModel>] column_models
+      # @param [Array<Array<String, nil>>] header_names_with_padding
+      # @return [ActsAsTable::Headers::Hash]
+      def self.for(column_models, header_names_with_padding)
+        # @!method _block(orig_hash, counter)
+        #   Returns the new ActsAsTable headers hash object with accumulated ActsAsTable column models count.
+        #
+        #   @param [ActsAsTable::Headers::Hash] orig_hash
+        #   @param [Integer] counter
+        #   @return [ActsAsTable::Headers::Hash]
+        _block = ::Proc.new { |orig_hash, counter|
+          # @return [Hash<String, Object>]
+          new_hash = orig_hash.each_pair.inject({}) { |acc, pair|
+            key, value = *pair
+
+            case value
+            when ::Array
+              counter += value.size
+
+              # @return [Array<ActsAsTable::ColumnModel>]
+              acc[key] = value
+            when ::Hash
+              # @return [ActsAsTable::Headers::Hash]
+              new_hash_for_value = _block.call(value, 0)
+
+              counter += new_hash_for_value.column_models_count
+
+              # @return [ActsAsTable::Headers::Hash]
+              acc[key] = new_hash_for_value
+            end
+
+            acc
+          }
+
+          self.new(counter).merge(new_hash).freeze
+        }
+
+        # @return [Hash<String, Object>]
+        orig_hash = header_names_with_padding.each_with_index.inject({}) { |acc, pair|
+          header_names, index = *pair
+
+          # @return [Integer]
+          max_header_names_index = header_names.size - 1
+
+          # @return [Hash<String, Object>]
+          column_models_for_index = header_names.each_with_index.inject(acc) { |header_acc, pair|
+            header_name, header_name_index, = *pair
+
+            if header_name_index == max_header_names_index
+              header_acc[header_name] ||= []
+              header_acc[header_name] << column_models[index]
+            else
+              header_acc[header_name] ||= {}
+            end
+
+            header_acc[header_name]
+          }
+
+          column_models_for_index.freeze
+
+          acc
+        }
+
+        _block.call(orig_hash, 0)
+      end
+
+      attr_reader :column_models_count
+
+      # Returns a new ActsAsTable headers hash object.
+      #
+      # @param [Integer] column_models_count
+      # @param [Array<Object>] args
+      # @yieldparam [ActsAsTable::Headers::Hash] hash
+      # @yieldparam [String] key
+      # @yieldreturn [ActsAsTable::Headers::Hash, ActsAsTable::ColumnModel]
+      # @return [ActsAsTable::Headers::Hash]
+      def initialize(column_models_count, *args, &block)
+        super(*args, &block)
+
+        @column_models_count = column_models_count
+      end
+
+      # Returns this ActsAsTable headers hash object as an array.
+      #
+      # @return [Array<Array<Object>>]
+      def to_array
+        # @!method _block(acc, hash_with_column_models_count, depth)
+        #   Returns the new ActsAsTable headers hash object with accumulated ActsAsTable column models count.
+        #
+        #   @param [Array<Array<Object>>] acc
+        #   @param [ActsAsTable::Headers::Hash] hash_with_column_models_count
+        #   @param [Integer] depth
+        #   @return [ActsAsTable::Headers::Hash]
+        _block = ::Proc.new { |acc, hash_with_column_models_count, depth|
+          hash_with_column_models_count.each do |key, hash_with_column_models_count_or_column_models|
+            case hash_with_column_models_count_or_column_models
+            when ::Array
+              acc[depth] ||= []
+              acc[depth] << [key, hash_with_column_models_count_or_column_models.size]
+
+              hash_with_column_models_count_or_column_models.each do |column_model|
+                acc[depth + 1] ||= []
+                acc[depth + 1] << [column_model]
+              end
+            when ::Hash
+              acc[depth] ||= []
+              acc[depth] << [key, hash_with_column_models_count_or_column_models.column_models_count]
+
+              _block.call(acc, hash_with_column_models_count_or_column_models, depth + 1)
+            end
+          end
+
+          acc
+        }
+
+        _block.call([], self, 0)
+      end
+    end
+  end
+end