tabulard 0.2.0

data/lib/sheetah/sheet.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "sheet/col_converter"
+require_relative "errors/error"
+require_relative "messaging/messages/sheet_error"
+require_relative "utils/monadic_result"
+
+module Sheetah
+  module Sheet
+    def self.included(mod)
+      mod.extend(ClassMethods)
+    end
+
+    def self.col2int(...)
+      COL_CONVERTER.col2int(...)
+    end
+
+    def self.int2col(...)
+      COL_CONVERTER.int2col(...)
+    end
+
+    module ClassMethods
+      def open(*args, **opts)
+        handle_sheet_error do
+          sheet = new(*args, **opts)
+          next sheet unless block_given?
+
+          begin
+            yield sheet
+          ensure
+            sheet.close
+          end
+        end
+      end
+
+      private
+
+      def handle_sheet_error
+        Utils::MonadicResult::Success.new(yield)
+      rescue Error => e
+        Utils::MonadicResult::Failure.new(e)
+      end
+    end
+
+    class Error < Errors::Error
+      def to_message
+        Messaging::Messages::SheetError.new
+      end
+    end
+
+    class Header
+      def initialize(col:, value:)
+        @col = col
+        @value = value
+      end
+
+      attr_reader :col, :value
+
+      def ==(other)
+        other.is_a?(self.class) && col == other.col && value == other.value
+      end
+
+      def row_value_index
+        Sheet.col2int(col) - 1
+      end
+    end
+
+    class Row
+      def initialize(row:, value:)
+        @row = row
+        @value = value
+      end
+
+      attr_reader :row, :value
+
+      def ==(other)
+        other.is_a?(self.class) && row == other.row && value == other.value
+      end
+    end
+
+    class Cell
+      def initialize(row:, col:, value:)
+        @row = row
+        @col = col
+        @value = value
+      end
+
+      attr_reader :row, :col, :value
+
+      def ==(other)
+        other.is_a?(self.class) && row == other.row && col == other.col && value == other.value
+      end
+    end
+
+    def each_header
+      raise NoMethodError, "You must implement #{self.class}#each_header => self"
+    end
+
+    def each_row
+      raise NoMethodError, "You must implement #{self.class}#each_row => self"
+    end
+
+    def close
+      raise NoMethodError, "You must implement #{self.class}#close => nil"
+    end
+  end
+end

data/lib/sheetah/sheet_processor.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "backends"
+require_relative "headers"
+require_relative "messaging"
+require_relative "row_processor"
+require_relative "sheet"
+require_relative "sheet_processor_result"
+require_relative "utils/monadic_result"
+
+module Sheetah
+  class SheetProcessor
+    include Utils::MonadicResult
+
+    def initialize(specification)
+      @specification = specification
+    end
+
+    def call(*args, **opts)
+      messenger = Messaging::Messenger.new
+
+      result = Do() do
+        Backends.open(*args, **opts) do |sheet|
+          row_processor = build_row_processor(sheet, messenger)
+
+          sheet.each_row do |row|
+            yield row_processor.call(row)
+          end
+        end
+      end
+
+      handle_result(result, messenger)
+    end
+
+    private
+
+    def parse_headers(sheet, messenger)
+      headers = Headers.new(specification: @specification, messenger: messenger)
+
+      sheet.each_header do |header|
+        headers.add(header)
+      end
+
+      headers.result
+    end
+
+    def build_row_processor(sheet, messenger)
+      headers = parse_headers(sheet, messenger).unwrap
+
+      RowProcessor.new(headers: headers, messenger: messenger)
+    end
+
+    def handle_result(result, messenger)
+      result.or do |failure|
+        messenger.error(failure.to_message) if failure.respond_to?(:to_message)
+      end
+
+      SheetProcessorResult.new(result: result.discard, messages: messenger.messages)
+    end
+  end
+end

