tabulard 0.2.0

data/lib/sheetah/backends/csv.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "csv"
+
+require_relative "../sheet"
+
+module Sheetah
+  module Backends
+    class Csv
+      include Sheet
+
+      class InvalidCSVError < Error
+      end
+
+      DEFAULTS = {
+        row_sep: :auto,
+        col_sep: ",",
+        quote_char: '"',
+      }.freeze
+
+      private_constant :DEFAULTS
+
+      def self.defaults
+        DEFAULTS
+      end
+
+      def initialize(
+        io,
+        row_sep: self.class.defaults[:row_sep],
+        col_sep: self.class.defaults[:col_sep],
+        quote_char: self.class.defaults[:quote_char]
+      )
+        @csv = CSV.new(
+          io,
+          row_sep: row_sep,
+          col_sep: col_sep,
+          quote_char: quote_char
+        )
+
+        @headers = detect_headers(@csv)
+        @cols_count = @headers.size
+      end
+
+      def each_header
+        return to_enum(:each_header) { @cols_count } unless block_given?
+
+        @headers.each_with_index do |header, col_idx|
+          col = Sheet.int2col(col_idx + 1)
+
+          yield Header.new(col: col, value: header)
+        end
+
+        self
+      end
+
+      def each_row
+        return to_enum(:each_row) unless block_given?
+
+        handle_malformed_csv do
+          @csv.each.with_index(1) do |raw, row|
+            value = Array.new(@cols_count) do |col_idx|
+              col = Sheet.int2col(col_idx + 1)
+
+              Cell.new(row: row, col: col, value: raw[col_idx])
+            end
+
+            yield Row.new(row: row, value: value)
+          end
+        end
+
+        self
+      end
+
+      def close
+        # Do nothing: this backend isn't responsible for opening the IO, and therefore it is not
+        # responsible for closing it either.
+      end
+
+      private
+
+      def handle_malformed_csv
+        yield
+      rescue CSV::MalformedCSVError
+        raise InvalidCSVError
+      end
+
+      def detect_headers(csv)
+        handle_malformed_csv { csv.shift } || []
+      end
+    end
+  end
+end

data/lib/sheetah/backends/wrapper.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "../sheet"
+
+module Sheetah
+  module Backends
+    class Wrapper
+      include Sheet
+
+      def initialize(table)
+        raise Error if table.nil?
+
+        @table = table
+
+        if (table_size = @table.size).positive?
+          @headers    = @table[0]
+          @rows_count = table_size - 1
+          @cols_count = @headers.size
+        else
+          @headers    = []
+          @rows_count = 0
+          @cols_count = 0
+        end
+      end
+
+      def each_header
+        return to_enum(:each_header) { @cols_count } unless block_given?
+
+        1.upto(@cols_count) do |col|
+          yield Header.new(col: Sheet.int2col(col), value: @headers[col - 1])
+        end
+
+        self
+      end
+
+      def each_row
+        return to_enum(:each_row) unless block_given?
+
+        1.upto(@rows_count) do |row|
+          raw = @table[row]
+
+          value = Array.new(@cols_count) do |col_idx|
+            Cell.new(row: row, col: Sheet.int2col(col_idx + 1), value: raw[col_idx])
+          end
+
+          yield Row.new(row: row, value: value)
+        end
+
+        self
+      end
+
+      def close
+        # nothing to do here
+      end
+    end
+  end
+end

data/lib/sheetah/backends/xlsx.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# NOTE: As reference:
+# - {Roo::Excelx::Cell#cell_value} => the "raw" value before Excel's typecasts
+# - {Roo::Excelx::Cell#value} => the "user" value, after Excel's typecasts
+require "roo"
+
+require_relative "../sheet"
+
+module Sheetah
+  module Backends
+    class Xlsx
+      include Sheet
+
+      def initialize(path)
+        raise Error if path.nil?
+
+        @roo = Roo::Excelx.new(path)
+        @is_empty = worksheet.first_row.nil?
+        @headers = detect_headers
+        @cols_count = @headers.size
+      end
+
+      def each_header
+        return to_enum(:each_header) { @cols_count } unless block_given?
+
+        @headers.each_with_index do |header, col_idx|
+          col = Sheet.int2col(col_idx + 1)
+
+          yield Header.new(col: col, value: header)
+        end
+
+        self
+      end
+
+      def each_row
+        return to_enum(:each_row) unless block_given?
+
+        return if @is_empty
+
+        first_row = 2
+        last_row = worksheet.last_row
+        row = 0
+
+        first_row.upto(last_row) do |cursor|
+          raw = worksheet.row(cursor)
+          row += 1
+
+          value = Array.new(@cols_count) do |col_idx|
+            col = Sheet.int2col(col_idx + 1)
+
+            Cell.new(row: row, col: col, value: raw[col_idx])
+          end
+
+          yield Row.new(row: row, value: value)
+        end
+
+        self
+      end
+
+      def close
+        @roo.close
+
+        nil
+      end
+
+      private
+
+      def worksheet
+        @worksheet ||= @roo.sheet_for(@roo.default_sheet)
+      end
+
+      def detect_headers
+        return [] if @is_empty
+
+        worksheet.row(1) || []
+      end
+    end
+  end
+end

