tabulard 0.2.0

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "../../messaging/messages/must_be_email"
+require_relative "../cast"
+
+module Sheetah
+  module Types
+    module Scalars
+      class EmailCast
+        include Cast
+
+        EMAIL_REGEXP = ::URI::MailTo::EMAIL_REGEXP
+        private_constant :EMAIL_REGEXP
+
+        def initialize(email_matcher: EMAIL_REGEXP, **)
+          @email_matcher = email_matcher
+        end
+
+        def call(value, _messenger)
+          return value if @email_matcher.match?(value)
+
+          throw :failure, Messaging::Messages::MustBeEmail.new(code_data: { value: value.inspect })
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "../../errors/type_error"
+require_relative "../type"
+require_relative "scalar_cast"
+
+module Sheetah
+  module Types
+    module Scalars
+      class Scalar < Type
+        self.cast_classes += [ScalarCast]
+
+        def composite?
+          false
+        end
+
+        def composite(_value, _messenger)
+          raise Errors::TypeError, "A scalar type cannot act as a composite"
+        end
+
+        def scalar(index, value, messenger)
+          raise Errors::TypeError, "A scalar type cannot be indexed" unless index.nil?
+
+          cast_chain.call(value, messenger)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "../../utils/cell_string_cleaner"
+require_relative "../../messaging/messages/must_exist"
+require_relative "../../messaging/messages/cleaned_string"
+require_relative "../cast"
+
+module Sheetah
+  module Types
+    module Scalars
+      class ScalarCast
+        include Cast
+
+        def initialize(nullable: true, clean_string: true, **)
+          @nullable = nullable
+          @clean_string = clean_string
+        end
+
+        def call(value, messenger)
+          handle_nil(value)
+
+          handle_garbage(value, messenger)
+        end
+
+        private
+
+        def handle_nil(value)
+          return unless value.nil?
+
+          if @nullable
+            throw :success, nil
+          else
+            throw :failure, Messaging::Messages::MustExist.new
+          end
+        end
+
+        def handle_garbage(value, messenger)
+          return value unless @clean_string && value.is_a?(::String)
+
+          clean_string = Utils::CellStringCleaner.call(value)
+
+          messenger.warn(Messaging::Messages::CleanedString.new) if clean_string != value
+
+          clean_string
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "scalar"
+require_relative "../../messaging/messages/must_be_string"
+
+module Sheetah
+  module Types
+    module Scalars
+      String = Scalar.cast do |value, _messenger|
+        # value.to_s, because we want the native, underlying string when value
+        # is an instance of a String subclass
+        next value.to_s if value.is_a?(::String)
+
+        throw :failure, Messaging::Messages::MustBeString.new
+      end
+    end
+  end
+end

data/lib/sheetah/types/type.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require_relative "cast_chain"
+
+module Sheetah
+  module Types
+    class Type
+      class << self
+        def all(&block)
+          return enum_for(:all) unless block
+
+          ObjectSpace.each_object(singleton_class, &block)
+          nil
+        end
+
+        def cast_classes
+          defined?(@cast_classes) ? @cast_classes : superclass.cast_classes
+        end
+
+        attr_writer :cast_classes
+
+        def cast(cast_class = nil, &cast_block)
+          if cast_class && cast_block
+            raise ArgumentError, "Expected either a Class or a block, got both"
+          elsif !(cast_class || cast_block)
+            raise ArgumentError, "Expected either a Class or a block, got none"
+          end
+
+          type = Class.new(self)
+          type.cast_classes += [cast_class || SimpleCast.new(cast_block)]
+          type
+        end
+
+        def freeze
+          @cast_classes = cast_classes.dup unless defined?(@cast_classes)
+          @cast_classes.freeze
+          super
+        end
+
+        def new!(...)
+          new(...).freeze
+        end
+      end
+
+      self.cast_classes = []
+
+      def initialize(**opts)
+        @cast_chain = CastChain.new
+
+        self.class.cast_classes.each do |cast_class|
+          @cast_chain.append(cast_class.new(**opts))
+        end
+      end
+
+      # @private
+      attr_reader :cast_chain
+
+      def cast(...)
+        @cast_chain.call(...)
+      end
+
+      def scalar?
+        raise NoMethodError, "You must implement this method in a subclass"
+      end
+
+      def composite?
+        raise NoMethodError, "You must implement this method in a subclass"
+      end
+
+      def scalar(_index, _value, _messenger)
+        raise NoMethodError, "You must implement this method in a subclass"
+      end
+
+      def composite(_value, _messenger)
+        raise NoMethodError, "You must implement this method in a subclass"
+      end
+
+      def freeze
+        @cast_chain.freeze
+        super
+      end
+
+      # @private
+      class SimpleCast
+        def initialize(cast)
+          @cast = cast
+        end
+
+        def new(**)
+          @cast
+        end
+
+        def ==(other)
+          other.is_a?(self.class) && other.cast == cast
+        end
+
+        protected
+
+        attr_reader :cast
+      end
+    end
+  end
+end