data/lib/sheetah/sheet_processor_result.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Sheetah
+  class SheetProcessorResult
+    def initialize(result:, messages: [])
+      @result = result
+      @messages = messages
+    end
+
+    attr_reader :result, :messages
+
+    def ==(other)
+      other.is_a?(self.class) &&
+        result == other.result &&
+        messages == other.messages
+    end
+  end
+end

data/lib/sheetah/specification.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Sheetah
+  class Specification
+    def initialize(columns:, ignore_unspecified_columns: false)
+      @columns = columns
+      @ignore_unspecified_columns = ignore_unspecified_columns
+    end
+
+    def get(header)
+      return if header.nil?
+
+      @columns.find do |column|
+        column.header_pattern.match?(header)
+      end
+    end
+
+    def required_columns
+      @columns.select(&:required?)
+    end
+
+    def optional_columns
+      @columns.reject(&:required?)
+    end
+
+    def ignore_unspecified_columns?
+      @ignore_unspecified_columns
+    end
+  end
+end

data/lib/sheetah/template.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "set"
+require_relative "attribute"
+require_relative "specification"
+require_relative "errors/spec_error"
+
+module Sheetah
+  # A {Template} represents the abstract structure of a tabular document.
+  #
+  # The main component of the structure is the object obtained by processing a
+  # row. A template therefore specifies all possible attributes of that object
+  # as a list of (key, abstract type) pairs.
+  #
+  # Each attribute will eventually be compiled into as many concrete columns as
+  # necessary with the help of a {TemplateConfig config} to produce a
+  # {Specification specification}.
+  #
+  # In other words, a {Template} specifies the structure of the processing
+  # result (its attributes), whereas a {Specification} specifies the columns
+  # that may be involved into building the processing result.
+  #
+  # {Attribute Attributes} may either be _composite_ (their value is a
+  # composition of multiple values) or _scalar_ (their value is a single
+  # value). Scalar attributes will thus produce a single column in the
+  # specification, and composite attributes will produce as many columns as
+  # required by the number of scalar values they hold.
+  class Template
+    def self.build(attributes:, **kwargs)
+      attributes = attributes.map { |attribute| Attribute.build(**attribute) }
+      attributes.freeze
+
+      template = new(attributes: attributes, **kwargs)
+      template.freeze
+    end
+
+    def initialize(attributes:, ignore_unspecified_columns: false)
+      ensure_attributes_unicity(attributes)
+
+      @attributes = attributes
+      @ignore_unspecified_columns = ignore_unspecified_columns
+    end
+
+    def apply(config)
+      columns = []
+
+      attributes.each do |attribute|
+        attribute.each_column(config) do |column|
+          columns << column.freeze
+        end
+      end
+
+      specification = Specification.new(
+        columns: columns.freeze,
+        ignore_unspecified_columns: ignore_unspecified_columns
+      )
+
+      specification.freeze
+    end
+
+    def ==(other)
+      other.is_a?(self.class) &&
+        attributes == other.attributes &&
+        ignore_unspecified_columns == other.ignore_unspecified_columns
+    end
+
+    protected
+
+    attr_reader :attributes, :ignore_unspecified_columns
+
+    private
+
+    def ensure_attributes_unicity(attributes)
+      keys = Set.new
+
+      duplicate = attributes.find do |attribute|
+        !keys.add?(attribute.key)
+      end
+
+      return unless duplicate
+
+      raise Errors::SpecError, "Duplicated key: #{duplicate.key.inspect}"
+    end
+  end
+end