data/lib/sheetah/backends.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Sheetah
+  module Backends
+    class << self
+      def open(*args, backend:, **opts, &block)
+        backend.open(*args, **opts, &block)
+      end
+    end
+  end
+end

data/lib/sheetah/column.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Sheetah
+  class Column
+    def initialize(
+      key:,
+      type:,
+      index:,
+      header:,
+      header_pattern:,
+      required:
+    )
+      @key            = key
+      @type           = type
+      @index          = index
+      @header         = header
+      @header_pattern = header_pattern
+      @required       = required
+    end
+
+    attr_reader :key,
+                :type,
+                :index,
+                :header,
+                :header_pattern
+
+    def required?
+      @required
+    end
+  end
+end

data/lib/sheetah/errors/error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Sheetah
+  module Errors
+    class Error < StandardError
+    end
+  end
+end

data/lib/sheetah/errors/spec_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module Sheetah
+  module Errors
+    class SpecError < Error
+    end
+  end
+end

data/lib/sheetah/errors/type_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module Sheetah
+  module Errors
+    class TypeError < Error
+    end
+  end
+end

data/lib/sheetah/frozen.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# :nocov: #
+
+require "sheetah"
+
+Sheetah::Types::Type.all(&:freeze)
+
+# :nocov: #

data/lib/sheetah/headers.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "set"
+require_relative "messaging/messages/invalid_header"
+require_relative "messaging/messages/duplicated_header"
+require_relative "messaging/messages/missing_column"
+
+module Sheetah
+  class Headers
+    include Utils::MonadicResult
+
+    class Header
+      def initialize(sheet_header, spec_column)
+        @header = sheet_header
+        @column = spec_column
+      end
+
+      attr_reader :header, :column
+
+      def ==(other)
+        other.is_a?(self.class) &&
+          header == other.header &&
+          column == other.column
+      end
+
+      def row_value_index
+        header.row_value_index
+      end
+    end
+
+    def initialize(specification:, messenger:)
+      @specification = specification
+      @messenger = messenger
+      @headers = []
+      @columns = Set.new
+      @failure = false
+    end
+
+    def add(header)
+      @messenger.scope_col!(header.col) do
+        column = @specification.get(header.value)
+
+        return unless add_ensure_column_is_specified(header, column)
+        return unless add_ensure_column_is_unique(header, column)
+
+        @headers << Header.new(header, column)
+      end
+    end
+
+    def result
+      missing_columns = @specification.required_columns - @columns.to_a
+
+      unless missing_columns.empty?
+        @failure = true
+
+        missing_columns.each do |column|
+          @messenger.error(
+            Messaging::Messages::MissingColumn.new(code_data: { value: column.header })
+          )
+        end
+      end
+
+      if @failure
+        Failure()
+      else
+        Success(@headers)
+      end
+    end
+
+    private
+
+    def add_ensure_column_is_specified(header, column)
+      return true unless column.nil?
+
+      unless @specification.ignore_unspecified_columns?
+        @failure = true
+        @messenger.error(
+          Messaging::Messages::InvalidHeader.new(code_data: { value: header.value })
+        )
+      end
+
+      false
+    end
+
+    def add_ensure_column_is_unique(header, column)
+      return true if @columns.add?(column)
+
+      @failure = true
+      @messenger.error(
+        Messaging::Messages::DuplicatedHeader.new(code_data: { value: header.value })
+      )
+
+      false
+    end
+  end
+end

data/lib/sheetah/messaging/config.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Sheetah
+  module Messaging
+    class Config
+      def initialize(validate_messages: default_validate_messages)
+        @validate_messages = validate_messages
+      end
+
+      attr_accessor :validate_messages
+
+      private
+
+      def default_validate_messages
+        ENV["SHEETAH_MESSAGING_VALIDATE_MESSAGES"] != "false"
+      end
+    end
+  end
+end

data/lib/sheetah/messaging/constants.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Sheetah
+  module Messaging
+    module SCOPES
+      SHEET = "SHEET"
+      ROW   = "ROW"
+      COL   = "COL"
+      CELL  = "CELL"
+    end
+
+    module SEVERITIES
+      WARN  = "WARN"
+      ERROR = "ERROR"
+    end
+  end
+end