data/lib/sheetah/utils/cell_string_cleaner.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Sheetah
+  module Utils
+    class CellStringCleaner
+      garbage = "(?:[^[:print:]]|[[:space:]])+"
+      GARBAGE_PREFIX = /\A#{garbage}/
+      GARBAGE_SUFFIX = /#{garbage}\Z/
+      private_constant :GARBAGE_PREFIX, :GARBAGE_SUFFIX
+
+      def self.call(...)
+        DEFAULT.call(...)
+      end
+
+      def call(value)
+        value = value.dup
+
+        # TODO: benchmarks
+        value.sub!(GARBAGE_PREFIX, "")
+        value.sub!(GARBAGE_SUFFIX, "")
+
+        value
+      end
+
+      DEFAULT = new.freeze
+      private_constant :DEFAULT
+    end
+  end
+end

data/lib/sheetah/utils/monadic_result.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Sheetah
+  module Utils
+    module MonadicResult
+      # {Unit} is a singleton, and is used when there is no other meaningful
+      # value that could be returned.
+      #
+      # It allows the {Result} implementation to distinguish between *a null
+      # value* (i.e. `nil`) and *the lack of a value*, to provide adequate
+      # behavior in each case.
+      #
+      # The {Result} API should not expose {Unit} directly to its consumers.
+      #
+      # @see https://en.wikipedia.org/wiki/Unit_type
+      Unit = Object.new
+
+      def Unit.to_s
+        "Unit"
+      end
+
+      def Unit.inspect
+        "Unit"
+      end
+
+      Unit.freeze
+
+      DO_TOKEN = :MonadicResultDo
+      private_constant :DO_TOKEN
+
+      module Result
+        UnwrapError  = Class.new(StandardError)
+        VariantError = Class.new(UnwrapError)
+        ValueError   = Class.new(UnwrapError)
+
+        def initialize(value = Unit)
+          @wrapped = value
+        end
+
+        def empty?
+          wrapped == Unit
+        end
+
+        def ==(other)
+          other.is_a?(self.class) && other.wrapped == wrapped
+        end
+
+        def inspect
+          if empty?
+            "#{variant}()"
+          else
+            "#{variant}(#{wrapped.inspect})"
+          end
+        end
+
+        alias to_s inspect
+
+        def discard
+          empty? ? self : self.class.new
+        end
+
+        protected
+
+        attr_reader :wrapped
+
+        private
+
+        def value
+          raise ValueError, "There is no value within the result" if empty?
+
+          wrapped
+        end
+
+        def value?
+          wrapped unless empty?
+        end
+
+        def open
+          if empty?
+            yield
+          else
+            yield wrapped
+          end
+        end
+      end
+
+      class Success
+        include Result
+
+        def success?
+          true
+        end
+
+        def failure?
+          false
+        end
+
+        def success
+          value
+        end
+
+        def failure
+          raise VariantError, "Not a Failure"
+        end
+
+        def unwrap
+          value?
+        end
+
+        alias bind open
+        public :bind
+
+        alias or itself
+
+        private
+
+        def variant
+          "Success"
+        end
+      end
+
+      class Failure
+        include Result
+
+        def success?
+          false
+        end
+
+        def failure?
+          true
+        end
+
+        def success
+          raise VariantError, "Not a Success"
+        end
+
+        def failure
+          value
+        end
+
+        def unwrap
+          throw DO_TOKEN, self
+        end
+
+        alias bind itself
+
+        alias or open
+        public :or
+
+        private
+
+        def variant
+          "Failure"
+        end
+      end
+
+      # rubocop:disable Naming/MethodName
+
+      def Success(...)
+        Success.new(...)
+      end
+
+      def Failure(...)
+        Failure.new(...)
+      end
+
+      def Do(&block)
+        catch(DO_TOKEN, &block)
+      end
+
+      # rubocop:enable Naming/MethodName
+    end
+  end
+end