data/lib/sheetah/template_config.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "types/container"
+
+module Sheetah
+  class TemplateConfig
+    def initialize(types: Types::Container.new)
+      @types = types
+    end
+
+    attr_reader :types
+
+    # Given an attribute key and a possibily-nil column index, return the header and header pattern
+    # for that column.
+    #
+    # The return value should be an array with two items:
+    #
+    # 1. The first item is the header, as a String.
+    # 2. The second item is the header pattern, and should respond to `#match?` with a boolean
+    #     value. Instances of Regexp will obviously do, but the requirement is really about the
+    #     `#match?` method.
+    #
+    # @param key [Symbol, String]
+    # @param index [Integer, nil]
+    # @return [Array(String, #match?)]
+    def header(key, index)
+      header = key.to_s.capitalize
+      header = "#{header} #{index + 1}" if index
+
+      pattern = /^#{Regexp.escape(header)}$/i
+
+      [header, pattern]
+    end
+  end
+end

data/lib/sheetah/types/cast.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Sheetah
+  module Types
+    # @private
+    module Cast
+      def ==(other)
+        other.is_a?(self.class) && other.config == config
+      end
+
+      protected
+
+      def config
+        instance_variables.each_with_object({}) do |ivar, acc|
+          acc[ivar] = instance_variable_get(ivar)
+        end
+      end
+    end
+  end
+end

data/lib/sheetah/types/cast_chain.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "../utils/monadic_result"
+
+module Sheetah
+  module Types
+    class CastChain
+      include Utils::MonadicResult
+
+      def initialize(casts = [])
+        @casts = casts
+      end
+
+      attr_reader :casts
+
+      def prepend(cast)
+        @casts.unshift(cast)
+        self
+      end
+
+      def append(cast)
+        @casts.push(cast)
+        self
+      end
+
+      def freeze
+        @casts.each(&:freeze)
+        @casts.freeze
+        super
+      end
+
+      def call(value, messenger)
+        failure = catch(:failure) do
+          success = catch(:success) do
+            @casts.reduce(value) do |prev_value, cast|
+              cast.call(prev_value, messenger)
+            end
+          end
+
+          return Success(success)
+        end
+
+        messenger.error(failure) if failure
+
+        Failure()
+      end
+    end
+  end
+end

data/lib/sheetah/types/composites/array.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "composite"
+require_relative "../../messaging/messages/must_be_array"
+
+module Sheetah
+  module Types
+    module Composites
+      Array = Composite.cast do |value, _messenger|
+        throw :failure, Messaging::Messages::MustBeArray.new unless value.is_a?(::Array)
+
+        value
+      end
+    end
+  end
+end

data/lib/sheetah/types/composites/array_compact.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "array"
+
+module Sheetah
+  module Types
+    module Composites
+      ArrayCompact = Array.cast do |value, _messenger|
+        value.compact
+      end
+    end
+  end
+end

data/lib/sheetah/types/composites/composite.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "../../errors/type_error"
+require_relative "../type"
+
+module Sheetah
+  module Types
+    module Composites
+      class Composite < Type
+        def initialize(types, **opts)
+          super(**opts)
+
+          @types = types
+        end
+
+        def composite?
+          true
+        end
+
+        def scalar(index, value, messenger)
+          if (type = @types[index])
+            type.scalar(nil, value, messenger)
+          else
+            raise Errors::TypeError, "Invalid index: #{index.inspect}"
+          end
+        end
+
+        alias composite cast
+      end
+    end
+  end
+end