data/lib/sheetah/messaging/message.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "constants"
+require_relative "validations"
+
+module Sheetah
+  module Messaging
+    class Message
+      include Validations
+
+      def initialize(
+        code:,
+        code_data: nil,
+        scope: SCOPES::SHEET,
+        scope_data: nil,
+        severity: SEVERITIES::WARN
+      )
+        @code        = code
+        @code_data   = code_data
+        @scope       = scope
+        @scope_data  = scope_data
+        @severity    = severity
+      end
+
+      attr_accessor(
+        :code,
+        :code_data,
+        :scope,
+        :scope_data,
+        :severity
+      )
+
+      def ==(other)
+        other.is_a?(self.class) &&
+          code       == other.code &&
+          code_data  == other.code_data &&
+          scope      == other.scope &&
+          scope_data == other.scope_data &&
+          severity   == other.severity
+      end
+
+      def to_s
+        parts = [scoping_to_s, "#{severity}: #{code}", code_data]
+        parts.compact!
+        parts.join(" ")
+      end
+
+      def to_h
+        {
+          code: code,
+          code_data: code_data,
+          scope: scope,
+          scope_data: scope_data,
+          severity: severity,
+        }
+      end
+
+      private
+
+      def scoping_to_s
+        case scope
+        when SCOPES::SHEET then "[#{scope}]"
+        when SCOPES::ROW   then "[#{scope}: #{scope_data[:row]}]"
+        when SCOPES::COL   then "[#{scope}: #{scope_data[:col]}]"
+        when SCOPES::CELL  then "[#{scope}: #{scope_data[:col]}#{scope_data[:row]}]"
+        end
+      end
+    end
+  end
+end

data/lib/sheetah/messaging/message_variant.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "message"
+
+module Sheetah
+  module Messaging
+    # While a {Message} represents any kind of message, {MessageVariant} represents any subset of
+    # messages that share the same code.
+    #
+    # The code of a message variant can and should be defined at the class level, given that it
+    # won't differ among the instances (and a validation is defined to enforce that invariant).
+    # {MessageVariant} should be considered an abstract class, and its subclasses should define
+    # their own `CODE` constant, which will be read by {.code}.
+    #
+    # As far as the other methods are concerned, {.code} should be considered the only source of
+    # truth when it comes to reading the code assigned to a message variant. The fact that {.code}
+    # is actually implemented using a dynamic resolution of the class' `CODE` constant is an
+    # implementation detail stemming from the fact that documentation tools such as YARD will
+    # highlight constants, as opposed to instance variables of a class for example. Using a constant
+    # is therefore meant to provide better documentation, and it should not be relied upon
+    # otherwise.
+    #
+    # @abstract
+    class MessageVariant < Message
+      # Reads the code assigned to the class (and its instances)
+      # @return [String]
+      def self.code
+        self::CODE
+      end
+
+      # Simplifies the initialization of a variant
+      #
+      # Contrary to the requirements of {Message#initialize}, {MessageVariant.new} doesn't require
+      # the caller to pass the `:code` keyword argument, as it is capable of prodividing it
+      # automatically (from reading {.code}).
+      def self.new(**opts)
+        super(code: code, **opts)
+      end
+
+      def_validator do
+        def validate_code(message)
+          message.code == message.class.code
+        end
+      end
+    end
+  end
+end

data/lib/sheetah/messaging/messages/cleaned_string.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "../message_variant"
+
+module Sheetah
+  module Messaging
+    module Messages
+      class CleanedString < MessageVariant
+        CODE = "cleaned_string"
+
+        def_validator do
+          cell
+          nil_code_data
+        end
+      end
+    end
+  end
+end

data/lib/sheetah/messaging/messages/duplicated_header.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "../message_variant"
+
+module Sheetah
+  module Messaging
+    module Messages
+      class DuplicatedHeader < MessageVariant
+        CODE = "duplicated_header"
+
+        def_validator do
+          col
+
+          def validate_code_data(message)
+            message.code_data in { value: String }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sheetah/messaging/messages/invalid_header.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "../message_variant"
+
+module Sheetah
+  module Messaging
+    module Messages
+      class InvalidHeader < MessageVariant
+        CODE = "invalid_header"
+
+        def_validator do
+          col
+
+          def validate_code_data(message)
+            message.code_data in { value: String }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sheetah/messaging/messages/missing_column.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "../message_variant"
+
+module Sheetah
+  module Messaging
+    module Messages
+      class MissingColumn < MessageVariant
+        CODE = "missing_column"
+
+        def_validator do
+          sheet
+
+          def validate_code_data(message)
+            message.code_data in { value: String }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sheetah/messaging/messages/must_be_array.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "../message_variant"
+
+module Sheetah
+  module Messaging
+    module Messages
+      class MustBeArray < MessageVariant
+        CODE = "must_be_array"
+
+        def_validator do
+          cell
+          nil_code_data
+        end
+      end
+    end
+  end
+end

data/lib/sheetah/messaging/messages/must_be_boolsy.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "../message_variant"
+
+module Sheetah
+  module Messaging
+    module Messages
+      class MustBeBoolsy < MessageVariant
+        CODE = "must_be_boolsy"
+
+        def_validator do
+          cell
+
+          def validate_code_data(message)
+            message.code_data in { value: String }
+          end
+        end
+      end
+    end
+  end
+end