data/lib/sheetah.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# {Sheetah} is a library designed to process tabular data according to a
+# {Sheetah::Template developer-defined structure}. It will turn each row into a
+# object whose keys and types are specified by the structure.
+#
+# It can work with tabular data presented in different formats by delegating
+# the parsing of documents to specialized backends
+# ({Sheetah::Backends::Xlsx}, {Sheetah::Backends::Csv}, etc...).
+#
+# Given a tabular document and a specification of the document structure,
+# Sheetah may process the document by handling the following tasks:
+#
+# - validation of the document's actual structure
+# - arbitrary complex typecasting of each row into a validated object,
+#   according to the document specification
+# - fine-grained error handling (at the sheet/row/col/cell level)
+# - all of the above done so that internationalization of messages is easy
+#
+# Sheetah is designed with memory efficiency in mind by processing documents
+# one row at a time, thus not requiring parsing and loading the whole document
+# in memory upfront (depending on the backend). The memory consumption of the
+# library should therefore theoretically stay stable during the processing of a
+# document, disregarding how many rows it may have.
+module Sheetah
+end
+
+require "sheetah/template"
+require "sheetah/template_config"
+require "sheetah/sheet_processor"
+require "sheetah/backends/wrapper"

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: tabulard
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Erwan Thomas
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-06-05 00:00:00.000000000 Z
+dependencies: []
+description:
+email:
+- id@maen.fr
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- VERSION
+- lib/sheetah.rb
+- lib/sheetah/attribute.rb
+- lib/sheetah/attribute_types.rb
+- lib/sheetah/attribute_types/composite.rb
+- lib/sheetah/attribute_types/scalar.rb
+- lib/sheetah/attribute_types/value.rb
+- lib/sheetah/attribute_types/value.rb.orig
+- lib/sheetah/backends.rb
+- lib/sheetah/backends/csv.rb
+- lib/sheetah/backends/wrapper.rb
+- lib/sheetah/backends/xlsx.rb
+- lib/sheetah/column.rb
+- lib/sheetah/errors/error.rb
+- lib/sheetah/errors/spec_error.rb
+- lib/sheetah/errors/type_error.rb
+- lib/sheetah/frozen.rb
+- lib/sheetah/headers.rb
+- lib/sheetah/messaging.rb
+- lib/sheetah/messaging/config.rb
+- lib/sheetah/messaging/constants.rb
+- lib/sheetah/messaging/message.rb
+- lib/sheetah/messaging/message_variant.rb
+- lib/sheetah/messaging/messages/cleaned_string.rb
+- lib/sheetah/messaging/messages/duplicated_header.rb
+- lib/sheetah/messaging/messages/invalid_header.rb
+- lib/sheetah/messaging/messages/missing_column.rb
+- lib/sheetah/messaging/messages/must_be_array.rb
+- lib/sheetah/messaging/messages/must_be_boolsy.rb
+- lib/sheetah/messaging/messages/must_be_date.rb
+- lib/sheetah/messaging/messages/must_be_email.rb
+- lib/sheetah/messaging/messages/must_be_string.rb
+- lib/sheetah/messaging/messages/must_exist.rb
+- lib/sheetah/messaging/messages/sheet_error.rb
+- lib/sheetah/messaging/messenger.rb
+- lib/sheetah/messaging/validations.rb
+- lib/sheetah/messaging/validations/base_validator.rb
+- lib/sheetah/messaging/validations/dsl.rb
+- lib/sheetah/messaging/validations/invalid_message.rb
+- lib/sheetah/messaging/validations/mixins.rb
+- lib/sheetah/row_processor.rb
+- lib/sheetah/row_processor_result.rb
+- lib/sheetah/row_value_builder.rb
+- lib/sheetah/sheet.rb
+- lib/sheetah/sheet/col_converter.rb
+- lib/sheetah/sheet_processor.rb
+- lib/sheetah/sheet_processor_result.rb
+- lib/sheetah/specification.rb
+- lib/sheetah/template.rb
+- lib/sheetah/template_config.rb
+- lib/sheetah/types/cast.rb
+- lib/sheetah/types/cast_chain.rb
+- lib/sheetah/types/composites/array.rb
+- lib/sheetah/types/composites/array_compact.rb
+- lib/sheetah/types/composites/composite.rb
+- lib/sheetah/types/container.rb
+- lib/sheetah/types/scalars/boolsy.rb
+- lib/sheetah/types/scalars/boolsy_cast.rb
+- lib/sheetah/types/scalars/date_string.rb
+- lib/sheetah/types/scalars/date_string_cast.rb
+- lib/sheetah/types/scalars/email.rb
+- lib/sheetah/types/scalars/email_cast.rb
+- lib/sheetah/types/scalars/scalar.rb
+- lib/sheetah/types/scalars/scalar_cast.rb
+- lib/sheetah/types/scalars/string.rb
+- lib/sheetah/types/type.rb
+- lib/sheetah/utils/cell_string_cleaner.rb
+- lib/sheetah/utils/monadic_result.rb
+homepage: https://github.com/tabulard/tabulard
+licenses:
+- Apache-2.0
+metadata:
+  source_code_uri: https://github.com/tabulard/tabulard
+  bug_tracker_uri: https://github.com/tabulard/tabulard/issues
+  changelog_uri: https://github.com/tabulard/tabulard/blob/master/CHANGELOG.md
+  documentation_uri: https://github.com/tabulard/tabulard/blob/master/README.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: A highly-customizable tabular data processor
+test_files: []