data/lib/sheetah/types/container.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "../errors/type_error"
+
+require_relative "scalars/scalar"
+require_relative "scalars/string"
+require_relative "scalars/email"
+require_relative "scalars/boolsy"
+require_relative "scalars/date_string"
+require_relative "composites/array"
+require_relative "composites/array_compact"
+
+module Sheetah
+  module Types
+    class Container
+      scalar      = Scalars::Scalar.new!
+      string      = Scalars::String.new!
+      email       = Scalars::Email.new!
+      boolsy      = Scalars::Boolsy.new!
+      date_string = Scalars::DateString.new!
+
+      DEFAULTS = {
+        scalars: {
+          scalar:      -> { scalar },
+          string:      -> { string },
+          email:       -> { email  },
+          boolsy:      -> { boolsy },
+          date_string: -> { date_string },
+        }.freeze,
+        composites: {
+          array:         ->(types) { Composites::Array.new!(types) },
+          array_compact: ->(types) { Composites::ArrayCompact.new!(types) },
+        }.freeze,
+      }.freeze
+
+      def initialize(scalars: nil, composites: nil, defaults: DEFAULTS)
+        @scalars =
+          (scalars ? defaults[:scalars].merge(scalars) : defaults[:scalars]).freeze
+
+        @composites =
+          (composites ? defaults[:composites].merge(composites) : defaults[:composites]).freeze
+      end
+
+      def scalars
+        @scalars.keys
+      end
+
+      def composites
+        @composites.keys
+      end
+
+      def scalar(scalar_name)
+        builder = fetch_scalar_builder(scalar_name)
+
+        builder.call
+      end
+
+      def composite(composite_name, scalar_names)
+        builder = fetch_composite_builder(composite_name)
+
+        scalars = scalar_names.map { |scalar_name| scalar(scalar_name) }
+
+        builder.call(scalars)
+      end
+
+      private
+
+      def fetch_scalar_builder(type)
+        @scalars.fetch(type) do
+          raise Errors::TypeError, "Invalid scalar type: #{type.inspect}"
+        end
+      end
+
+      def fetch_composite_builder(type)
+        @composites.fetch(type) do
+          raise Errors::TypeError, "Invalid composite type: #{type.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/sheetah/types/scalars/boolsy.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "scalar"
+require_relative "boolsy_cast"
+
+module Sheetah
+  module Types
+    module Scalars
+      Boolsy = Scalar.cast(BoolsyCast)
+    end
+  end
+end

data/lib/sheetah/types/scalars/boolsy_cast.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "../../messaging/messages/must_be_boolsy"
+require_relative "../cast"
+
+module Sheetah
+  module Types
+    module Scalars
+      class BoolsyCast
+        include Cast
+
+        TRUTHY = [].freeze
+        FALSY  = [].freeze
+        private_constant :TRUTHY, :FALSY
+
+        def initialize(truthy: TRUTHY, falsy: FALSY, **)
+          @truthy = truthy
+          @falsy  = falsy
+        end
+
+        def call(value, _messenger)
+          if @truthy.include?(value)
+            true
+          elsif @falsy.include?(value)
+            false
+          else
+            throw :failure, Messaging::Messages::MustBeBoolsy.new(
+              code_data: { value: value.inspect }
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sheetah/types/scalars/date_string.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "scalar"
+require_relative "date_string_cast"
+
+module Sheetah
+  module Types
+    module Scalars
+      DateString = Scalar.cast(DateStringCast)
+    end
+  end
+end

data/lib/sheetah/types/scalars/date_string_cast.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "date"
+require_relative "../../messaging/messages/must_be_date"
+require_relative "../cast"
+
+module Sheetah
+  module Types
+    module Scalars
+      class DateStringCast
+        include Cast
+
+        DATE_FMT = "%Y-%m-%d"
+        private_constant :DATE_FMT
+
+        def initialize(date_fmt: DATE_FMT, accept_date: true, **)
+          @date_fmt = date_fmt
+          @accept_date = accept_date
+        end
+
+        def call(value, _messenger)
+          case value
+          when ::Date
+            return value if @accept_date
+          when ::String
+            date = parse_date_string(value)
+            return date if date
+          end
+
+          throw :failure, Messaging::Messages::MustBeDate.new(code_data: { format: @date_fmt })
+        end
+
+        private
+
+        def parse_date_string(value)
+          ::Date.strptime(value, @date_fmt)
+        rescue ::TypeError, ::Date::Error
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/sheetah/types/scalars/email.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "string"
+require_relative "email_cast"
+
+module Sheetah
+  module Types
+    module Scalars
+      Email = String.cast(EmailCast)
+    end
+  end
+end